_get_tzname

Recupera a representação da cadeia de caracteres do nome do fuso horário ou do nome da zona DST (horário de verão padrão).

Sintaxe

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

Parâmetros

pReturnValue
O tamanho da cadeia de caracteres de timeZoneName, incluindo um terminador NULL.

timeZoneName
O endereço de uma cadeia de caracteres para a representação do nome do fuso horário ou do nome do fuso horário com horário de verão (DST), dependendo de index.

sizeInBytes
O tamanho da cadeia de caracteres de timeZoneName em bytes.

index
O index de um dos dois nomes de fuso horário a serem recuperados.

index	Conteúdo de timeZoneName	Valor padrão timeZoneName
0	Nome do fuso horário	"PST"
1	O nome do fuso horário com horário de verão	"PDT"
> 1 ou < 0	errno definido como EINVAL	não modificado

A menos que seja explicitamente atualizado durante o runtime, "PST" será retornado para o fuso horário padrão e "PDT" para o fuso horário padrão de horário de verão. Para obter mais informações, confira Comentários.

Não há garantia de que a cadeia de caracteres de fuso horário seja a mesma em diferentes versões do sistema operacional. Os nomes oficiais de fuso horário podem ser alterados e são.

Valor retornado

Zero se for bem-sucedido; caso contrário, um valor de tipo errno.

Se for timeZoneName NULL, ou sizeInBytes for zero ou menor que zero (mas não ambos), um manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, essa função definirá errno para EINVAL e retornará EINVAL.

Condições de erro

pReturnValue	timeZoneName	sizeInBytes	index	Valor retornado	Conteúdo de timeZoneName
tamanho do nome do FH	NULL	0	0 ou 1	0	não modificado
tamanho do nome do FH	any	> 0	0 ou 1	0	Nome do FH
não modificado	NULL	> 0	any	EINVAL	não modificado
não modificado	any	zero	any	EINVAL	não modificado
não modificado	any	> 0	> 1	EINVAL	não modificado

Comentários

A função _get_tzname recupera a representação da cadeia de caracteres do nome do fuso horário atual ou do nome do fuso horário padrão de horário de verão (DST) no endereço de timeZoneName dependendo do valor de index, juntamente com o tamanho da cadeia de caracteres em pReturnValue. Se timeZoneName for NULL e sizeInBytes for zero, o tamanho da cadeia de caracteres em bytes necessária para manter o fuso horário especificado e um , de terminação NULLserá retornado em pReturnValue.

Os valores de index devem ser 0 para o fuso horário padrão ou 1 para o fuso horário padrão do horário de verão; todos os outros valores têm resultados indeterminados.

Por padrão, "PST" é retornado para o fuso horário padrão e "PDT" para o fuso horário padrão do horário de verão. O nome verdadeiro do fuso horário será atualizado na primeira vez em que ele for necessário por uma função que requer informações de fuso horário, como strftime, ftime, ftime_s, mktime, localtime, entre outros. Se uma função que não requer informações de fuso horário não for chamada antes de chamar _get_tzname, os valores padrão serão retornados, a menos que você os atualize explicitamente usando uma das funções mencionadas ou por uma chamada para tzset. Além disso, se a variável de ambiente TZ estiver definida, ela terá precedência sobre o nome do fuso horário relatado pelo sistema operacional. Mesmo nesse caso, uma das funções mencionadas acima precisa ser chamada antes de _get_tzname ser chamado ou o valor de fuso horário padrão será retornado. Para obter mais informações sobre a variável de ambiente TZ e o CRT, confira _tzset.

Aviso

Não há garantia de que a cadeia de caracteres de fuso horário seja a mesma em diferentes versões do sistema operacional. Os nomes oficiais de fuso horário podem ser alterados e são.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Exemplo

Este exemplo chama _get_tzname para obter o tamanho do buffer necessário para exibir o nome de fuso horário padrão de horário de verão atual, aloca um buffer desse tamanho, chama _get_tzname novamente para carregar o nome no buffer e o imprime no console.

Ele também chama _tzset() para fazer com que o sistema operacional atualize as informações de fuso horário antes de chamar _get_tzname(). Caso contrário, os valores padrão são usados.

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

Saída

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

Requisitos

Rotina	Cabeçalho necessário
_get_tzname	<time.h>

Para obter mais informações, consulte Compatibilidade.

Confira também

Gerenciamento de tempo
errno, _doserrno, _sys_errlist e _sys_nerr
_get_daylight
_get_dstbias
_get_timezone