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