_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。

index	timeZoneName 的内容	timeZoneName 默认值
0	时区名称	"PST"
1	夏令时标准时区名称	"PDT"
> 1 或 < 0	将 errno 设置为 EINVAL	未修改

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

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

返回值

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

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

错误条件

pReturnValue	timeZoneName	sizeInBytes	index	返回值	timeZoneName 的内容
TZ 名称的大小	NULL	0	0 或 1	0	未修改
TZ 名称的大小	任意	> 0	0 或 1	0	TZ 名称
未修改	NULL	> 0	任意	EINVAL	未修改
未修改	any	零	any	EINVAL	未修改
未修改	任意	> 0	> 1	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。

警告

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

默认情况下，此函数的全局状态范围限定为应用程序。 要更改此行为，请参阅 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.

要求

例程	必需的标头
_get_tzname	<time.h>

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

另请参阅

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