1GETDATE(3) Linux Programmer's Manual GETDATE(3)
2
6 getdate, getdate_r - convert a date-plus-time string to broken-down
7 time
8
10 #include <time.h>
11 struct tm *getdate(const char *string);
13 extern int getdate_err;
15 #include <time.h>
17 int getdate_r(const char *restrict string, struct tm *restrict res);
19 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
21 getdate():
23 _XOPEN_SOURCE >= 500
24 getdate_r():
26 _GNU_SOURCE
27
29 The function getdate() converts a string representation of a date and
30 time, contained in the buffer pointed to by string, into a broken-down
31 time. The broken-down time is stored in a tm structure, and a pointer
32 to this structure is returned as the function result. This tm struc‐
33 ture is allocated in static storage, and consequently it will be over‐
34 written by further calls to getdate().
35 In contrast to strptime(3), (which has a format argument), getdate()
37 uses the formats found in the file whose full pathname is given in the
38 environment variable DATEMSK. The first line in the file that matches
39 the given input string is used for the conversion.
40 The matching is done case insensitively. Superfluous whitespace, ei‐
42 ther in the pattern or in the string to be converted, is ignored.
43 The conversion specifications that a pattern can contain are those
45 given for strptime(3). One more conversion specification is specified
46 in POSIX.1-2001:
47 %Z Timezone name. This is not implemented in glibc.
49 When %Z is given, the structure containing the broken-down time is ini‐
51 tialized with values corresponding to the current time in the given
52 timezone. Otherwise, the structure is initialized to the broken-down
53 time corresponding to the current local time (as by a call to local‐
54 time(3)).
55 When only the day of the week is given, the day is taken to be the
57 first such day on or after today.
58 When only the month is given (and no year), the month is taken to be
60 the first such month equal to or after the current month. If no day is
61 given, it is the first day of the month.
62 When no hour, minute, and second are given, the current hour, minute,
64 and second are taken.
65 If no date is given, but we know the hour, then that hour is taken to
67 be the first such hour equal to or after the current hour.
68 getdate_r() is a GNU extension that provides a reentrant version of
70 getdate(). Rather than using a global variable to report errors and a
71 static buffer to return the broken down time, it returns errors via the
72 function result value, and returns the resulting broken-down time in
73 the caller-allocated buffer pointed to by the argument res.
74
76 When successful, getdate() returns a pointer to a struct tm. Other‐
77 wise, it returns NULL and sets the global variable getdate_err to one
78 of the error numbers shown below. Changes to errno are unspecified.
79 On success getdate_r() returns 0; on error it returns one of the error
81 numbers shown below.
82
84 The following errors are returned via getdate_err (for getdate()) or as
85 the function result (for getdate_r()):
86 1 The DATEMSK environment variable is not defined, or its value is an
88 empty string.
89 2 The template file specified by DATEMSK cannot be opened for read‐
91 ing.
92 3 Failed to get file status information.
94 4 The template file is not a regular file.
96 5 An error was encountered while reading the template file.
98 6 Memory allocation failed (not enough memory available).
100 7 There is no line in the file that matches the input.
102 8 Invalid input specification.
104
106 DATEMSK
107 File containing format patterns.
108 TZ, LC_TIME
110 Variables used by strptime(3).
111
113 For an explanation of the terms used in this section, see at‐
114 tributes(7).
115 ┌────────────┬───────────────┬─────────────────────────────────────────┐
117 │Interface │ Attribute │ Value │
118 ├────────────┼───────────────┼─────────────────────────────────────────┤
119 │getdate() │ Thread safety │ MT-Unsafe race:getdate env locale │
120 ├────────────┼───────────────┼─────────────────────────────────────────┤
121 │getdate_r() │ Thread safety │ MT-Safe env locale │
122 └────────────┴───────────────┴─────────────────────────────────────────┘
123
125 POSIX.1-2001, POSIX.1-2008.
126
128 The POSIX.1 specification for strptime(3) contains conversion specifi‐
129 cations using the %E or %O modifier, while such specifications are not
130 given for getdate(). In glibc, getdate() is implemented using strp‐
131 time(3), so that precisely the same conversions are supported by both.
132
134 The program below calls getdate() for each of its command-line argu‐
135 ments, and for each call displays the values in the fields of the re‐
136 turned tm structure. The following shell session demonstrates the op‐
137 eration of the program:
138 $ TFILE=$PWD/tfile
140 $ echo '%A' > $TFILE # Full name of the day of the week
141 $ echo '%T' >> $TFILE # ISO date (YYYY-MM-DD)
142 $ echo '%F' >> $TFILE # Time (HH:MM:SS)
143 $ date
144 $ export DATEMSK=$TFILE
145 $ ./a.out Tuesday '2009-12-28' '12:22:33'
146 Sun Sep 7 06:03:36 CEST 2008
147 Call 1 ("Tuesday") succeeded:
148 tm_sec = 36
149 tm_min = 3
150 tm_hour = 6
151 tm_mday = 9
152 tm_mon = 8
153 tm_year = 108
154 tm_wday = 2
155 tm_yday = 252
156 tm_isdst = 1
157 Call 2 ("2009-12-28") succeeded:
158 tm_sec = 36
159 tm_min = 3
160 tm_hour = 6
161 tm_mday = 28
162 tm_mon = 11
163 tm_year = 109
164 tm_wday = 1
165 tm_yday = 361
166 tm_isdst = 0
167 Call 3 ("12:22:33") succeeded:
168 tm_sec = 33
169 tm_min = 22
170 tm_hour = 12
171 tm_mday = 7
172 tm_mon = 8
173 tm_year = 108
174 tm_wday = 0
175 tm_yday = 250
176 tm_isdst = 1
177 Program source
179 #define _GNU_SOURCE
181 #include <time.h>
182 #include <stdio.h>
183 #include <stdlib.h>
184 int
186 main(int argc, char *argv[])
187 {
188 struct tm *tmp;
189 for (int j = 1; j < argc; j++) {
191 tmp = getdate(argv[j]);
192 if (tmp == NULL) {
194 printf("Call %d failed; getdate_err = %d\n",
195 j, getdate_err);
196 continue;
197 }
198 printf("Call %d (\"%s\") succeeded:\n", j, argv[j]);
200 printf(" tm_sec = %d\n", tmp->tm_sec);
201 printf(" tm_min = %d\n", tmp->tm_min);
202 printf(" tm_hour = %d\n", tmp->tm_hour);
203 printf(" tm_mday = %d\n", tmp->tm_mday);
204 printf(" tm_mon = %d\n", tmp->tm_mon);
205 printf(" tm_year = %d\n", tmp->tm_year);
206 printf(" tm_wday = %d\n", tmp->tm_wday);
207 printf(" tm_yday = %d\n", tmp->tm_yday);
208 printf(" tm_isdst = %d\n", tmp->tm_isdst);
209 }
210 exit(EXIT_SUCCESS);
212 }
213
215 time(2), localtime(3), setlocale(3), strftime(3), strptime(3)
216
218 This page is part of release 5.12 of the Linux man-pages project. A
219 description of the project, information about reporting bugs, and the
220 latest version of this page, can be found at
221 https://www.kernel.org/doc/man-pages/.
222 2021-03-22 GETDATE(3)