Debian Codegraph @

upstream/debian-trixie/man3/getdate.3

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