_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 类型值。

如果 timeZoneNameNULL,或 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 中字符串的大小。 如果 timeZoneNameNULL 并且 sizeInBytes 为零,则在 pReturnValue 中返回保存指定时区和终止 NULL 所需的字符串大小(以字节为单位)。

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

默认情况下,对于标准时区返回 "PST",对于夏令时标准时区返回 "PDT"。 真实的时区名称会在要求提供时区信息(如 strftimeftimeftime_smktimelocaltime 等)的函数首次需要时区名称时更新。 如果在调用 _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