2 .\" Copyright 2001 walter harms (walter.harms@informatik.uni-oldenburg.de)
3 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
4 .\" <mtk.manpages@gmail.com>
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .\" Modified, 2001-12-26, aeb
9 .\" 2008-09-07, mtk, Various rewrites; added an example program.
11 .TH getdate 3 (date) "Linux man-pages (unreleased)"
13 getdate, getdate_r \- convert a date-plus-time string to broken-down time
16 .RI ( libc ", " \-lc )
19 .B "#include <time.h>"
21 .BI "struct tm *getdate(const char *" string );
23 .B "extern int getdate_err;"
25 .BI "int getdate_r(const char *restrict " string ", struct tm *restrict " res );
29 Feature Test Macro Requirements for glibc (see
30 .BR feature_test_macros (7)):
36 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
46 converts a string representation of a date and time,
47 contained in the buffer pointed to by
49 into a broken-down time.
50 The broken-down time is stored in a
52 structure, and a pointer to this
53 structure is returned as the function result.
56 structure is allocated in static storage,
57 and consequently it will be overwritten by further calls to
66 uses the formats found in the file
67 whose full pathname is given in the environment variable
69 The first line in the file that matches the given input string
70 is used for the conversion.
72 The matching is done case insensitively.
73 Superfluous whitespace, either in the pattern or in the string to
74 be converted, is ignored.
76 The conversion specifications that a pattern can contain are those given for
78 One more conversion specification is specified in POSIX.1-2001:
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.
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
96 When only the day of the week is given,
97 the day is taken to be the first such day
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.
104 When no hour, minute, and second are given, the current
105 hour, minute, and second are taken.
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.
111 is a GNU extension that provides a reentrant version of
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
122 returns a pointer to a
124 Otherwise, it returns NULL and sets the global variable
126 to one of the error numbers shown below.
134 on error it returns one of the error numbers shown below.
136 The following errors are returned via
140 or as the function result (for
146 environment variable is not defined, or its value is an empty string.
149 The template file specified by
151 cannot be opened for reading.
154 Failed to get file status information.
158 The template file is not a regular file.
161 An error was encountered while reading the template file.
164 Memory allocation failed (not enough memory available).
165 .\" Error 6 doesn't seem to occur in glibc
168 There is no line in the file that matches the input.
171 Invalid input specification.
175 File containing format patterns.
183 For an explanation of the terms used in this section, see
189 Interface Attribute Value
197 MT-Unsafe race:getdate env locale
210 The POSIX.1 specification for
212 contains conversion specifications using the
216 modifier, while such specifications are not given for
222 so that precisely the same conversions are supported by both.
228 The program below calls
230 for each of its command-line arguments,
231 and for each call displays the values in the fields of the returned
234 The following shell session demonstrates the operation of the program:
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)"
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:
256 Call 2 ("2009\-12\-28") succeeded:
266 Call 3 ("12:22:33") succeeded:
280 .\" SRC BEGIN (getdate.c)
288 main(int argc, char *argv[])
292 for (size_t j = 1; j < argc; j++) {
293 tmp = getdate(argv[j]);
296 printf("Call %zu failed; getdate_err = %d\en",
301 printf("Call %zu (\e"%s\e") succeeded:\en", j, argv[j]);
302 printf(" tm_sec = %d\en", tmp\->tm_sec);
303 printf(" tm_min = %d\en", tmp\->tm_min);
304 printf(" tm_hour = %d\en", tmp\->tm_hour);
305 printf(" tm_mday = %d\en", tmp\->tm_mday);
306 printf(" tm_mon = %d\en", tmp\->tm_mon);
307 printf(" tm_year = %d\en", tmp\->tm_year);
308 printf(" tm_wday = %d\en", tmp\->tm_wday);
309 printf(" tm_yday = %d\en", tmp\->tm_yday);
310 printf(" tm_isdst = %d\en", tmp\->tm_isdst);