asctime_s, _wasctime_sasctime_s, _wasctime_s

Convierte una estructura de tiempo de TM en una cadena de caracteres.Convert a tm time structure to a character string. Estas funciones son versiones de asctime, _wasctime con mejoras de seguridad, tal y como se describe en Características de seguridad de CRT.These functions are versions of asctime, _wasctime with security enhancements as described in Security Features in the CRT.

SintaxisSyntax

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ámetrosParameters

búferbuffer
Un puntero a un búfer para almacenar el resultado de la cadena de caracteres.A pointer to a buffer to store the character string result. Esta función presupone un puntero a una ubicación de memoria válida con un tamaño especificado por numberOfElements.This function assumes a pointer to a valid memory location with a size specified by numberOfElements.

numberOfElementsnumberOfElements
Tamaño del búfer usado para almacenar el resultado.The size of the buffer used to store the result.

tmSourcetmSource
Estructura de fecha y hora.Time/date structure. Esta función presupone un puntero a un objeto struct TM válido.This function assumes a pointer to a valid struct tm object.

Valor devueltoReturn Value

Cero si es correcto.Zero if successful. Si hay un error, se invoca al controlador de parámetros no válidos, tal y como se describe en Validación de parámetros.If there is a failure, the invalid parameter handler is invoked, as described in Parameter Validation. Si la ejecución puede continuar, el valor devuelto es un código de error.If execution is allowed to continue, the return value is an error code. Los códigos de error se definen en ERRNO.H.Error codes are defined in ERRNO.H. Para obtener más información, consulte errno (Constantes).For more information, see errno Constants. Los códigos de error reales devueltos para cada condición de error se muestran en la tabla siguiente.The actual error codes returned for each error condition are shown in the following table.

Condiciones de errorError Conditions

búferbuffer numberOfElementsnumberOfElements tmSourcetmSource Valor devueltoReturn Valor en búferValue in buffer
NULLNULL AnyAny AnyAny EINVALEINVAL No modificadoNot modified
Not null (apunta a la memoria válida)Not NULL (points to valid memory) 00 AnyAny EINVALEINVAL No modificadoNot modified
No nullNot NULL 0< tamaño < 260< size < 26 AnyAny EINVALEINVAL cadena vacía.Empty string
No nullNot NULL >= 26>= 26 NULLNULL EINVALEINVAL cadena vacía.Empty string
No nullNot NULL >= 26>= 26 Estructura de hora no válida o valores fuera del intervalo para los componentes del tiempoInvalid time structure or out of range values for components of the time EINVALEINVAL cadena vacía.Empty string

Nota

Las condiciones de error para wasctime_s son similares a asctime_s con la excepción de que el límite de tamaño se mide en palabras.Error conditions for wasctime_s are similar to asctime_s with the exception that the size limit is measured in words.

ObservacionesRemarks

La función asctime convierte una hora almacenada como una estructura en una cadena de caracteres.The asctime function converts a time stored as a structure to a character string. El valor tmSource se suele obtener de una llamada a gmtime o localtime.The tmSource value is usually obtained from a call to gmtime or localtime. Ambas funciones se pueden usar para rellenar una estructura de TM , tal y como se define en el tiempo. C.Both functions can be used to fill in a tm structure, as defined in TIME.H.

miembro de timeptrtimeptr member ValueValue
tm_hourtm_hour Horas desde la medianoche (0-23)Hours since midnight (0-23)
tm_isdsttm_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.Positive if daylight saving time is in effect; 0 if daylight saving time is not in effect; negative if status of daylight saving time is unknown. 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).The C run-time library assumes the United States' rules for implementing the calculation of Daylight Saving Time (DST).
tm_mdaytm_mday Día del mes (1-31)Day of month (1-31)
tm_mintm_min Minutos después de la hora (0-59)Minutes after hour (0-59)
tm_montm_mon Mes (0-11; Enero = 0)Month (0-11; January = 0)
tm_sectm_sec Segundos después del minuto (0-59)Seconds after minute (0-59)
tm_wdaytm_wday Día de la semana (0-6; Sunday = 0)Day of week (0-6; Sunday = 0)
tm_ydaytm_yday Día del año (0-365; 1 de enero = 0)Day of year (0-365; January 1 = 0)
tm_yeartm_year Año (año actual menos 1900)Year (current year minus 1900)

