_get_tzname

检索时区名称或夏令时 (DST) 标准时区名称的字符串表示形式。

语法

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

参数

pReturnValue
包括 NULL 终止符的 timeZoneName 的字符串长度。

timeZoneName
具体取决于 index 的时区名称或夏令时标准时区名称 (DST) 表示形式的字符串的地址。

sizeInBytes
timeZoneName 字符串的大小，以字节为单位。

index
要检索的两个时区名称之一的 index。

除非在运行时期间显式更新，否则为标准时区返回 "PST"，为夏令时标准时区返回 "PDT"。 有关详细信息，请参阅注解部分。

不保证 OS 版本之间的时区字符串相同。 官方时区名称可以而且确实会更改。

返回值

如果成功，则为零；否则为 errno 类型值。

如果 timeZoneName 为 NULL，或 sizeInBytes 为零或小于零（但不同时满足以上两个条件），则调用无效参数句柄，如参数验证中所述。 如果允许执行继续，则该函数将 errno 设置为 EINVAL 并返回 EINVAL。

错误条件

备注

_get_tzname 函数根据 index 值检索 timeZoneName 地址中的当前时区名称或夏令时标准时区名称 (DST) 的字符串表示形式，并检索 pReturnValue 中字符串的大小。 如果 timeZoneName 为 NULL 并且 sizeInBytes 为零，则在 pReturnValue 中返回保存指定时区和终止 NULL 所需的字符串大小（以字节为单位）。

标准时区的 index 值必须为 0，夏令时标准时区的值必须为 1；任何其他值都具有不确定的结果。

默认情况下，对于标准时区返回 "PST"，对于夏令时标准时区返回 "PDT"。 真实的时区名称会在要求提供时区信息（如 strftime、ftime、ftime_s、mktime、localtime 等）的函数首次需要时区名称时更新。 如果在调用 _get_tzname 之前未调用不需要时区信息的函数，则将返回默认值，除非首先使用提到的函数之一或通过调用 tzset 显式更新它们。 此外，如果设置了环境变量 TZ，则其优先于 OS 报告的时区名称。 即使在这种情况下，上述函数之一也必须在调用之前 _get_tzname 调用，否则将返回默认时区值。 有关环境变量 TZ 和 CRT 的详细信息，请参阅 _tzset。

默认情况下，此函数的全局状态范围限定为应用程序。 要更改此行为，请参阅 CRT 中的全局状态。

示例

此示例调用 _get_tzname 获取所需的缓冲区大小以显示当前的夏令时标准时区名称、分配该大小的缓冲区、再次调用 _get_tzname 以加载缓冲区中的名称，并将其输出到控制台。

它还调用 _tzset() 以使 OS 在调用 _get_tzname() 之前更新时区信息。 否则使用默认值。

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

输出

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

要求

有关详细信息，请参阅兼容性。

另请参阅

工时管理
errno、_doserrno、_sys_errlist 和 _sys_nerr
_get_daylight
_get_dstbias
_get_timezone