You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Retrieves the character string representation of the time zone name or the daylight standard time zone name (DST).
14
+
Retrieves the character string representation of the time zone name or the daylight standard time (DST) zone name.
16
15
17
16
## Syntax
18
17
@@ -27,51 +26,62 @@ errno_t _get_tzname(
27
26
28
27
### Parameters
29
28
30
-
*pReturnValue*<br/>
31
-
The string length of *timeZoneName* including a null terminator.
29
+
*`pReturnValue`*\
30
+
The string length of *`timeZoneName`* including a `NULL` terminator.
32
31
33
-
*timeZoneName*<br/>
34
-
The address of a character string for the representation of the time zone name or the daylight standard time zone name (DST), depending on *index*.
32
+
*`timeZoneName`*\
33
+
The address of a character string for the representation of the time zone name or the daylight standard time zone name (DST), depending on *`index`*.
35
34
36
-
*sizeInBytes*<br/>
37
-
The size of the *timeZoneName* character string in bytes.
35
+
*`sizeInBytes`*\
36
+
The size of the *`timeZoneName`* character string in bytes.
38
37
39
-
*index*<br/>
40
-
The index of one of the two time zone names to retrieve.
38
+
*`index`*\
39
+
The *`index`* of one of the two time zone names to retrieve.
41
40
42
-
|*index*|Contents of *timeZoneName*|*timeZoneName* default value|
41
+
|*`index`*|Contents of *`timeZoneName`*|*`timeZoneName`* default value|
43
42
|-|-|-|
44
-
|0|Time zone name|"PST"|
45
-
|1|Daylight standard time zone name|"PDT"|
46
-
|> 1 or < 0|**errno** set to **EINVAL**|not modified|
43
+
|0|Time zone name|`"PST"`|
44
+
|1|Daylight standard time zone name|`"PDT"`|
45
+
|> 1 or < 0|**`errno`** set to `EINVAL`|not modified|
47
46
48
-
Unless the values are explicitly changed during run time, the default values are "PST" and "PDT" respectively.
47
+
Unless explicitly updated during runtime, `"PST"` is returned for the standard time zone and `"PDT"` for the daylight standard time zone. For more information, see the [Remarks](#remarks).
48
+
49
+
The time zone string isn't guaranteed to be the same between OS releases. Official time zone names can and do change.
49
50
50
51
## Return Value
51
52
52
-
Zero if successful, otherwise an **errno** type value.
53
+
Zero if successful, otherwise an **`errno`** type value.
53
54
54
-
If either *timeZoneName* is **NULL**, or *sizeInBytes* is zero or less than zero (but not both), an invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**.
55
+
If either *`timeZoneName`* is `NULL`, or *`sizeInBytes`* is zero or less than zero (but not both), an invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **`errno`** to `EINVAL` and returns `EINVAL`.
55
56
56
57
### Error Conditions
57
58
58
-
|*pReturnValue*|*timeZoneName*|*sizeInBytes*|*index*|Return value|Contents of *timeZoneName*|
59
+
|*`pReturnValue`*|*`timeZoneName`*|*`sizeInBytes`*|*`index`*|Return value|Contents of *`timeZoneName`*|
The **_get_tzname** function retrieves the character string representation of the current time zone name or the daylight standard time zone name (DST) into the address of *timeZoneName* depending on the index value, along with the size of the string in *pReturnValue*. If *timeZoneName* is **NULL** and *sizeInBytes* is zero, the size of the string required to hold the specified time zone and a terminating null in bytes is returned in *pReturnValue*. The index values must be either 0 for standard time zone or 1 for daylight standard time zone; any other values of *index* have undetermined results.
69
+
The `_get_tzname` function retrieves the character string representation of the current time zone name or the daylight standard time zone name (DST) into the address of *`timeZoneName`* depending on the *`index`* value, along with the size of the string in *`pReturnValue`*. If *`timeZoneName`* is `NULL` and *`sizeInBytes`* is zero, the size of the string required to hold the specified time zone and a terminating `NULL` in bytes is returned in *`pReturnValue`*.
70
+
71
+
The *`index`* values must be either 0 for standard time zone or 1 for daylight standard time zone; any other values have undetermined results.
72
+
73
+
By default, `"PST"` is returned for the standard time zone and `"PDT"` for the daylight standard time zone. The true time zone name is updated the first time it's needed by a function that requires time zone information, such as [`strftime`](strftime-wcsftime-strftime-l-wcsftime-l.md), [`ftime`](ftime-ftime32-ftime64.md), [`ftime_s`](ftime-s-ftime32-s-ftime64-s.md), [`mktime`](mktime-mktime32-mktime64.md), [`localtime`](localtime-localtime32-localtime64.md), and others. If a function that doesn't require time zone information isn't called prior to calling `_get_tzname`, the default values are returned unless you first explicitly update them with one of the functions just mentioned, or a call to [`tzset()`](tzset.md). Also, if the `TZ` environment variable is set, it takes precedence over the time zone name reported by the OS. Even in this case, one of the functions mentioned above must be called before `_get_tzname` is called or the default time zone value will be returned. For more information about the `TZ` environment variable and the CRT, see [`_tzset`](tzset.md).
74
+
75
+
> [!WARNING]
76
+
> The time zone string is not guaranteed to be the same between OS releases. Official time zone names can and do change.
69
77
70
78
By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md).
71
79
72
80
## Example
73
81
74
-
This sample calls **_get_tzname** to get the required buffer size to display the current Daylight standard time zone name, allocates a buffer of that size, calls **_get_tzname** again to load the name in the buffer, and prints it to the console.
82
+
This sample calls `_get_tzname` to get the required buffer size to display the current Daylight standard time zone name, allocates a buffer of that size, calls `_get_tzname` again to load the name in the buffer, and prints it to the console.
83
+
84
+
It also calls `_tzset()` to cause the OS to update the time zone information before calling `_get_tzname()`. Otherwise, the default values are used.
75
85
76
86
```C
77
87
// crt_get_tzname.c
@@ -80,7 +90,7 @@ This sample calls **_get_tzname** to get the required buffer size to display the
80
90
#include<time.h>
81
91
#include<malloc.h>
82
92
83
-
enumTZINDEX {
93
+
enumTZindex {
84
94
STD,
85
95
DST
86
96
};
@@ -90,17 +100,25 @@ int main()
90
100
size_t tznameSize = 0;
91
101
char * tznameBuffer = NULL;
92
102
103
+
_tzset(); // Update the time zone information
104
+
93
105
// Get the size of buffer required to hold DST time zone name
94
106
if (_get_tzname(&tznameSize, NULL, 0, DST))
107
+
{
95
108
return 1; // Return an error value if it failed
109
+
}
96
110
97
111
// Allocate a buffer for the name
98
112
if (NULL == (tznameBuffer = (char *)(malloc(tznameSize))))
113
+
{
99
114
return 2; // Return an error value if it failed
115
+
}
100
116
101
117
// Load the name in the buffer
102
118
if (_get_tzname(&tznameSize, tznameBuffer, tznameSize, DST))
119
+
{
103
120
return 3; // Return an error value if it failed
121
+
}
104
122
105
123
printf_s("The current Daylight standard time zone name is %s.\n", tznameBuffer);
106
124
return 0;
@@ -110,21 +128,21 @@ int main()
110
128
### Output
111
129
112
130
```Output
113
-
The current Daylight standard time zone name is PDT.
131
+
The current Daylight standard time zone name is Pacific Daylight Time.
114
132
```
115
133
116
134
## Requirements
117
135
118
136
|Routine|Required header|
119
137
|-------------|---------------------|
120
-
|**_get_tzname**|\<time.h>|
138
+
|`_get_tzname`|`<time.h>`|
121
139
122
140
For more information, see [Compatibility](../../c-runtime-library/compatibility.md).
0 commit comments