man3/getdate.3

   1 .\" Copyright 2001 walter harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" Modified, 2001-12-26, aeb
  28 .\" 2008-09-07, mtk, Various rewrites; added an example program.
  29 .\"
  30 .TH GETDATE 3 2017-09-15 "" "Linux Programmer's Manual"
  31 .SH NAME
  32 getdate, getdate_r \- convert a date-plus-time string to broken-down time
  33 .SH SYNOPSIS
  34 .B "#include <time.h>"
  35 .PP
  36 .BI "struct tm *getdate(const char *" string );
  37 .PP
  38 .B "extern int getdate_err;"
  39 .PP
  40 .B "#include <time.h>"
  41 .PP
  42 .BI "int getdate_r(const char *" string ", struct tm *" res );
  43 .PP
  44 .in -4n
  45 Feature Test Macro Requirements for glibc (see
  46 .BR feature_test_macros (7)):
  47 .in
  48 .PP
  49 .BR getdate ():
  50 .ad l
  51 .RS 4
  52 _XOPEN_SOURCE\ >=\ 500
  53 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  54 .RE
  55 .br
  56 .BR getdate_r ():
  57 .ad l
  58 .RS 4
  59 _GNU_SOURCE
  60 .RE
  61 .ad
  62 .SH DESCRIPTION
  63 The function
  64 .BR getdate ()
  65 converts a string representation of a date and time,
  66 contained in the buffer pointed to by
  67 .IR string ,
  68 into a broken-down time.
  69 The broken-down time is stored in a
  70 .I tm
  71 structure, and a pointer to this
  72 structure is returned as the function result.
  73 This
  74 .I tm
  75 structure is allocated in static storage,
  76 and consequently it will be overwritten by further calls to
  77 .BR getdate ().
  78 .PP
  79 In contrast to
  80 .BR strptime (3),
  81 (which has a
  82 .I format
  83 argument),
  84 .BR getdate ()
  85 uses the formats found in the file
  86 whose full pathname is given in the environment variable
  87 .BR DATEMSK .
  88 The first line in the file that matches the given input string
  89 is used for the conversion.
  90 .PP
  91 The matching is done case insensitively.
  92 Superfluous whitespace, either in the pattern or in the string to
  93 be converted, is ignored.
  94 .PP
  95 The conversion specifications that a pattern can contain are those given for
  96 .BR strptime (3).
  97 One more conversion specification is specified in POSIX.1-2001:
  98 .TP
  99 .B %Z
 100 Timezone name.
 101 .\" FIXME Is it (still) true that %Z is not supported in glibc?
 102 .\" Looking at the glibc 2.21 source code, where the implementation uses
 103 .\" strptime(), suggests that it might be supported.
 104 This is not implemented in glibc.
 105 .PP
 106 When
 107 .B %Z
 108 is given, the structure containing the broken-down time
 109 is initialized with values corresponding to the current
 110 time in the given timezone.
 111 Otherwise, the structure is initialized to the broken-down time
 112 corresponding to the current local time (as by a call to
 113 .BR localtime (3)).
 114 .PP
 115 When only the day of the week is given,
 116 the day is taken to be the first such day
 117 on or after today.
 118 .PP
 119 When only the month is given (and no year), the month is taken to
 120 be the first such month equal to or after the current month.
 121 If no day is given, it is the first day of the month.
 122 .PP
 123 When no hour, minute and second are given, the current
 124 hour, minute and second are taken.
 125 .PP
 126 If no date is given, but we know the hour, then that hour is taken
 127 to be the first such hour equal to or after the current hour.
 128 .PP
 129 .BR getdate_r ()
 130 is a GNU extension that provides a reentrant version of
 131 .BR getdate ().
 132 Rather than using a global variable to report errors and a static buffer
 133 to return the broken down time,
 134 it returns errors via the function result value,
 135 and returns the resulting broken-down time in the
 136 caller-allocated buffer pointed to by the argument
 137 .IR res .
 138 .SH RETURN VALUE
 139 When successful,
 140 .BR getdate ()
 141 returns a pointer to a
 142 .IR "struct tm" .
 143 Otherwise, it returns NULL and sets the global variable
 144 .IR getdate_err
 145 to one of the error numbers shown below.
 146 Changes to
 147 .I errno
 148 are unspecified.
 149 .PP
 150 On success
 151 .BR getdate_r ()
 152 returns 0;
 153 on error it returns one of the error numbers shown below.
 154 .SH ERRORS
 155 The following errors are returned via
 156 .IR getdate_err
 157 (for
 158 .BR getdate ())
 159 or as the function result (for
 160 .BR getdate_r ()):
 161 .TP 4n
 162 .B 1
 163 The
 164 .B DATEMSK
 165 environment variable is not defined, or its value is an empty string.
 166 .TP
 167 .B 2
 168 The template file specified by
 169 .B DATEMSK
 170 cannot be opened for reading.
 171 .TP
 172 .B 3
 173 Failed to get file status information.
 174 .\" stat()
 175 .TP
 176 .B 4
 177 The template file is not a regular file.
 178 .TP
 179 .B 5
 180 An error was encountered while reading the template file.
 181 .TP
 182 .B 6
 183 Memory allocation failed (not enough memory available).
 184 .\" Error 6 doesn't seem to occur in glibc
 185 .TP
 186 .B 7
 187 There is no line in the file that matches the input.
 188 .TP
 189 .B 8
 190 Invalid input specification.
 191 .SH ENVIRONMENT
 192 .TP
 193 .B DATEMSK
 194 File containing format patterns.
 195 .TP
 196 .BR TZ ", " LC_TIME
 197 Variables used by
 198 .BR strptime (3).
 199 .SH ATTRIBUTES
 200 For an explanation of the terms used in this section, see
 201 .BR attributes (7).
 202 .TS
 203 allbox;
 204 lb lb lb
 205 l l l.
 206 Interface       Attribute       Value
 207 T{
 208 .BR getdate ()
 209 T}      Thread safety   MT-Unsafe race:getdate env locale
 210 T{
 211 .BR getdate_r ()
 212 T}      Thread safety   MT-Safe env locale
 213 .TE
 214 .SH CONFORMING TO
 215 POSIX.1-2001, POSIX.1-2008.
 216 .SH NOTES
 217 The POSIX.1 specification for
 218 .BR strptime (3)
 219 contains conversion specifications using the
 220 .B %E
 221 or
 222 .B %O
 223 modifier, while such specifications are not given for
 224 .BR getdate ().
 225 In glibc,
 226 .BR getdate ()
 227 is implemented using
 228 .BR strptime (3),
 229 so that precisely the same conversions are supported by both.
 230 .SH EXAMPLE
 231 The program below calls
 232 .BR getdate ()
 233 for each of its command-line arguments,
 234 and for each call displays the values in the fields of the returned
 235 .I tm
 236 structure.
 237 The following shell session demonstrates the operation of the program:
 238 .PP
 239 .in +4n
 240 .EX
 241 .RB "$" " TFILE=$PWD/tfile"
 242 .RB "$" " echo \(aq%A\(aq > $TFILE " "      # Full name of the day of the week"
 243 .RB "$" " echo \(aq%T\(aq >> $TFILE" "      # ISO date (YYYY-MM-DD)"
 244 .RB "$" " echo \(aq%F\(aq >> $TFILE" "      # Time (HH:MM:SS)"
 245 .RB "$" " date"
 246 .RB "$" " export DATEMSK=$TFILE"
 247 .RB "$" " ./a.out Tuesday \(aq2009-12-28\(aq \(aq12:22:33\(aq"
 248 Sun Sep  7 06:03:36 CEST 2008
 249 Call 1 ("Tuesday") succeeded:
 250     tm_sec   = 36
 251     tm_min   = 3
 252     tm_hour  = 6
 253     tm_mday  = 9
 254     tm_mon   = 8
 255     tm_year  = 108
 256     tm_wday  = 2
 257     tm_yday  = 252
 258     tm_isdst = 1
 259 Call 2 ("2009-12-28") succeeded:
 260     tm_sec   = 36
 261     tm_min   = 3
 262     tm_hour  = 6
 263     tm_mday  = 28
 264     tm_mon   = 11
 265     tm_year  = 109
 266     tm_wday  = 1
 267     tm_yday  = 361
 268     tm_isdst = 0
 269 Call 3 ("12:22:33") succeeded:
 270     tm_sec   = 33
 271     tm_min   = 22
 272     tm_hour  = 12
 273     tm_mday  = 7
 274     tm_mon   = 8
 275     tm_year  = 108
 276     tm_wday  = 0
 277     tm_yday  = 250
 278     tm_isdst = 1
 279 .EE
 280 .in
 281 .SS Program source
 282 \&
 283 .EX
 284 #define _GNU_SOURCE
 285 #include <time.h>
 286 #include <stdio.h>
 287 #include <stdlib.h>
 288
 289 int
 290 main(int argc, char *argv[])
 291 {
 292     struct tm *tmp;
 293     int j;
 294
 295     for (j = 1; j < argc; j++) {
 296         tmp = getdate(argv[j]);
 297
 298         if (tmp == NULL) {
 299             printf("Call %d failed; getdate_err = %d\en",
 300                    j, getdate_err);
 301             continue;
 302         }
 303
 304         printf("Call %d (\e"%s\e") succeeded:\en", j, argv[j]);
 305         printf("    tm_sec   = %d\en", tmp\->tm_sec);
 306         printf("    tm_min   = %d\en", tmp\->tm_min);
 307         printf("    tm_hour  = %d\en", tmp\->tm_hour);
 308         printf("    tm_mday  = %d\en", tmp\->tm_mday);
 309         printf("    tm_mon   = %d\en", tmp\->tm_mon);
 310         printf("    tm_year  = %d\en", tmp\->tm_year);
 311         printf("    tm_wday  = %d\en", tmp\->tm_wday);
 312         printf("    tm_yday  = %d\en", tmp\->tm_yday);
 313         printf("    tm_isdst = %d\en", tmp\->tm_isdst);
 314     }
 315
 316     exit(EXIT_SUCCESS);
 317 }
 318 .EE
 319 .SH SEE ALSO
 320 .BR time (2),
 321 .BR localtime (3),
 322 .BR setlocale (3),
 323 .BR strftime (3),
 324 .BR strptime (3)