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 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
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,
41 either 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 weekday is given, the day is taken to be the first such
56 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 Multithreading (see pthreads(7))
113 The getdate() function is not thread-safe.
114 The getdate_r() function is thread-safe.
116
118 POSIX.1-2001.
119
121 The POSIX.1-2001 specification for strptime(3) contains conversion
122 specifications using the %E or %O modifier, while such specifications
123 are not given for getdate(). In glibc, getdate() is implemented using
124 strptime(3), so that precisely the same conversions are supported by
125 both.
126
128 The program below calls getdate() for each of its command-line argu‐
129 ments, and for each call displays the values in the fields of the
130 returned tm structure. The following shell session demonstrates the
131 operation of the program:
132 $ TFILE=$PWD/tfile
134 $ echo '%A' > $TFILE # Full weekday name
135 $ echo '%T' >> $TFILE # ISO date (YYYY-MM-DD)
136 $ echo '%F' >> $TFILE # Time (HH:MM:SS)
137 $ date
138 $ export DATEMSK=$TFILE
139 $ ./a.out Tuesday '2009-12-28' '12:22:33'
140 Sun Sep 7 06:03:36 CEST 2008
141 Call 1 ("Tuesday") succeeded:
142 tm_sec = 36
143 tm_min = 3
144 tm_hour = 6
145 tm_mday = 9
146 tm_mon = 8
147 tm_year = 108
148 tm_wday = 2
149 tm_yday = 252
150 tm_isdst = 1
151 Call 2 ("2009-12-28") succeeded:
152 tm_sec = 36
153 tm_min = 3
154 tm_hour = 6
155 tm_mday = 28
156 tm_mon = 11
157 tm_year = 109
158 tm_wday = 1
159 tm_yday = 361
160 tm_isdst = 0
161 Call 3 ("12:22:33") succeeded:
162 tm_sec = 33
163 tm_min = 22
164 tm_hour = 12
165 tm_mday = 7
166 tm_mon = 8
167 tm_year = 108
168 tm_wday = 0
169 tm_yday = 250
170 tm_isdst = 1
171 Program source
173 #define _GNU_SOURCE 500
175 #include <time.h>
176 #include <stdio.h>
177 #include <stdlib.h>
178 int
180 main(int argc, char *argv[])
181 {
182 struct tm *tmp;
183 int j;
184 for (j = 1; j < argc; j++) {
186 tmp = getdate(argv[j]);
187 if (tmp == NULL) {
189 printf("Call %d failed; getdate_err = %d\n",
190 j, getdate_err);
191 continue;
192 }
193 printf("Call %d (\"%s\") succeeded:\n", j, argv[j]);
195 printf(" tm_sec = %d\n", tmp->tm_sec);
196 printf(" tm_min = %d\n", tmp->tm_min);
197 printf(" tm_hour = %d\n", tmp->tm_hour);
198 printf(" tm_mday = %d\n", tmp->tm_mday);
199 printf(" tm_mon = %d\n", tmp->tm_mon);
200 printf(" tm_year = %d\n", tmp->tm_year);
201 printf(" tm_wday = %d\n", tmp->tm_wday);
202 printf(" tm_yday = %d\n", tmp->tm_yday);
203 printf(" tm_isdst = %d\n", tmp->tm_isdst);
204 }
205 exit(EXIT_SUCCESS);
207 }
208
210 time(2), localtime(3), setlocale(3), strftime(3), strptime(3)
211
213 This page is part of release 3.53 of the Linux man-pages project. A
214 description of the project, and information about reporting bugs, can
215 be found at http://www.kernel.org/doc/man-pages/.
216 2013-06-21 GETDATE(3)