localtime_s, _localtime32_s, _localtime64_s

Convierte un valor de hora time_t en una estructura tm y lo corrige para la zona horaria local. Estas funciones son versiones de localtime, _localtime32, _localtime64 con mejoras de seguridad como se describe en Características de seguridad de CRT.

Sintaxis

errno_t localtime_s(
   struct tm* const tmDest,
   time_t const* const sourceTime
);
errno_t _localtime32_s(
   struct tm* tmDest,
   __time32_t const* sourceTime
);
errno_t _localtime64_s(
   struct tm* tmDest,
   __time64_t const* sourceTime
);

Parámetros

tmDest
Puntero a la estructura de tiempo que debe rellenarse.

sourceTime
Puntero a la hora almacenada.

Valor devuelto

Cero si es correcta. Si se produce un error, el valor devuelto es un código de error. Los códigos de error se definen en Errno.h. Para ver una lista de estos errores, consulte errno.

Condiciones de error

tmDest	sourceTime	Valor devuelto	Valor de tmDest	Invoca el controlador de parámetros no válidos
NULL	cualquiera	EINVAL	No modificado	Sí
No NULL (apunta a la memoria válida)	NULL	EINVAL	Todos los campos establecidos en -1	Sí
No NULL (apunta a la memoria válida)	menor que 0 o mayor que _MAX__TIME64_T	EINVAL	Todos los campos establecidos en -1	No

Las dos primeras condiciones de error invocan el controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, estas funciones establecen errno en EINVAL y devuelven EINVAL.

Comentarios

La función localtime_s convierte una hora almacenada como valor time_t y almacena el resultado en una estructura de tipo tm. El valor time_tsourceTime representa los segundos transcurridos desde la medianoche (00:00:00) del 1 de enero de 1970, hora UTC. Este valor se obtiene a menudo de la time función .

localtime_s corrige la zona horaria local si el usuario establece primero la variable de entorno global TZ. Si se establece TZ, también se establecen automáticamente otras tres variables de entorno (_timezone, _daylight y _tzname). Si no se establece la TZ variable, localtime_s intenta usar la información de zona horaria especificada en la aplicación Fecha y hora en Panel de control. Si no se puede obtener esta información, PST8PDT, que significa la zona horaria del Pacífico, se usa de forma predeterminada. Consulte _tzset para ver una descripción de estas variables. TZ es una extensión de Microsoft y no forma parte de la definición del estándar ANSI de localtime.

Nota:

El entorno de destino debería intentar determinar si el horario de verano está vigente.

_localtime64_s, que usa la estructura __time64_t, permite expresar fechas hasta las 23:59:59 del 18 de enero de 3001, hora universal coordinada (UTC), mientras que _localtime32_s representa fechas hasta las 23:59:59 del 18 de enero de 2038, hora UTC.

localtime_s es una función insertada que se evalúa como _localtime64_s y time_t es equivalente a __time64_t. Si necesita forzar al compilador a interpretar time_t como el antiguo de 32 bits time_t, puede definir _USE_32BIT_TIME_T, lo que hace localtime_s que se evalúe como _localtime32_s. No se recomienda _USE_32BIT_TIME_T, ya que la aplicación puede producir un error después del 18 de enero de 2038 y no se permite en plataformas de 64 bits.

Los campos del tipo de estructura tm almacenan los valores siguientes, cada uno de los cuales es un int.

Campo	Descripción
tm_sec	Segundos después del minuto (0 - 59).
tm_min	Minutos después de la hora (0 - 59).
tm_hour	Horas desde la medianoche (0 - 23).
tm_mday	Día del mes (1 - 31).
tm_mon	Mes (0 - 11; enero = 0).
tm_year	Año (año actual menos 1900).
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_isdst	Valor positivo si el horario de verano está en vigor; 0 si el horario de verano no está en vigor; valor negativo si se desconoce el estado del horario de verano.

Si se establece la variable de entorno TZ, la biblioteca en tiempo de ejecución de C usa las reglas correspondientes a los Estados Unidos para implementar el cálculo del horario de verano (DST).

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.

Requisitos

Routine	Encabezado C necesario	Encabezado C++ necesario
localtime_s, _localtime32_s, _localtime64_s	<time.h>	<ctime> o <time.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

// crt_localtime_s.c
// This program uses _time64 to get the current time
// and then uses _localtime64_s() to convert this time to a structure
// representing the local time. The program converts the result
// from a 24-hour clock to a 12-hour clock and determines the
// proper extension (AM or PM).

#include <stdio.h>
#include <string.h>
#include <time.h>

int main( void )
{
    struct tm newtime;
    char am_pm[] = "AM";
    __time64_t long_time;
    char timebuf[26];
    errno_t err;

    // Get time as 64-bit integer.
    _time64( &long_time );
    // Convert to local time.
    err = _localtime64_s( &newtime, &long_time );
    if (err)
    {
        printf("Invalid argument to _localtime64_s.");
        exit(1);
    }
    if( newtime.tm_hour > 12 )        // Set up extension.
        strcpy_s( am_pm, sizeof(am_pm), "PM" );
    if( newtime.tm_hour > 12 )        // Convert from 24-hour
        newtime.tm_hour -= 12;        // to 12-hour clock.
    if( newtime.tm_hour == 0 )        // Set hour to 12 if midnight.
        newtime.tm_hour = 12;

    // Convert to an ASCII representation.
    err = asctime_s(timebuf, 26, &newtime);
    if (err)
    {
        printf("Invalid argument to asctime_s.");
        exit(1);
    }
    printf( "%.19s %s\n", timebuf, am_pm );
}

Fri Apr 25 01:19:27 PM

Consulte también

Administración de tiempo
asctime_s, _wasctime_s
ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64
_ftime, _ftime32, _ftime64
gmtime_s, _gmtime32_s, _gmtime64_s
localtime, _localtime32, _localtime64
time, _time32, _time64
_tzset