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