Debian Codegraph @

upstream/debian-unstable/man3/getdate.3

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