1GETDATE(3)                 Linux Programmer's Manual                GETDATE(3)
2
3
4

NAME

6       getdate,  getdate_r  -  convert  a date-plus-time string to broken-down
7       time
8

SYNOPSIS

10       #include <time.h>
11
12       struct tm *getdate(const char *string);
13
14       extern int getdate_err;
15
16       #include <time.h>
17
18       int getdate_r(const char *restrict string, struct tm *restrict res);
19
20   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
21
22       getdate():
23           _XOPEN_SOURCE >= 500
24
25       getdate_r():
26           _GNU_SOURCE
27

DESCRIPTION

29       The function getdate() converts a string representation of a  date  and
30       time,  contained in the buffer pointed to by string, into a broken-down
31       time.  The broken-down time is stored in a tm structure, and a  pointer
32       to  this  structure is returned as the function result.  This tm struc‐
33       ture is allocated in static storage, and consequently it will be  over‐
34       written by further calls to getdate().
35
36       In  contrast  to  strptime(3), (which has a format argument), getdate()
37       uses the formats found in the file whose full pathname is given in  the
38       environment  variable DATEMSK.  The first line in the file that matches
39       the given input string is used for the conversion.
40
41       The matching is done case insensitively.  Superfluous  whitespace,  ei‐
42       ther in the pattern or in the string to be converted, is ignored.
43
44       The  conversion  specifications  that  a  pattern can contain are those
45       given for strptime(3).  One more conversion specification is  specified
46       in POSIX.1-2001:
47
48       %Z     Timezone name.  This is not implemented in glibc.
49
50       When %Z is given, the structure containing the broken-down time is ini‐
51       tialized with values corresponding to the current  time  in  the  given
52       timezone.   Otherwise,  the structure is initialized to the broken-down
53       time corresponding to the current local time (as by a  call  to  local‐
54       time(3)).
55
56       When  only  the  day  of  the week is given, the day is taken to be the
57       first such day on or after today.
58
59       When only the month is given (and no year), the month is  taken  to  be
60       the first such month equal to or after the current month.  If no day is
61       given, it is the first day of the month.
62
63       When no hour, minute, and second are given, the current  hour,  minute,
64       and second are taken.
65
66       If  no  date is given, but we know the hour, then that hour is taken to
67       be the first such hour equal to or after the current hour.
68
69       getdate_r() is a GNU extension that provides  a  reentrant  version  of
70       getdate().   Rather than using a global variable to report errors and a
71       static buffer to return the broken down time, it returns errors via the
72       function  result  value,  and returns the resulting broken-down time in
73       the caller-allocated buffer pointed to by the argument res.
74

RETURN VALUE

76       When successful, getdate() returns a pointer to a  struct  tm.   Other‐
77       wise,  it  returns NULL and sets the global variable getdate_err to one
78       of the error numbers shown below.  Changes to errno are unspecified.
79
80       On success getdate_r() returns 0; on error it returns one of the  error
81       numbers shown below.
82

ERRORS

84       The following errors are returned via getdate_err (for getdate()) or as
85       the function result (for getdate_r()):
86
87       1   The DATEMSK environment variable is not defined, or its value is an
88           empty string.
89
90       2   The  template  file specified by DATEMSK cannot be opened for read‐
91           ing.
92
93       3   Failed to get file status information.
94
95       4   The template file is not a regular file.
96
97       5   An error was encountered while reading the template file.
98
99       6   Memory allocation failed (not enough memory available).
100
101       7   There is no line in the file that matches the input.
102
103       8   Invalid input specification.
104

ENVIRONMENT

106       DATEMSK
107              File containing format patterns.
108
109       TZ, LC_TIME
110              Variables used by strptime(3).
111

ATTRIBUTES

113       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
114       tributes(7).
115
116       ┌────────────┬───────────────┬─────────────────────────────────────────┐
117Interface   Attribute     Value                                   
118       ├────────────┼───────────────┼─────────────────────────────────────────┤
119getdate()   │ Thread safety │ MT-Unsafe race:getdate env locale       │
120       ├────────────┼───────────────┼─────────────────────────────────────────┤
121getdate_r() │ Thread safety │ MT-Safe env locale                      │
122       └────────────┴───────────────┴─────────────────────────────────────────┘
123

