asctime_s, _wasctime_s

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

Sintaxis

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

Parámetros

buffer
Puntero a un búfer para almacenar el resultado de la cadena de caracteres. Esta función presupone un puntero a una ubicación de memoria válida con un tamaño especificado por numberOfElements.

numberOfElements
Tamaño del búfer usado para almacenar el resultado.

tmSource
Estructura de fecha y hora. Esta función presupone un puntero a un objeto válido struct tm.

Valor devuelto

Cero si es correcta. Si se produce un error, se invoca el controlador de parámetros no válidos, 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, consulte errno constantes. Los códigos de error reales devueltos para cada condición de error se muestran en la tabla siguiente.

Condiciones de error

buffer	numberOfElements	tmSource	Return	Valor de buffer
NULL	Any	Any	EINVAL	No modificado
No NULL (apunta a la memoria válida)	0	Cualquiera	EINVAL	No modificado
No NULL	0<numberOfElements< 26	Cualquiera	EINVAL	Cadena vacía
No NULL	>= 26	NULL	EINVAL	Cadena vacía
No NULL	>= 26	Estructura de hora no válida o valores fuera del intervalo para los componentes del tiempo	EINVAL	Cadena vacía

Nota:

Las condiciones de error de wasctime_s son similares a asctime_s con la excepción de que el límite de tamaño se mide en palabras.

Comentarios

La función asctime convierte una hora almacenada como estructura en una cadena de caracteres. Normalmente, el tmSource valor se obtiene de una llamada a gmtime o localtime. Ambas funciones se pueden usar para rellenar una estructura tm, tal y como se define en TIME.H.

miembro de timeptr	Valor
tm_hour	Horas desde la medianoche (0-23).
tm_isdst	Positivo si el horario de verano está en vigor; 0 si el horario de verano no está en vigor; negativo si se desconoce el estado del horario de verano. La biblioteca en tiempo de ejecución de C usa las reglas de Estados Unidos para implementar el cálculo del horario de verano (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 del 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)

La cadena de caracteres convertidos también se ajusta en función de la configuración de zona horaria local. Para obtener información sobre cómo configurar la hora local, vea las funciones , _ftime32_time64_ftime_time32_ftime64ylocaltime_s , . _localtime32_s_localtime64_stime Para obtener información sobre cómo definir el entorno de zona horaria y las variables globales, vea _tzset.

El resultado de cadena que asctime_s genera contiene exactamente 26 caracteres y tiene el formato Wed Jan 2 02:03:55 1980\n\0. Se usa un reloj de 24 horas. Todos los campos tienen un ancho constante. El carácter de nueva línea y el carácter nulo ocupan las dos últimas posiciones de la cadena. El valor pasado como numberOfElements debe ser al menos este tamaño. Si es menor, se devolverá un código de error, EINVAL, .

_wasctime_s es una versión con caracteres anchos de asctime_s. Por lo demás,_wasctime_s y asctime_s se comportan de forma idéntica.

Las versiones de la biblioteca de depuración de estas funciones rellenan primero el búfer con 0xFE. Para deshabilitar este comportamiento, use _CrtSetDebugFillThreshold.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Asignación de rutina de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tasctime_s	asctime_s	asctime_s	_wasctime_s

En C++, el uso de estas funciones se simplifica mediante sobrecargas de plantilla. Las sobrecargas pueden deducir la longitud del búfer automáticamente, lo que elimina la necesidad de especificar un argumento de tamaño. Para obtener más información, consulte Sobrecargas de plantillas seguras.

Requisitos

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

Seguridad

Si el puntero del búfer no NULL es y el puntero no apunta a un búfer válido, la función sobrescribirá lo que esté en la ubicación. Este error también puede provocar una infracción de acceso.

Puede producirse una saturación del búfer si el argumento de tamaño que se pasa es mayor que el tamaño real del búfer.

Ejemplo

Este programa coloca la hora del sistema en el entero aclocklargo , lo traduce en la estructura newtimey, a continuación, lo convierte en forma de cadena para la salida, mediante la asctime_s función .

// 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;
}

Current date and time: Wed May 14 15:30:17 2003

Consulte también

Administración de tiempo
ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s
_ftime, _ftime32, _ftime64
gmtime_s, _gmtime32_s, _gmtime64_s
localtime_s, _localtime32_s, _localtime64_s
time, _time32, _time64
_tzset