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       #define _XOPEN_SOURCE 500
11       #include <time.h>
12
13       struct tm *getdate(const char *string);
14
15       extern int getdate_err;
16
17       #define _GNU_SOURCE
18       #include <time.h>
19
20       int getdate_r(const char *string, struct tm *res);
21

DESCRIPTION

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

RETURN VALUE

70       When successful, getdate() returns a pointer to a  struct  tm.   Other‐
71       wise,  it  returns NULL and sets the global variable getdate_err to one
72       of the error numbers shown below.  Changes to errno are unspecified.
73
74       On success getdate_r() returns 0; on error it returns one of the  error
75       numbers shown below.
76

ERRORS

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

ENVIRONMENT

100       DATEMSK
101              File containing format patterns.
102
103       TZ, LC_TIME
104              Variables used by strptime(3).
105

CONFORMING TO

107       POSIX.1-2001.
108

NOTES

110       The POSIX.1-2001  specification  for  strptime(3)  contains  conversion
111       specifications  using  the %E or %O modifier, while such specifications
112       are not given for getdate().  In glibc, getdate() is implemented  using
113       strptime(3),  so  that  precisely the same conversions are supported by
114       both.
115

EXAMPLE

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

SEE ALSO

199       time(2),  localtime(3),  setlocale(3),  strftime(3),  strptime(3), fea‐
200       ture_test_macros(7)
201

COLOPHON

203       This page is part of release 3.22 of the Linux  man-pages  project.   A
204       description  of  the project, and information about reporting bugs, can
205       be found at http://www.kernel.org/doc/man-pages/.
206
207
208
209                                  2008-09-07                        GETDATE(3)
Impressum