asctime_s, _wasctime_s

Artículo
04/10/2013

Convierte una estructura en tiempo de tm a una cadena de caracteres.Estas funciones son versiones de asctime, _wasctime con mejoras de seguridad como se describe en Características de seguridad en CRT.

errno_t asctime_s( 
   char* buffer,
   size_t numberOfElements,
   const struct tm *_tm 
);
errno_t _wasctime_s( 
   wchar_t* buffer,
   size_t numberOfElements
   const struct tm *_tm 
);
template <size_t size>
errno_t asctime_s( 
   char (&buffer)[size],
   const struct tm *_tm 
); // C++ only
template <size_t size>
errno_t _wasctime_s( 
   wchar_t (&buffer)[size],
   const struct tm *_tm 
); // C++ only

Parámetros

buffer
[out] un puntero a un búfer para almacenar el resultado de la cadena de caracteres.Esta función utiliza un puntero a una ubicación de memoria válida con un tamaño especificado por numberOfElements.
numberOfElements
[in] El tamaño del búfer usado para almacenar el resultado.
_tm
[in] Estructura de hora o de fecha.Esta función utiliza un puntero a un objeto válido de structtm .

Valor devuelto

cero si correctamente.Si hay un error, se invoca el controlador no válido de parámetro, tal y como se describe en Validación de parámetros.Si la ejecución puede continuar, el valor devuelto es un código de error.Los códigos de error se definen en ERRNO.H.Para obtener más información, vea constantes de errno.los códigos de error reales devueltos para cada condición de error se muestran en la tabla siguiente.

condiciones de error

buffer	numberOfElements	tm	Return	Valor de buffer
NULL	Cualquiera	Cualquiera	EINVAL	no modificado
NoNULL (señala memoria válido)	0	Cualquiera	EINVAL	no modificado
no NULL	0< tamaño < 26	Cualquiera	EINVAL	Cadena vacía
no NULL	>= 26	NULL	EINVAL	Cadena vacía
no NULL	>= 26	Estructura no válida del tiempo o por valores de intervalo para los componentes de tiempo	EINVAL	Cadena vacía

[!NOTA]

Las condiciones de error para wasctime_s son similares a asctime_s excepto que el límite de tamaño se mide en palabras.

Comentarios

La función de asctime convierte una hora almacenada como una estructura a una cadena de caracteres.El valor de _tm se obtiene normalmente de una llamada a gmtime o a localtime.ambas funciones se pueden utilizar para completar una estructura de tm , como definido en TIME.H.

miembro del timeptr	Valor
tm_hour	horas desde la medianoche (0-23)
tm_isdst	Positivo si el horario de verano está vigente; 0 si el horario de verano no está vigente; negativa si el estado de horario de verano es desconocido.La biblioteca en tiempo de ejecución de C supone las reglas de los Estados Unidos para implementar el cálculo en tiempo de Daylight Guardar (DST).
tm_mday	Día del mes (1-31)
tm_min	minutos después de la hora (0-59)
tm_mon	mes (0-11; enero = 0)
tm_sec	Segundos después de minuto (0-59)
tm_wday	día de la semana (0-6; domingo = 0)
tm_yday	Día del año (0-365; 1 de enero = 0)
tm_year	Año (año actual menos 1900)

Cadena de caracteres convierte también se ajusta según la configuración de zonas de la hora local.Vea time, _time32, _time64, _ftime, _ftime32, _ftime64, y las funciones de localtime_s, _localtime32_s, _localtime64_s para obtener información sobre la configuración de la hora local y la función de _tzset para obtener información sobre la definición del entorno y las variables globales de la zona horaria.

El resultado de la cadena generado por asctime_s contiene exactamente 26 caracteres y tiene el formato Wed Jan 02 02:03:55 1980\n\0.se utiliza un reloj de 24 horas.todos los campos tienen un ancho constante.El carácter de nueva línea y el carácter null ocupan las dos últimas posiciones de la cadena.El valor pasado como segundo parámetro debe ser por lo menos éste grande.Si es menor, un código de error, EINVAL, se devolverá.

_wasctime_s es una versión con caracteres anchos de asctime_s._wasctime_s y asctime_s se comportan exactamente igual de otra manera.

Asignación rutinaria de texto genérico

rutina de TCHAR.H	_UNICODE y _MBCS no definido	_MBCS definido	_UNICODE definido
_tasctime_s	asctime_s	asctime_s	_wasctime_s

En C++, mediante estas funciones es simplificado con sobrecargas de plantilla; las sobrecargas pueden deducir longitud de búfer automáticamente, lo que elimina la necesidad de especificar un argumento size.Para obtener más información, vea Sobrecargas de plantilla de seguridad.

Requisitos

rutina	Encabezado necesario
asctime_s	<time.h>
_wasctime_s	<time.h> o <wchar.h>

Seguridad

Si el puntero de búfer no es NULL y el puntero no señala a un búfer válido, la función sobrescribirá lo que haya en la ubicación.Esto puede dar lugar a una infracción de acceso.

saturación del búfer puede producirse si el argumento de tamaño pasado es mayor que el tamaño real del búfer.

Ejemplo

Este programa coloca la hora del sistema en aclockentero largo, la convierte en la estructura newtime y la convierte al formato de cadena para la salida, mediante la función de asctime_s .

// crt_asctime_s.c
#include <time.h>
#include <stdio.h>

struct tm newtime;
__time32_t aclock;

int main( void )
{
   char buffer[32];
   errno_t errNum;
   _time32( &aclock );   // Get time in seconds.
   _localtime32_s( &newtime, &aclock );   // Convert time to struct tm form.

   // Print local time as a string.

   errNum = asctime_s(buffer, 32, &newtime);
   if (errNum)
   {
       printf("Error code: %d", (int)errNum);
       return 1;
   }
   printf( "Current date and time: %s", buffer );
   return 0;
}