1GETDATE(3P)                POSIX Programmer's Manual               GETDATE(3P)
2
3
4

PROLOG

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

NAME

12       getdate — convert user format date and time
13

SYNOPSIS

15       #include <time.h>
16
17       struct tm *getdate(const char *string);
18

DESCRIPTION

20       The getdate() function shall convert a string representation of a  date
21       or time into a broken-down time.
22
23       The external variable or macro getdate_err, which has type int, is used
24       by getdate() to return error values. It  is  unspecified  whether  get‐
25       date_err  is  a  macro or an identifier declared with external linkage,
26       and whether or not it is a modifiable lvalue. If a macro definition  is
27       suppressed in order to access an actual object, or a program defines an
28       identifier with the name getdate_err, the behavior is undefined.
29
30       Templates are used to parse and interpret the input  string.  The  tem‐
31       plates are contained in a text file identified by the environment vari‐
32       able DATEMSK.  The DATEMSK variable should be set to indicate the  full
33       pathname of the file that contains the templates. The first line in the
34       template that matches the input specification is used  for  interpreta‐
35       tion and conversion into the internal time format.
36
37       The following conversion specifications shall be supported:
38
39       %%      Equivalent to %.
40
41       %a      Abbreviated weekday name.
42
43       %A      Full weekday name.
44
45       %b      Abbreviated month name.
46
47       %B      Full month name.
48
49       %c      Locale's appropriate date and time representation.
50
51       %C      Century  number  [00,99];  leading  zeros are permitted but not
52               required.
53
54       %d      Day of month [01,31]; the leading 0 is optional.
55
56       %D      Date as %m/%d/%y.
57
58       %e      Equivalent to %d.
59
60       %h      Abbreviated month name.
61
62       %H      Hour [00,23].
63
64       %I      Hour [01,12].
65
66       %m      Month number [01,12].
67
68       %M      Minute [00,59].
69
70       %n      Equivalent to <newline>.
71
72       %p      Locale's equivalent of either AM or PM.
73
74       %r      The locale's appropriate representation of time in  AM  and  PM
75               notation.   In  the  POSIX  locale, this shall be equivalent to
76               %I:%M:%S %p.
77
78       %R      Time as %H:%M.
79
80       %S      Seconds [00,60]. The range goes to 60 (rather than stopping  at
81               59)  to allow positive leap seconds to be expressed. Since leap
82               seconds cannot be predicted by any algorithm, leap second  data
83               must come from some external source.
84
85       %t      Equivalent to <tab>.
86
87       %T      Time as %H:%M:%S.
88
89       %w      Weekday number (Sunday = [0,6]).
90
91       %x      Locale's appropriate date representation.
92
93       %X      Locale's appropriate time representation.
94
95       %y      Year within century. When a century is not otherwise specified,
96               values in the range [69,99] shall refer to years 1969  to  1999
97               inclusive, and values in the range [00,68] shall refer to years
98               2000 to 2068 inclusive.
99
100               Note:     It is expected that in a future version of this stan‐
101                         dard the default century inferred from a 2-digit year
102                         will  change.  (This  would  apply  to  all  commands
103                         accepting a 2-digit year as input.)
104
105       %Y      Year as "ccyy" (for example, 2001).
106
107       %Z      Timezone  name  or  no characters if no timezone exists. If the
108               timezone supplied by %Z is  not  the  timezone  that  getdate()
109               expects, an invalid input specification error shall result. The
110               getdate() function calculates an  expected  timezone  based  on
111               information  supplied  to  the function (such as the hour, day,
112               and month).
113
114       The match between the template and  input  specification  performed  by
115       getdate() shall be case-insensitive.
116
117       The month and weekday names can consist of any combination of upper and
118       lowercase letters. The process can request that the input date or  time
119       specification be in a specific language by setting the LC_TIME category
120       (see setlocale()).
121
122       Leading zeros are not necessary for the descriptors that allow  leading
123       zeros.  However,  at most two digits are allowed for those descriptors,
124       including leading zeros. Extra white space in either the template  file
125       or in string shall be ignored.
126
127       The  results are undefined if the conversion specifications %c, %x, and
128       %X include unsupported conversion specifications.
129
130       The following rules apply for converting the input  specification  into
131       the internal format:
132
133        *  If %Z is being scanned, then getdate() shall initialize the broken-
134           down time to be the current time in the  scanned  timezone.  Other‐
135           wise, it shall initialize the broken-down time based on the current
136           local time as if localtime() had been called.
137
138        *  If only the weekday is given, the day  chosen  shall  be  the  day,
139           starting with today and moving into the future, which first matches
140           the named day.
141
142        *  If only the month (and no year) is given, the month chosen shall be
143           the  month,  starting  with  the  current month and moving into the
144           future, which first matches the named month. The first day  of  the
145           month shall be assumed if no day is given.
146
147        *  If no hour, minute, and second are given, the current hour, minute,
148           and second shall be assumed.
149
150        *  If no date is given, the hour chosen shall be  the  hour,  starting
151           with  the  current  hour  and  moving  into the future, which first
152           matches the named hour.
153
154       If a conversion specification in the DATEMSK file does  not  correspond
155       to one of the conversion specifications above, the behavior is unspeci‐
156       fied.
157
158       The getdate() function need not be thread-safe.
159

RETURN VALUE

161       Upon successful completion, getdate()  shall  return  a  pointer  to  a
162       struct  tm.   Otherwise,  it  shall  return a null pointer and set get‐
163       date_err to indicate the error.
164

