1getdate(3) Library Functions Manual getdate(3)
2
6 getdate, getdate_r - convert a date-plus-time string to broken-down
7 time
8
10 Standard C library (libc, -lc)
11
13 #include <time.h>
14 struct tm *getdate(const char *string);
16 extern int getdate_err;
18 int getdate_r(const char *restrict string, struct tm *restrict res);
20 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
22 getdate():
24 _XOPEN_SOURCE >= 500
25 getdate_r():
27 _GNU_SOURCE
28
30 The function getdate() converts a string representation of a date and
31 time, contained in the buffer pointed to by string, into a broken-down
32 time. The broken-down time is stored in a tm structure, and a pointer
33 to this structure is returned as the function result. This tm struc‐
34 ture is allocated in static storage, and consequently it will be over‐
35 written by further calls to getdate().
36 In contrast to strptime(3), (which has a format argument), getdate()
38 uses the formats found in the file whose full pathname is given in the
39 environment variable DATEMSK. The first line in the file that matches
40 the given input string is used for the conversion.
41 The matching is done case insensitively. Superfluous whitespace, ei‐
43 ther in the pattern or in the string to be converted, is ignored.
44 The conversion specifications that a pattern can contain are those
46 given for strptime(3). One more conversion specification is specified
47 in POSIX.1-2001:
48 %Z Timezone name. This is not implemented in glibc.
50 When %Z is given, the structure containing the broken-down time is ini‐
52 tialized with values corresponding to the current time in the given
53 timezone. Otherwise, the structure is initialized to the broken-down
54 time corresponding to the current local time (as by a call to local‐
55 time(3)).
56 When only the day of the week is given, the day is taken to be the
58 first such day on or after today.
59 When only the month is given (and no year), the month is taken to be
61 the first such month equal to or after the current month. If no day is
62 given, it is the first day of the month.
63 When no hour, minute, and second are given, the current hour, minute,
65 and second are taken.
66 If no date is given, but we know the hour, then that hour is taken to
68 be the first such hour equal to or after the current hour.
69 getdate_r() is a GNU extension that provides a reentrant version of
71 getdate(). Rather than using a global variable to report errors and a
72 static buffer to return the broken down time, it returns errors via the
73 function result value, and returns the resulting broken-down time in
74 the caller-allocated buffer pointed to by the argument res.
75
77 When successful, getdate() returns a pointer to a struct tm. Other‐
78 wise, it returns NULL and sets the global variable getdate_err to one
79 of the error numbers shown below. Changes to errno are unspecified.
80 On success getdate_r() returns 0; on error it returns one of the error
82 numbers shown below.
83
85 The following errors are returned via getdate_err (for getdate()) or as
86 the function result (for getdate_r()):
87 1 The DATEMSK environment variable is not defined, or its value is an
89 empty string.
90 2 The template file specified by DATEMSK cannot be opened for read‐
92 ing.
93 3 Failed to get file status information.
95 4 The template file is not a regular file.
97 5 An error was encountered while reading the template file.
99 6 Memory allocation failed (not enough memory available).
101 7 There is no line in the file that matches the input.
103 8 Invalid input specification.
105
107 DATEMSK
108 File containing format patterns.
109 TZ, LC_TIME
111 Variables used by strptime(3).
112
114 For an explanation of the terms used in this section, see at‐
115 tributes(7).
116 ┌────────────┬───────────────┬─────────────────────────────────────────┐
118 │Interface │ Attribute │ Value │
119 ├────────────┼───────────────┼─────────────────────────────────────────┤
120 │getdate() │ Thread safety │ MT-Unsafe race:getdate env locale │
121 ├────────────┼───────────────┼─────────────────────────────────────────┤
122 │getdate_r() │ Thread safety │ MT-Safe env locale │
123 └────────────┴───────────────┴─────────────────────────────────────────┘
124
126 The POSIX.1 specification for strptime(3) contains conversion
127 specifications using the %E or %O modifier, while such specifications
128 are not given for getdate(). In glibc, getdate() is implemented using
129 strptime(3), so that precisely the same conversions are supported by
130 both.
131
133 POSIX.1-2008.
134
136 POSIX.1-2001.
137
139 The program below calls getdate() for each of its command-line
140 arguments, and for each call displays the values in the fields of the
141 returned tm structure. The following shell session demonstrates the
142 operation of the program:
143 $ TFILE=$PWD/tfile
145 $ echo '%A' > $TFILE # Full name of the day of the week
146 $ echo '%T' >> $TFILE # Time (HH:MM:SS)
147 $ echo '%F' >> $TFILE # ISO date (YYYY-MM-DD)
148 $ date
149 $ export DATEMSK=$TFILE
150 $ ./a.out Tuesday '2009-12-28' '12:22:33'
151 Sun Sep 7 06:03:36 CEST 2008
152 Call 1 ("Tuesday") succeeded:
153 tm_sec = 36
154 tm_min = 3
155 tm_hour = 6
156 tm_mday = 9
157 tm_mon = 8
158 tm_year = 108
159 tm_wday = 2
160 tm_yday = 252
161 tm_isdst = 1
162 Call 2 ("2009-12-28") succeeded:
163 tm_sec = 36
164 tm_min = 3
165 tm_hour = 6
166 tm_mday = 28
167 tm_mon = 11
168 tm_year = 109
169 tm_wday = 1
170 tm_yday = 361
171 tm_isdst = 0
172 Call 3 ("12:22:33") succeeded:
173 tm_sec = 33
174 tm_min = 22
175 tm_hour = 12
176 tm_mday = 7
177 tm_mon = 8
178 tm_year = 108
179 tm_wday = 0
180 tm_yday = 250
181 tm_isdst = 1
182 Program source
184 #define _GNU_SOURCE
186 #include <stdio.h>
187 #include <stdlib.h>
188 #include <time.h>
189 int
191 main(int argc, char *argv[])
192 {
193 struct tm *tmp;
194 for (size_t j = 1; j < argc; j++) {
196 tmp = getdate(argv[j]);
197 if (tmp == NULL) {
199 printf("Call %zu failed; getdate_err = %d\n",
200 j, getdate_err);
201 continue;
202 }
203 printf("Call %zu (\"%s\") succeeded:\n", j, argv[j]);
205 printf(" tm_sec = %d\n", tmp->tm_sec);
206 printf(" tm_min = %d\n", tmp->tm_min);
207 printf(" tm_hour = %d\n", tmp->tm_hour);
208 printf(" tm_mday = %d\n", tmp->tm_mday);
209 printf(" tm_mon = %d\n", tmp->tm_mon);
210 printf(" tm_year = %d\n", tmp->tm_year);
211 printf(" tm_wday = %d\n", tmp->tm_wday);
212 printf(" tm_yday = %d\n", tmp->tm_yday);
213 printf(" tm_isdst = %d\n", tmp->tm_isdst);
214 }
215 exit(EXIT_SUCCESS);
217 }
218
220 time(2), localtime(3), setlocale(3), strftime(3), strptime(3)
221Linux man-pages 6.05 2023-07-20 getdate(3)