1GETDATE(P) POSIX Programmer's Manual GETDATE(P)
2
6 getdate - convert user format date and time
7
9 #include <time.h>
10 struct tm *getdate(const char *string);
12
15 The getdate() function shall convert a string representation of a date
16 or time into a broken-down time.
17 The external variable or macro getdate_err is used by getdate() to
19 return error values.
20 Templates are used to parse and interpret the input string. The tem‐
22 plates are contained in a text file identified by the environment vari‐
23 able DATEMSK . The DATEMSK variable should be set to indicate the full
24 pathname of the file that contains the templates. The first line in the
25 template that matches the input specification is used for interpreta‐
26 tion and conversion into the internal time format.
27 The following conversion specifications shall be supported:
29 %% Equivalent to % .
31 %a Abbreviated weekday name.
33 %A Full weekday name.
35 %b Abbreviated month name.
37 %B Full month name.
39 %c Locale's appropriate date and time representation.
41 %C Century number [00,99]; leading zeros are permitted but not
43 required.
44 %d Day of month [01,31]; the leading 0 is optional.
46 %D Date as %m / %d / %y .
48 %e Equivalent to %d .
50 %h Abbreviated month name.
52 %H Hour [00,23].
54 %I Hour [01,12].
56 %m Month number [01,12].
58 %M Minute [00,59].
60 %n Equivalent to <newline>.
62 %p Locale's equivalent of either AM or PM.
64 %r The locale's appropriate representation of time in AM and PM
66 notation. In the POSIX locale, this shall be equivalent to %I :
67 %M : %S %p .
68 %R Time as %H : %M .
70 %S Seconds [00,60]. The range goes to 60 (rather than stopping at
72 59) to allow positive leap seconds to be expressed. Since leap
73 seconds cannot be predicted by any algorithm, leap second data
74 must come from some external source.
75 %t Equivalent to <tab>.
77 %T Time as %H : %M : %S .
79 %w Weekday number (Sunday = [0,6]).
81 %x Locale's appropriate date representation.
83 %X Locale's appropriate time representation.
85 %y Year within century. When a century is not otherwise specified,
87 values in the range [69,99] shall refer to years 1969 to 1999
88 inclusive, and values in the range [00,68] shall refer to years
89 2000 to 2068 inclusive.
90 Note:
92 It is expected that in a future version of IEEE Std 1003.1-2001
93 the default century inferred from a 2-digit year will change.
94 (This would apply to all commands accepting a 2-digit year as
95 input.)
96 %Y Year as "ccyy" (for example, 2001).
99 %Z Timezone name or no characters if no timezone exists. If the
101 timezone supplied by %Z is not the timezone that getdate()
102 expects, an invalid input specification error shall result. The
103 getdate() function calculates an expected timezone based on
104 information supplied to the function (such as the hour, day, and
105 month).
106 The match between the template and input specification performed by
109 getdate() shall be case-insensitive.
110 The month and weekday names can consist of any combination of upper and
112 lowercase letters. The process can request that the input date or time
113 specification be in a specific language by setting the LC_TIME category
114 (see setlocale() ).
115 Leading zeros are not necessary for the descriptors that allow leading
117 zeros. However, at most two digits are allowed for those descriptors,
118 including leading zeros. Extra whitespace in either the template file
119 or in string shall be ignored.
120 The results are undefined if the conversion specifications %c , %x ,
122 and %X include unsupported conversion specifications.
123 The following rules apply for converting the input specification into
125 the internal format:
126 * If %Z is being scanned, then getdate() shall initialize the broken-
128 down time to be the current time in the scanned timezone. Otherwise,
129 it shall initialize the broken-down time based on the current local
130 time as if localtime() had been called.
131 * If only the weekday is given, the day chosen shall be the day,
133 starting with today and moving into the future, which first matches
134 the named day.
135 * If only the month (and no year) is given, the month chosen shall be
137 the month, starting with the current month and moving into the
138 future, which first matches the named month. The first day of the
139 month shall be assumed if no day is given.
140 * If no hour, minute, and second are given, the current hour, minute,
142 and second shall be assumed.
143 * If no date is given, the hour chosen shall be the hour, starting
145 with the current hour and moving into the future, which first
146 matches the named hour.
147 If a conversion specification in the DATEMSK file does not correspond
149 to one of the conversion specifications above, the behavior is unspeci‐
150 fied.
151 The getdate() function need not be reentrant. A function that is not
153 required to be reentrant is not required to be thread-safe.
154
156 Upon successful completion, getdate() shall return a pointer to a
157 struct tm. Otherwise, it shall return a null pointer and set get‐
158 date_err to indicate the error.
159
161 The getdate() function shall fail in the following cases, setting get‐
162 date_err to the value shown in the list below. Any changes to errno are
163 unspecified.
164 1. The DATEMSK environment variable is null or undefined.
166 2. The template file cannot be opened for reading.
168 3. Failed to get file status information.
170 4. The template file is not a regular file.
172 5. An I/O error is encountered while reading the template file.
174 6. Memory allocation failed (not enough memory available).
176 7. There is no line in the template that matches the input.
178 8. Invalid input specification. For example, February 31; or a time is
180 specified that cannot be represented in a time_t (representing the
181 time in seconds since the Epoch).
182 The following sections are informative.
184
186 1. The following example shows the possible contents of a template:
187 %m
190 %A %B %d, %Y, %H:%M:%S
191 %A
192 %B
193 %m/%d/%y %I %p
194 %d,%m,%Y %H:%M
195 at %A the %dst of %B in %Y
196 run job at %I %p,%B %dnd
197 %A den %d. %B %Y %H.%M Uhr
198 2. The following are examples of valid input specifications for the
200 template in Example 1:
201 getdate("10/1/87 4 PM");
204 getdate("Friday");
205 getdate("Friday September 18, 1987, 10:30:30");
206 getdate("24,9,1986 10:30");
207 getdate("at monday the 1st of december in 1986");
208 getdate("run job at 3 PM, december 2nd");
209 If the LC_TIME category is set to a German locale that includes freitag
211 as a weekday name and oktober as a month name, the following would be
212 valid:
213 getdate("freitag den 10. oktober 1986 10.30 Uhr");
216 3. The following example shows how local date and time specification
218 can be defined in the template:
219 Invocation Line in Template
221 getdate("11/27/86") %m/%d/%y
222 getdate("27.11.86") %d.%m.%y
223 getdate("86-11-27") %y-%m-%d
224 getdate("Friday 12:00:00") %A %H:%M:%S
225 4. The following examples help to illustrate the above rules assuming
227 that the current date is Mon Sep 22 12:19:47 EDT 1986 and the
228 LC_TIME category is set to the default C locale:
229 Input Line in Template Date
231 Mon %a Mon Sep 22 12:19:47 EDT 1986
232 Sun %a Sun Sep 28 12:19:47 EDT 1986
233 Fri %a Fri Sep 26 12:19:47 EDT 1986
234 September %B Mon Sep 1 12:19:47 EDT 1986
235 January %B Thu Jan 1 12:19:47 EST 1987
236 December %B Mon Dec 1 12:19:47 EST 1986
237 Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986
238 Jan Fri %b %a Fri Jan 2 12:19:47 EST 1987
239 Dec Mon %b %a Mon Dec 1 12:19:47 EST 1986
240 Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EST 1989
241 Fri 9 %a %H Fri Sep 26 09:00:00 EDT 1986
242 Feb 10:30 %b %H:%S Sun Feb 1 10:00:30 EST 1987
243 10:30 %H:%M Tue Sep 23 10:30:00 EDT 1986
244 13:30 %H:%M Mon Sep 22 13:30:00 EDT 1986
245
247 Although historical versions of getdate() did not require that <time.h>
248 declare the external variable getdate_err, this volume of
249 IEEE Std 1003.1-2001 does require it. The standard developers encourage
250 applications to remove declarations of getdate_err and instead incorpo‐
251 rate the declaration by including <time.h>.
252 Applications should use %Y (4-digit years) in preference to %y (2-digit
254 years).
255
257 In standard locales, the conversion specifications %c , %x , and %X do
258 not include unsupported conversion specifiers and so the text regarding
259 results being undefined is not a problem in that case.
260
262 None.
263
265 ctime() , localtime() , setlocale() , strftime() , times() , the Base
266 Definitions volume of IEEE Std 1003.1-2001, <time.h>
267
269 Portions of this text are reprinted and reproduced in electronic form
270 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
271 -- Portable Operating System Interface (POSIX), The Open Group Base
272 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
273 Electrical and Electronics Engineers, Inc and The Open Group. In the
274 event of any discrepancy between this version and the original IEEE and
275 The Open Group Standard, the original IEEE and The Open Group Standard
276 is the referee document. The original Standard can be obtained online
277 at http://www.opengroup.org/unix/online.html .
278IEEE/The Open Group 2003 GETDATE(P)