ERRORS

166       The getdate() function shall fail in the following cases, setting  get‐
167       date_err to the value shown in the list below. Any changes to errno are
168       unspecified.
169
170        1. The DATEMSK environment variable is null or undefined.
171
172        2. The template file cannot be opened for reading.
173
174        3. Failed to get file status information.
175
176        4. The template file is not a regular file.
177
178        5. An I/O error is encountered while reading the template file.
179
180        6. Memory allocation failed (not enough memory available).
181
182        7. There is no line in the template that matches the input.
183
184        8. Invalid input specification. For example, February 31; or a time is
185           specified  that cannot be represented in a time_t (representing the
186           time in seconds since the Epoch).
187
188       The following sections are informative.
189

EXAMPLES

191        1. The following example shows the possible contents of a template:
192
193
194               %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
204        2. The following are examples of valid input  specifications  for  the
205           template in Example 1:
206
207
208               getdate("10/1/87 4 PM");
209               getdate("Friday");
210               getdate("Friday September 18, 1987, 10:30:30");
211               getdate("24,9,1986 10:30");
212               getdate("at monday the 1st of december in 1986");
213               getdate("run job at 3 PM, december 2nd");
214
215           If  the  LC_TIME  category  is set to a German locale that includes
216           freitag as a weekday name and oktober as a month name, the  follow‐
217           ing would be valid:
218
219
220               getdate("freitag den 10. oktober 1986 10.30 Uhr");
221
222        3. The  following  example shows how local date and time specification
223           can be defined in the template:
224
225                     ┌───────────────────────────┬──────────────────┐
226Invocation         Line in Template 
227                     ├───────────────────────────┼──────────────────┤
228                     │getdate("11/27/86")        │ %m/%d/%y         │
229                     │getdate("27.11.86")        │ %d.%m.%y         │
230                     │getdate("86-11-27")        │ %y-%m-%d         │
231                     │getdate("Friday 12:00:00") │ %A %H:%M:%S      │
232                     └───────────────────────────┴──────────────────┘
233        4. The following examples help to illustrate the above rules  assuming
234           that  the  current  date  is  Mon  Sep 22 12:19:47 EDT 1986 and the
235           LC_TIME category is set to the default C or POSIX locale:
236
237            ┌─────────────┬──────────────────┬──────────────────────────────┐
238Input     Line in Template Date             
239            ├─────────────┼──────────────────┼──────────────────────────────┤
240            │Mon          │ %a               │ Mon Sep 22 12:19:47 EDT 1986 │
241            │Sun          │ %a               │ Sun Sep 28 12:19:47 EDT 1986 │
242            │Fri          │ %a               │ Fri Sep 26 12:19:47 EDT 1986 │
243            │September    │ %B               │ Mon Sep 1 12:19:47 EDT 1986  │
244            │January      │ %B               │ Thu Jan 1 12:19:47 EST 1987  │
245            │December     │ %B               │ Mon Dec 1 12:19:47 EST 1986  │
246            │Sep Mon      │ %b %a            │ Mon Sep 1 12:19:47 EDT 1986  │
247            │Jan Fri      │ %b %a            │ Fri Jan 2 12:19:47 EST 1987  │
248            │Dec Mon      │ %b %a            │ Mon Dec 1 12:19:47 EST 1986  │
249            │Jan Wed 1989 │ %b %a %Y         │ Wed Jan 4 12:19:47 EST 1989  │
250            │Fri 9        │ %a %H            │ Fri Sep 26 09:00:00 EDT 1986 │
251            │Feb 10:30    │ %b %H:%S         │ Sun Feb 1 10:00:30 EST 1987  │
252            │10:30        │ %H:%M            │ Tue Sep 23 10:30:00 EDT 1986 │
253            │13:30        │ %H:%M            │ Mon Sep 22 13:30:00 EDT 1986 │
254            └─────────────┴──────────────────┴──────────────────────────────┘

APPLICATION USAGE

256       Although historical versions of getdate() did not require that <time.h>
257       declare  the external variable getdate_err, this volume of POSIX.1‐2017
258       does require it. The  standard  developers  encourage  applications  to
259       remove declarations of getdate_err and instead incorporate the declara‐
260       tion by including <time.h>.
261
262       Applications should use %Y (4-digit years) in preference to %y (2-digit
263       years).
264

RATIONALE

266       In  standard  locales,  the conversion specifications %c, %x, and %X do
267       not include unsupported conversion specifiers and so the text regarding
268       results being undefined is not a problem in that case.
269

FUTURE DIRECTIONS

271       None.
272

SEE ALSO

274       ctime(), localtime(), setlocale(), strftime(), times()
275
276       The Base Definitions volume of POSIX.1‐2017, <time.h>
277
279       Portions  of  this text are reprinted and reproduced in electronic form
280       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
281       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
282       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
283       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
284       event of any discrepancy between this version and the original IEEE and
285       The  Open Group Standard, the original IEEE and The Open Group Standard
286       is the referee document. The original Standard can be  obtained  online
287       at http://www.opengroup.org/unix/online.html .
288
289       Any  typographical  or  formatting  errors that appear in this page are
290       most likely to have been introduced during the conversion of the source
291       files  to  man page format. To report such errors, see https://www.ker
292       nel.org/doc/man-pages/reporting_bugs.html .
293
294
295
296IEEE/The Open Group                  2017                          GETDATE(3P)
Impressum