]>
Commit | Line | Data |
---|---|---|
e9577640 MK |
1 | .\" Copyright 2001 walter harms (walter.harms@informatik.uni-oldenburg.de) |
2 | .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk | |
3 | .\" <mtk.manpages@gmail.com> | |
fea681da | 4 | .\" |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
6 | .\" |
7 | .\" Modified, 2001-12-26, aeb | |
e9577640 MK |
8 | .\" 2008-09-07, mtk, Various rewrites; added an example program. |
9 | .\" | |
4c1c5274 | 10 | .TH getdate 3 (date) "Linux man-pages (unreleased)" |
fea681da | 11 | .SH NAME |
e9577640 | 12 | getdate, getdate_r \- convert a date-plus-time string to broken-down time |
42009080 AC |
13 | .SH LIBRARY |
14 | Standard C library | |
15 | .RI ( libc ", " \-lc ) | |
fea681da | 16 | .SH SYNOPSIS |
c7db92b9 | 17 | .nf |
fea681da | 18 | .B "#include <time.h>" |
68e4db0a | 19 | .PP |
b9f02710 | 20 | .BI "struct tm *getdate(const char *" string ); |
68e4db0a | 21 | .PP |
0daa9e92 | 22 | .B "extern int getdate_err;" |
dbfe9c70 | 23 | .PP |
5e0058dc | 24 | .BI "int getdate_r(const char *restrict " string ", struct tm *restrict " res ); |
c7db92b9 | 25 | .fi |
68e4db0a | 26 | .PP |
d39ad78f | 27 | .RS -4 |
5b318b5e MK |
28 | Feature Test Macro Requirements for glibc (see |
29 | .BR feature_test_macros (7)): | |
d39ad78f | 30 | .RE |
68e4db0a | 31 | .PP |
5b318b5e | 32 | .BR getdate (): |
9d2adbae | 33 | .nf |
5c10d2c5 MK |
34 | _XOPEN_SOURCE >= 500 |
35 | .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED | |
9d2adbae | 36 | .fi |
98c9347c | 37 | .PP |
5b318b5e | 38 | .BR getdate_r (): |
9d2adbae MK |
39 | .nf |
40 | _GNU_SOURCE | |
41 | .fi | |
fea681da MK |
42 | .SH DESCRIPTION |
43 | The function | |
63aa9df0 | 44 | .BR getdate () |
e9577640 MK |
45 | converts a string representation of a date and time, |
46 | contained in the buffer pointed to by | |
47 | .IR string , | |
48 | into a broken-down time. | |
49 | The broken-down time is stored in a | |
d9a10d9d | 50 | .I tm |
e9577640 MK |
51 | structure, and a pointer to this |
52 | structure is returned as the function result. | |
d9a10d9d MK |
53 | This |
54 | .I tm | |
e9577640 MK |
55 | structure is allocated in static storage, |
56 | and consequently it will be overwritten by further calls to | |
57 | .BR getdate (). | |
847e0d88 | 58 | .PP |
c13182ef | 59 | In contrast to |
fea681da MK |
60 | .BR strptime (3), |
61 | (which has a | |
62 | .I format | |
63 | argument), | |
63aa9df0 | 64 | .BR getdate () |
fea681da | 65 | uses the formats found in the file |
e9577640 | 66 | whose full pathname is given in the environment variable |
fea681da MK |
67 | .BR DATEMSK . |
68 | The first line in the file that matches the given input string | |
69 | is used for the conversion. | |
847e0d88 | 70 | .PP |
fea681da MK |
71 | The matching is done case insensitively. |
72 | Superfluous whitespace, either in the pattern or in the string to | |
73 | be converted, is ignored. | |
847e0d88 | 74 | .PP |
fea681da MK |
75 | The conversion specifications that a pattern can contain are those given for |
76 | .BR strptime (3). | |
e9577640 | 77 | One more conversion specification is specified in POSIX.1-2001: |
fea681da MK |
78 | .TP |
79 | .B %Z | |
80 | Timezone name. | |
d16449b1 MK |
81 | .\" FIXME Is it (still) true that %Z is not supported in glibc? |
82 | .\" Looking at the glibc 2.21 source code, where the implementation uses | |
83 | .\" strptime(), suggests that it might be supported. | |
e9577640 | 84 | This is not implemented in glibc. |
dd3568a1 | 85 | .PP |
fea681da MK |
86 | When |
87 | .B %Z | |
e9577640 MK |
88 | is given, the structure containing the broken-down time |
89 | is initialized with values corresponding to the current | |
5b0dc1ba | 90 | time in the given timezone. |
e9577640 MK |
91 | Otherwise, the structure is initialized to the broken-down time |
92 | corresponding to the current local time (as by a call to | |
93 | .BR localtime (3)). | |
dd3568a1 | 94 | .PP |
b458e1bf MK |
95 | When only the day of the week is given, |
96 | the day is taken to be the first such day | |
fea681da | 97 | on or after today. |
dd3568a1 | 98 | .PP |
fea681da MK |
99 | When only the month is given (and no year), the month is taken to |
100 | be the first such month equal to or after the current month. | |
101 | If no day is given, it is the first day of the month. | |
dd3568a1 | 102 | .PP |
735334d4 MK |
103 | When no hour, minute, and second are given, the current |
104 | hour, minute, and second are taken. | |
dd3568a1 | 105 | .PP |
fea681da MK |
106 | If no date is given, but we know the hour, then that hour is taken |
107 | to be the first such hour equal to or after the current hour. | |
847e0d88 | 108 | .PP |
e9577640 MK |
109 | .BR getdate_r () |
110 | is a GNU extension that provides a reentrant version of | |
111 | .BR getdate (). | |
112 | Rather than using a global variable to report errors and a static buffer | |
113 | to return the broken down time, | |
114 | it returns errors via the function result value, | |
115 | and returns the resulting broken-down time in the | |
116 | caller-allocated buffer pointed to by the argument | |
117 | .IR res . | |
47297adb | 118 | .SH RETURN VALUE |
d4e9903b | 119 | When successful, |
e9577640 MK |
120 | .BR getdate () |
121 | returns a pointer to a | |
8478ee02 | 122 | .IR "struct tm" . |
fea681da | 123 | Otherwise, it returns NULL and sets the global variable |
1ae6b2c7 | 124 | .I getdate_err |
e9577640 | 125 | to one of the error numbers shown below. |
fea681da MK |
126 | Changes to |
127 | .I errno | |
c13182ef | 128 | are unspecified. |
847e0d88 | 129 | .PP |
e9577640 MK |
130 | On success |
131 | .BR getdate_r () | |
132 | returns 0; | |
133 | on error it returns one of the error numbers shown below. | |
134 | .SH ERRORS | |
135 | The following errors are returned via | |
1ae6b2c7 | 136 | .I getdate_err |
e9577640 MK |
137 | (for |
138 | .BR getdate ()) | |
139 | or as the function result (for | |
140 | .BR getdate_r ()): | |
fea681da MK |
141 | .TP 4n |
142 | .B 1 | |
2f0af33b MK |
143 | The |
144 | .B DATEMSK | |
e9577640 | 145 | environment variable is not defined, or its value is an empty string. |
fea681da MK |
146 | .TP |
147 | .B 2 | |
e9577640 MK |
148 | The template file specified by |
149 | .B DATEMSK | |
150 | cannot be opened for reading. | |
fea681da MK |
151 | .TP |
152 | .B 3 | |
153 | Failed to get file status information. | |
e9577640 | 154 | .\" stat() |
fea681da MK |
155 | .TP |
156 | .B 4 | |
157 | The template file is not a regular file. | |
158 | .TP | |
159 | .B 5 | |
e9577640 | 160 | An error was encountered while reading the template file. |
fea681da MK |
161 | .TP |
162 | .B 6 | |
163 | Memory allocation failed (not enough memory available). | |
e9577640 | 164 | .\" Error 6 doesn't seem to occur in glibc |
fea681da MK |
165 | .TP |
166 | .B 7 | |
167 | There is no line in the file that matches the input. | |
168 | .TP | |
169 | .B 8 | |
170 | Invalid input specification. | |
2b2581ee MK |
171 | .SH ENVIRONMENT |
172 | .TP | |
173 | .B DATEMSK | |
174 | File containing format patterns. | |
175 | .TP | |
176 | .BR TZ ", " LC_TIME | |
177 | Variables used by | |
178 | .BR strptime (3). | |
0a5e5cd8 | 179 | .SH ATTRIBUTES |
894fae6b MK |
180 | For an explanation of the terms used in this section, see |
181 | .BR attributes (7). | |
c466875e MK |
182 | .ad l |
183 | .nh | |
894fae6b MK |
184 | .TS |
185 | allbox; | |
b32feea5 | 186 | lb lb lbx |
894fae6b MK |
187 | l l l. |
188 | Interface Attribute Value | |
189 | T{ | |
0a5e5cd8 | 190 | .BR getdate () |
b32feea5 MK |
191 | T} Thread safety T{ |
192 | MT-Unsafe race:getdate env locale | |
193 | T} | |
894fae6b | 194 | T{ |
0a5e5cd8 | 195 | .BR getdate_r () |
b32feea5 MK |
196 | T} Thread safety T{ |
197 | MT-Safe env locale | |
198 | T} | |
894fae6b | 199 | .TE |
c466875e MK |
200 | .hy |
201 | .ad | |
202 | .sp 1 | |
3113c7f3 | 203 | .SH STANDARDS |
b08fc2ff | 204 | POSIX.1-2001, POSIX.1-2008. |
fea681da | 205 | .SH NOTES |
b08fc2ff | 206 | The POSIX.1 specification for |
fb186734 | 207 | .BR strptime (3) |
fea681da MK |
208 | contains conversion specifications using the |
209 | .B %E | |
210 | or | |
211 | .B %O | |
212 | modifier, while such specifications are not given for | |
63aa9df0 | 213 | .BR getdate (). |
e9577640 | 214 | In glibc, |
63aa9df0 | 215 | .BR getdate () |
e9577640 MK |
216 | is implemented using |
217 | .BR strptime (3), | |
218 | so that precisely the same conversions are supported by both. | |
a14af333 | 219 | .SH EXAMPLES |
e9577640 MK |
220 | The program below calls |
221 | .BR getdate () | |
222 | for each of its command-line arguments, | |
223 | and for each call displays the values in the fields of the returned | |
224 | .I tm | |
225 | structure. | |
226 | The following shell session demonstrates the operation of the program: | |
847e0d88 | 227 | .PP |
e9577640 | 228 | .in +4n |
b8302363 | 229 | .EX |
b43a3b30 | 230 | .RB "$" " TFILE=$PWD/tfile" |
b458e1bf | 231 | .RB "$" " echo \(aq%A\(aq > $TFILE " " # Full name of the day of the week" |
7580780e AC |
232 | .RB "$" " echo \(aq%T\(aq >> $TFILE" " # Time (HH:MM:SS)" |
233 | .RB "$" " echo \(aq%F\(aq >> $TFILE" " # ISO date (YYYY\-MM\-DD)" | |
b43a3b30 MK |
234 | .RB "$" " date" |
235 | .RB "$" " export DATEMSK=$TFILE" | |
d064d41a | 236 | .RB "$" " ./a.out Tuesday \(aq2009\-12\-28\(aq \(aq12:22:33\(aq" |
e9577640 MK |
237 | Sun Sep 7 06:03:36 CEST 2008 |
238 | Call 1 ("Tuesday") succeeded: | |
239 | tm_sec = 36 | |
240 | tm_min = 3 | |
241 | tm_hour = 6 | |
242 | tm_mday = 9 | |
243 | tm_mon = 8 | |
244 | tm_year = 108 | |
245 | tm_wday = 2 | |
246 | tm_yday = 252 | |
247 | tm_isdst = 1 | |
d064d41a | 248 | Call 2 ("2009\-12\-28") succeeded: |
e9577640 MK |
249 | tm_sec = 36 |
250 | tm_min = 3 | |
251 | tm_hour = 6 | |
252 | tm_mday = 28 | |
253 | tm_mon = 11 | |
254 | tm_year = 109 | |
255 | tm_wday = 1 | |
256 | tm_yday = 361 | |
257 | tm_isdst = 0 | |
258 | Call 3 ("12:22:33") succeeded: | |
259 | tm_sec = 33 | |
260 | tm_min = 22 | |
261 | tm_hour = 12 | |
262 | tm_mday = 7 | |
263 | tm_mon = 8 | |
264 | tm_year = 108 | |
265 | tm_wday = 0 | |
266 | tm_yday = 250 | |
267 | tm_isdst = 1 | |
b8302363 | 268 | .EE |
e9577640 | 269 | .in |
9c330504 | 270 | .SS Program source |
d84d0300 | 271 | \& |
b0b6ab4e | 272 | .\" SRC BEGIN (getdate.c) |
e7d0bb47 | 273 | .EX |
21e2ed66 | 274 | #define _GNU_SOURCE |
e9577640 MK |
275 | #include <stdio.h> |
276 | #include <stdlib.h> | |
ad3868f0 | 277 | #include <time.h> |
e9577640 MK |
278 | |
279 | int | |
280 | main(int argc, char *argv[]) | |
281 | { | |
282 | struct tm *tmp; | |
e9577640 | 283 | |
b42296e4 | 284 | for (size_t j = 1; j < argc; j++) { |
e9577640 MK |
285 | tmp = getdate(argv[j]); |
286 | ||
287 | if (tmp == NULL) { | |
d1a71985 | 288 | printf("Call %d failed; getdate_err = %d\en", |
e9577640 MK |
289 | j, getdate_err); |
290 | continue; | |
291 | } | |
292 | ||
b42296e4 | 293 | printf("Call %zu (\e"%s\e") succeeded:\en", j, argv[j]); |
d1a71985 MK |
294 | printf(" tm_sec = %d\en", tmp\->tm_sec); |
295 | printf(" tm_min = %d\en", tmp\->tm_min); | |
296 | printf(" tm_hour = %d\en", tmp\->tm_hour); | |
297 | printf(" tm_mday = %d\en", tmp\->tm_mday); | |
298 | printf(" tm_mon = %d\en", tmp\->tm_mon); | |
299 | printf(" tm_year = %d\en", tmp\->tm_year); | |
300 | printf(" tm_wday = %d\en", tmp\->tm_wday); | |
301 | printf(" tm_yday = %d\en", tmp\->tm_yday); | |
302 | printf(" tm_isdst = %d\en", tmp\->tm_isdst); | |
e9577640 MK |
303 | } |
304 | ||
305 | exit(EXIT_SUCCESS); | |
306 | } | |
e7d0bb47 | 307 | .EE |
b0b6ab4e | 308 | .\" SRC END |
47297adb | 309 | .SH SEE ALSO |
be4d4fe4 | 310 | .BR time (2), |
fea681da | 311 | .BR localtime (3), |
9fcfcba0 | 312 | .BR setlocale (3), |
fea681da | 313 | .BR strftime (3), |
0a4f8b7b | 314 | .BR strptime (3) |