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 specifi‐
127 cations using the %E or %O modifier, while such specifications are not
128 given for getdate(). In glibc, getdate() is implemented using strp‐
129 time(3), so that precisely the same conversions are supported by both.
130
132 POSIX.1-2008.
133
135 POSIX.1-2001.
136
138 The program below calls getdate() for each of its command-line argu‐
139 ments, and for each call displays the values in the fields of the re‐
140 turned tm structure. The following shell session demonstrates the op‐
141 eration of the program:
142 $ TFILE=$PWD/tfile
144 $ echo '%A' > $TFILE # Full name of the day of the week
145 $ echo '%T' >> $TFILE # Time (HH:MM:SS)
146 $ echo '%F' >> $TFILE # ISO date (YYYY-MM-DD)
147 $ date
148 $ export DATEMSK=$TFILE
149 $ ./a.out Tuesday '2009-12-28' '12:22:33'
150 Sun Sep 7 06:03:36 CEST 2008
151 Call 1 ("Tuesday") succeeded:
152 tm_sec = 36
153 tm_min = 3
154 tm_hour = 6
155 tm_mday = 9
156 tm_mon = 8
157 tm_year = 108
158 tm_wday = 2
159 tm_yday = 252
160 tm_isdst = 1
161 Call 2 ("2009-12-28") succeeded:
162 tm_sec = 36
163 tm_min = 3
164 tm_hour = 6
165 tm_mday = 28
166 tm_mon = 11
167 tm_year = 109
168 tm_wday = 1
169 tm_yday = 361
170 tm_isdst = 0
171 Call 3 ("12:22:33") succeeded:
172 tm_sec = 33
173 tm_min = 22
174 tm_hour = 12
175 tm_mday = 7
176 tm_mon = 8
177 tm_year = 108
178 tm_wday = 0
179 tm_yday = 250
180 tm_isdst = 1
181 Program source
183 #define _GNU_SOURCE
185 #include <stdio.h>
186 #include <stdlib.h>
187 #include <time.h>
188 int
190 main(int argc, char *argv[])
191 {
192 struct tm *tmp;
193 for (size_t j = 1; j < argc; j++) {
195 tmp = getdate(argv[j]);
196 if (tmp == NULL) {
198 printf("Call %zu failed; getdate_err = %d\n",
199 j, getdate_err);
200 continue;
201 }
202 printf("Call %zu (\"%s\") succeeded:\n", j, argv[j]);
204 printf(" tm_sec = %d\n", tmp->tm_sec);
205 printf(" tm_min = %d\n", tmp->tm_min);
206 printf(" tm_hour = %d\n", tmp->tm_hour);
207 printf(" tm_mday = %d\n", tmp->tm_mday);
208 printf(" tm_mon = %d\n", tmp->tm_mon);
209 printf(" tm_year = %d\n", tmp->tm_year);
210 printf(" tm_wday = %d\n", tmp->tm_wday);
211 printf(" tm_yday = %d\n", tmp->tm_yday);
212 printf(" tm_isdst = %d\n", tmp->tm_isdst);
213 }
214 exit(EXIT_SUCCESS);
216 }
217
219 time(2), localtime(3), setlocale(3), strftime(3), strptime(3)
220Linux man-pages 6.04 2023-03-30 getdate(3)