Compartir vía

_get_tzname

  • Artículo

Recupera la representación en cadena de caracteres del nombre de la zona horaria o del nombre de la zona horaria estándar de horario de verano (DST).

Sintaxis

errno_t _get_tzname(
    size_t* pReturnValue,
    char* timeZoneName,
    size_t sizeInBytes,
    int index
);

Parámetros

pReturnValue
Longitud de cadena de timeZoneName incluido un terminador NULL.

timeZoneName
Dirección de una cadena de caracteres para la representación del nombre de zona horaria o el nombre de zona de hora estándar de horario de verano (DST), en función de index.

sizeInBytes
Tamaño de la cadena de caracteres timeZoneName en bytes.

index
index de uno de los dos nombres de zona horaria que hay que recuperar.

index Contenido de timeZoneName Valor predeterminado timeZoneName
0 Nombre de zona horaria "PST"
1 Nombre de zona de hora estándar de horario de verano "PDT"
> 1 o < 0 errno se establece en EINVAL no modificado

A menos que se haya actualizado explícitamente en tiempo de ejecución, se devuelve "PST" para la zona horaria estándar y "PDT" para la zona horaria estándar de verano. Puede obtener información adicional en la sección Notas.

No se garantiza que la cadena de zona horaria coincida en las distintas versiones del sistema operativo. Los nombres oficiales de zona horaria pueden cambiar y, de hecho, cambian.

Valor devuelto

Cero si se ejecuta correctamente; en caso contrario, un valor de tipo errno.

Si es timeZoneName , o sizeInBytes es NULLcero o menor que cero (pero no ambos), se invoca un controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, la función establece errno en EINVAL y devuelve EINVAL.

Condiciones del error

pReturnValue timeZoneName sizeInBytes index Valor devuelto Contenido de timeZoneName
tamaño de nombre de ZH NULL 0 0 o 1 0 no modificado
tamaño de nombre de ZH cualquiera > 0 0 o 1 0 Nombre de ZH
no modificado NULL > 0 cualquiera EINVAL no modificado
no modificado cualquiera zero cualquiera EINVAL no modificado
no modificado cualquiera > 0 > 1 EINVAL no modificado

Comentarios

La función _get_tzname recupera la representación en cadena de caracteres del nombre de zona horaria o del nombre de zona horaria estándar de horario de verano (DST) en la dirección de timeZoneName en función del valor index, junto con el tamaño de la cadena en pReturnValue. Si timeZoneName es y sizeInBytes es NULL cero, el tamaño de la cadena en bytes necesario para contener la zona horaria especificada y un terminado NULL, se devuelve en pReturnValue.

Los valores index tienen que ser 0 para la zona horaria estándar o 1 para la zona horaria estándar de horario de verano; cualquier otro valor arrojará un resultado indeterminado.

De forma predeterminada, se devuelve"PST" para la zona horaria estándar y "PDT" para la zona horaria estándar de verano. El verdadero nombre de zona horaria se actualiza la primera vez que lo requiere una función que necesita información de zona horaria como, por ejemplo, strftime, ftime, ftime_s, mktime, localtime y otras. Si no se llama a una función que no requiere información de zona horaria antes de llamar _get_tznamea , los valores predeterminados se devuelven a menos que primero los actualice explícitamente mediante una de las funciones mencionadas o mediante una llamada a tzset. Además, si está definida la variable de entorno TZ, tendrá prioridad sobre el nombre de zona horaria notificado por el sistema operativo. Incluso en este caso, hay que invocar una de las funciones mencionadas anteriormente antes de invocar _get_tzname, o se devolverá el valor de zona horaria predeterminado. Para obtener información adicional sobre la variable de entorno TZ y la CRT, consulte_tzset.

Advertencia

No se garantiza que la cadena de zona horaria coincida en las distintas versiones de SO. Los nombres oficiales de zona horaria pueden cambiar y, de hecho, cambian.

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.

Ejemplo

En este ejemplo se invoca _get_tzname para obtener el tamaño de búfer necesario para mostrar el nombre de zona horaria estándar de verano actual, se asigna un búfer de ese tamaño, se vuelve a invocar _get_tzname para cargar el nombre en el búfer y se imprime en la consola.

También invoca _tzset() para hacer que el SO actualice la información de zona horaria antes de invocar_get_tzname(). En caso contrario, se usarán los valores predeterminados.

// crt_get_tzname.c
// Compile by using: cl /W4 crt_get_tzname.c
#include <stdio.h>
#include <time.h>
#include <malloc.h>

enum TZindex {
    STD,
    DST
};

int main()
{
    size_t tznameSize = 0;
    char * tznameBuffer = NULL;

    _tzset(); // Update the time zone information

    // Get the size of buffer required to hold DST time zone name
    if (_get_tzname(&tznameSize, NULL, 0, DST))
    {
        return 1;    // Return an error value if it failed
    }

    // Allocate a buffer for the name
    if (NULL == (tznameBuffer = (char *)(malloc(tznameSize))))
    {
        return 2;    // Return an error value if it failed
    }

    // Load the name in the buffer
    if (_get_tzname(&tznameSize, tznameBuffer, tznameSize, DST))
    {
        return 3;    // Return an error value if it failed
    }

    printf_s("The current Daylight standard time zone name is %s.\n", tznameBuffer);
    return 0;
}

Output

The current Daylight standard time zone name is Pacific Daylight Time.

Requisitos

Routine Encabezado necesario
_get_tzname <time.h>

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

Consulte también

Administración de tiempo
errno, _doserrno, _sys_errlist y _sys_nerr.
_get_daylight
_get_dstbias
_get_timezone