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