man3/getdate.3

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