1GETDATE(3P) POSIX Programmer's Manual GETDATE(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 getdate — convert user format date and time
14
16 #include <time.h>
17 struct tm *getdate(const char *string);
19
21 The getdate() function shall convert a string representation of a date
22 or time into a broken-down time.
23 The external variable or macro getdate_err, which has type int, is used
25 by getdate() to return error values. It is unspecified whether get‐
26 date_err is a macro or an identifier declared with external linkage,
27 and whether or not it is a modifiable lvalue. If a macro definition is
28 suppressed in order to access an actual object, or a program defines an
29 identifier with the name getdate_err, the behavior is undefined.
30 Templates are used to parse and interpret the input string. The tem‐
32 plates are contained in a text file identified by the environment vari‐
33 able DATEMSK. The DATEMSK variable should be set to indicate the full
34 pathname of the file that contains the templates. The first line in the
35 template that matches the input specification is used for interpreta‐
36 tion and conversion into the internal time format.
37 The following conversion specifications shall be supported:
39 %% Equivalent to %.
41 %a Abbreviated weekday name.
43 %A Full weekday name.
45 %b Abbreviated month name.
47 %B Full month name.
49 %c Locale's appropriate date and time representation.
51 %C Century number [00,99]; leading zeros are permitted but not
53 required.
54 %d Day of month [01,31]; the leading 0 is optional.
56 %D Date as %m/%d/%y.
58 %e Equivalent to %d.
60 %h Abbreviated month name.
62 %H Hour [00,23].
64 %I Hour [01,12].
66 %m Month number [01,12].
68 %M Minute [00,59].
70 %n Equivalent to <newline>.
72 %p Locale's equivalent of either AM or PM.
74 %r The locale's appropriate representation of time in AM and PM
76 notation. In the POSIX locale, this shall be equivalent to
77 %I:%M:%S %p.
78 %R Time as %H:%M.
80 %S Seconds [00,60]. The range goes to 60 (rather than stopping at
82 59) to allow positive leap seconds to be expressed. Since leap
83 seconds cannot be predicted by any algorithm, leap second data
84 must come from some external source.
85 %t Equivalent to <tab>.
87 %T Time as %H:%M:%S.
89 %w Weekday number (Sunday = [0,6]).
91 %x Locale's appropriate date representation.
93 %X Locale's appropriate time representation.
95 %y Year within century. When a century is not otherwise specified,
97 values in the range [69,99] shall refer to years 1969 to 1999
98 inclusive, and values in the range [00,68] shall refer to years
99 2000 to 2068 inclusive.
100 Note: It is expected that in a future version of this stan‐
102 dard the default century inferred from a 2-digit year
103 will change. (This would apply to all commands
104 accepting a 2-digit year as input.)
105 %Y Year as "ccyy" (for example, 2001).
107 %Z Timezone name or no characters if no timezone exists. If the
109 timezone supplied by %Z is not the timezone that getdate()
110 expects, an invalid input specification error shall result. The
111 getdate() function calculates an expected timezone based on
112 information supplied to the function (such as the hour, day,
113 and month).
114 The match between the template and input specification performed by
116 getdate() shall be case-insensitive.
117 The month and weekday names can consist of any combination of upper and
119 lowercase letters. The process can request that the input date or time
120 specification be in a specific language by setting the LC_TIME category
121 (see setlocale()).
122 Leading zeros are not necessary for the descriptors that allow leading
124 zeros. However, at most two digits are allowed for those descriptors,
125 including leading zeros. Extra white space in either the template file
126 or in string shall be ignored.
127 The results are undefined if the conversion specifications %c, %x, and
129 %X include unsupported conversion specifications.
130 The following rules apply for converting the input specification into
132 the internal format:
133 * If %Z is being scanned, then getdate() shall initialize the broken-
135 down time to be the current time in the scanned timezone. Other‐
136 wise, it shall initialize the broken-down time based on the current
137 local time as if localtime() had been called.
138 * If only the weekday is given, the day chosen shall be the day,
140 starting with today and moving into the future, which first matches
141 the named day.
142 * If only the month (and no year) is given, the month chosen shall be
144 the month, starting with the current month and moving into the
145 future, which first matches the named month. The first day of the
146 month shall be assumed if no day is given.
147 * If no hour, minute, and second are given, the current hour, minute,
149 and second shall be assumed.
150 * If no date is given, the hour chosen shall be the hour, starting
152 with the current hour and moving into the future, which first
153 matches the named hour.
154 If a conversion specification in the DATEMSK file does not correspond
156 to one of the conversion specifications above, the behavior is unspeci‐
157 fied.
158 The getdate() function need not be thread-safe.
160
162 Upon successful completion, getdate() shall return a pointer to a
163 struct tm. Otherwise, it shall return a null pointer and set get‐
164 date_err to indicate the error.
165
167 The getdate() function shall fail in the following cases, setting get‐
168 date_err to the value shown in the list below. Any changes to errno are
169 unspecified.
170 1. The DATEMSK environment variable is null or undefined.
172 2. The template file cannot be opened for reading.
174 3. Failed to get file status information.
176 4. The template file is not a regular file.
178 5. An I/O error is encountered while reading the template file.
180 6. Memory allocation failed (not enough memory available).
182 7. There is no line in the template that matches the input.
184 8. Invalid input specification. For example, February 31; or a time is
186 specified that cannot be represented in a time_t (representing the
187 time in seconds since the Epoch).
188 The following sections are informative.
190
192 1. The following example shows the possible contents of a template:
193 %m
195 %A %B %d, %Y, %H:%M:%S
196 %A
197 %B
198 %m/%d/%y %I %p
199 %d,%m,%Y %H:%M
200 at %A the %dst of %B in %Y
201 run job at %I %p,%B %dnd
202 %A den %d. %B %Y %H.%M Uhr
203 2. The following are examples of valid input specifications for the
205 template in Example 1:
206 getdate("10/1/87 4 PM");
208 getdate("Friday");
209 getdate("Friday September 18, 1987, 10:30:30");
210 getdate("24,9,1986 10:30");
211 getdate("at monday the 1st of december in 1986");
212 getdate("run job at 3 PM, december 2nd");
213 If the LC_TIME category is set to a German locale that includes
215 freitag as a weekday name and oktober as a month name, the follow‐
216 ing would be valid:
217 getdate("freitag den 10. oktober 1986 10.30 Uhr");
219 3. The following example shows how local date and time specification
221 can be defined in the template:
222 ┌───────────────────────────┬──────────────────┐
224 │ Invocation │ Line in Template │
225 ├───────────────────────────┼──────────────────┤
226 │getdate("11/27/86") │ %m/%d/%y │
227 │getdate("27.11.86") │ %d.%m.%y │
228 │getdate("86-11-27") │ %y-%m-%d │
229 │getdate("Friday 12:00:00") │ %A %H:%M:%S │
230 └───────────────────────────┴──────────────────┘
231 4. The following examples help to illustrate the above rules assuming
232 that the current date is Mon Sep 22 12:19:47 EDT 1986 and the
233 LC_TIME category is set to the default C locale:
234 ┌─────────────┬──────────────────┬──────────────────────────────┐
236 │ Input │ Line in Template │ Date │
237 ├─────────────┼──────────────────┼──────────────────────────────┤
238 │Mon │ %a │ Mon Sep 22 12:19:47 EDT 1986 │
239 │Sun │ %a │ Sun Sep 28 12:19:47 EDT 1986 │
240 │Fri │ %a │ Fri Sep 26 12:19:47 EDT 1986 │
241 │September │ %B │ Mon Sep 1 12:19:47 EDT 1986 │
242 │January │ %B │ Thu Jan 1 12:19:47 EST 1987 │
243 │December │ %B │ Mon Dec 1 12:19:47 EST 1986 │
244 │Sep Mon │ %b %a │ Mon Sep 1 12:19:47 EDT 1986 │
245 │Jan Fri │ %b %a │ Fri Jan 2 12:19:47 EST 1987 │
246 │Dec Mon │ %b %a │ Mon Dec 1 12:19:47 EST 1986 │
247 │Jan Wed 1989 │ %b %a %Y │ Wed Jan 4 12:19:47 EST 1989 │
248 │Fri 9 │ %a %H │ Fri Sep 26 09:00:00 EDT 1986 │
249 │Feb 10:30 │ %b %H:%S │ Sun Feb 1 10:00:30 EST 1987 │
250 │10:30 │ %H:%M │ Tue Sep 23 10:30:00 EDT 1986 │
251 │13:30 │ %H:%M │ Mon Sep 22 13:30:00 EDT 1986 │
252 └─────────────┴──────────────────┴──────────────────────────────┘
254 Although historical versions of getdate() did not require that <time.h>
255 declare the external variable getdate_err, this volume of POSIX.1‐2008
256 does require it. The standard developers encourage applications to
257 remove declarations of getdate_err and instead incorporate the declara‐
258 tion by including <time.h>.
259 Applications should use %Y (4-digit years) in preference to %y (2-digit
261 years).
262
264 In standard locales, the conversion specifications %c, %x, and %X do
265 not include unsupported conversion specifiers and so the text regarding
266 results being undefined is not a problem in that case.
267
269 None.
270
272 ctime(), localtime(), setlocale(), strftime(), times()
273 The Base Definitions volume of POSIX.1‐2008, <time.h>
275
277 Portions of this text are reprinted and reproduced in electronic form
278 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
279 -- Portable Operating System Interface (POSIX), The Open Group Base
280 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
281 cal and Electronics Engineers, Inc and The Open Group. (This is
282 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
283 event of any discrepancy between this version and the original IEEE and
284 The Open Group Standard, the original IEEE and The Open Group Standard
285 is the referee document. The original Standard can be obtained online
286 at http://www.unix.org/online.html .
287 Any typographical or formatting errors that appear in this page are
289 most likely to have been introduced during the conversion of the source
290 files to man page format. To report such errors, see https://www.ker‐
291 nel.org/doc/man-pages/reporting_bugs.html .
292IEEE/The Open Group 2013 GETDATE(3P)