CONFORMING TO

125       POSIX.1-2001, POSIX.1-2008.
126

NOTES

128       The  POSIX.1 specification for strptime(3) contains conversion specifi‐
129       cations using the %E or %O modifier, while such specifications are  not
130       given  for  getdate().   In glibc, getdate() is implemented using strp‐
131       time(3), so that precisely the same conversions are supported by both.
132

EXAMPLES

134       The program below calls getdate() for each of  its  command-line  argu‐
135       ments,  and  for each call displays the values in the fields of the re‐
136       turned tm structure.  The following shell session demonstrates the  op‐
137       eration of the program:
138
139           $ TFILE=$PWD/tfile
140           $ echo '%A' > $TFILE       # Full name of the day of the week
141           $ echo '%T' >> $TFILE      # ISO date (YYYY-MM-DD)
142           $ echo '%F' >> $TFILE      # Time (HH:MM:SS)
143           $ date
144           $ export DATEMSK=$TFILE
145           $ ./a.out Tuesday '2009-12-28' '12:22:33'
146           Sun Sep  7 06:03:36 CEST 2008
147           Call 1 ("Tuesday") succeeded:
148               tm_sec   = 36
149               tm_min   = 3
150               tm_hour  = 6
151               tm_mday  = 9
152               tm_mon   = 8
153               tm_year  = 108
154               tm_wday  = 2
155               tm_yday  = 252
156               tm_isdst = 1
157           Call 2 ("2009-12-28") succeeded:
158               tm_sec   = 36
159               tm_min   = 3
160               tm_hour  = 6
161               tm_mday  = 28
162               tm_mon   = 11
163               tm_year  = 109
164               tm_wday  = 1
165               tm_yday  = 361
166               tm_isdst = 0
167           Call 3 ("12:22:33") succeeded:
168               tm_sec   = 33
169               tm_min   = 22
170               tm_hour  = 12
171               tm_mday  = 7
172               tm_mon   = 8
173               tm_year  = 108
174               tm_wday  = 0
175               tm_yday  = 250
176               tm_isdst = 1
177
178   Program source
179
180       #define _GNU_SOURCE
181       #include <time.h>
182       #include <stdio.h>
183       #include <stdlib.h>
184
185       int
186       main(int argc, char *argv[])
187       {
188           struct tm *tmp;
189
190           for (int j = 1; j < argc; j++) {
191               tmp = getdate(argv[j]);
192
193               if (tmp == NULL) {
194                   printf("Call %d failed; getdate_err = %d\n",
195                          j, getdate_err);
196                   continue;
197               }
198
199               printf("Call %d (\"%s\") succeeded:\n", j, argv[j]);
200               printf("    tm_sec   = %d\n", tmp->tm_sec);
201               printf("    tm_min   = %d\n", tmp->tm_min);
202               printf("    tm_hour  = %d\n", tmp->tm_hour);
203               printf("    tm_mday  = %d\n", tmp->tm_mday);
204               printf("    tm_mon   = %d\n", tmp->tm_mon);
205               printf("    tm_year  = %d\n", tmp->tm_year);
206               printf("    tm_wday  = %d\n", tmp->tm_wday);
207               printf("    tm_yday  = %d\n", tmp->tm_yday);
208               printf("    tm_isdst = %d\n", tmp->tm_isdst);
209           }
210
211           exit(EXIT_SUCCESS);
212       }
213

SEE ALSO

215       time(2), localtime(3), setlocale(3), strftime(3), strptime(3)
216

COLOPHON

218       This  page  is  part of release 5.12 of the Linux man-pages project.  A
219       description of the project, information about reporting bugs,  and  the
220       latest     version     of     this    page,    can    be    found    at
221       https://www.kernel.org/doc/man-pages/.
222
223
224
225                                  2021-03-22                        GETDATE(3)
Impressum