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