La cadena de caracteres convertidos también se ajusta en función de la configuración de zona horaria local.The converted character string is also adjusted according to the local time zone settings. Vea las funciones time, _time32, _time64, _ftime, _ftime32, _ftime64 y localtime_s, _localtime32_s, _localtime64_s para obtener información sobre cómo configurar la hora local y la función _tzset para obtener información sobre cómo definir el entorno de zona horaria y variables globales.See the time, _time32, _time64, _ftime, _ftime32, _ftime64, and localtime_s, _localtime32_s, _localtime64_s functions for information about configuring the local time and the _tzset function for information about defining the time zone environment and global variables.

El resultado de la cadena producido por asctime_s contiene exactamente 26 caracteres y tiene el formato Wed Jan 02 02:03:55 1980\n\0 .The string result produced by asctime_s contains exactly 26 characters and has the form Wed Jan 02 02:03:55 1980\n\0. Se usa un reloj de 24 horas.A 24-hour clock is used. Todos los campos tienen un ancho constante.All fields have a constant width. El carácter de nueva línea y el carácter nulo ocupan las dos últimas posiciones de la cadena.The new line character and the null character occupy the last two positions of the string. El valor que se pase como segundo parámetro debe ser al menos igual de grande.The value passed in as the second parameter should be at least this big. Si es menor, se devolverá un código de error, EINVAL.If it is less, an error code, EINVAL, will be returned.

_wasctime_s es una versión con caracteres anchos de asctime_s._wasctime_s is a wide-character version of asctime_s. _wasctime_s y asctime_s se comportan de manera idéntica._wasctime_s and asctime_s behave identically otherwise.

Las versiones de la biblioteca de depuración de estas funciones rellenan primero el búfer con 0xFE.The debug library versions of these functions first fill the buffer with 0xFE. Para deshabilitar este comportamiento, use _CrtSetDebugFillThreshold.To disable this behavior, use _CrtSetDebugFillThreshold.

De forma predeterminada, el ámbito de este estado global de esta función es la aplicación.By default, this function's global state is scoped to the application. Para cambiar esto, vea estado global en CRT.To change this, see Global state in the CRT.

Asignación de rutina de texto genéricoGeneric-Text Routine Mapping

Rutina TCHAR.HTCHAR.H routine _UNICODE y _MBCS no definidos_UNICODE & _MBCS not defined _MBCS definido_MBCS defined _UNICODE definido_UNICODE defined
_tasctime_s_tasctime_s asctime_sasctime_s asctime_sasctime_s _wasctime_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.In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. Para obtener más información, vea Sobrecargas de plantilla seguras.For more information, see Secure Template Overloads.

RequisitosRequirements

RutinaRoutine Encabezado necesarioRequired header
asctime_sasctime_s <time.h>
_wasctime_s_wasctime_s <time.h> o <wchar.h><time.h> or <wchar.h>

SeguridadSecurity

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 esté en la ubicación.If the buffer pointer is not NULL and the pointer does not point to a valid buffer, the function will overwrite whatever is at the location. Esto también puede producir una infracción de acceso.This can also result in an access violation.

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.A buffer overrun can occur if the size argument passed in is greater than the actual size of the buffer.

EjemploExample

Este programa coloca la hora del sistema en el aclockentero largo, lo traduce en la estructura newtime y, a continuación, lo convierte en un formato de cadena para la salida, mediante la función asctime_s .This program places the system time in the long integer aclock, translates it into the structure newtime and then converts it to string form for output, using the asctime_s function.

// 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énSee also

Administración de horaTime Management
ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_sctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s
_ftime, _ftime32, _ftime64_ftime, _ftime32, _ftime64
gmtime_s, _gmtime32_s, _gmtime64_sgmtime_s, _gmtime32_s, _gmtime64_s
localtime_s, _localtime32_s, _localtime64_slocaltime_s, _localtime32_s, _localtime64_s
time, _time32, _time64time, _time32, _time64
_tzset_tzset