original/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 2014-06-13 "" "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 .sp
  36 .BI "struct tm *getdate(const char *" string );
  37 .sp
  38 .B "extern int getdate_err;"
  39 .sp
  40 .B "#include <time.h>"
  41 .sp
  42 .BI "int getdate_r(const char *" string ", struct tm *" res );
  43 .sp
  44 .in -4n
  45 Feature Test Macro Requirements for glibc (see
  46 .BR feature_test_macros (7)):
  47 .in
  48 .sp
  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
  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
  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
  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 This is not implemented in glibc.
 102 .LP
 103 When
 104 .B %Z
 105 is given, the structure containing the broken-down time
 106 is initialized with values corresponding to the current
 107 time in the given timezone.
 108 Otherwise, the structure is initialized to the broken-down time
 109 corresponding to the current local time (as by a call to
 110 .BR localtime (3)).
 111 .LP
 112 When only the day of the week is given,
 113 the day is taken to be the first such day
 114 on or after today.
 115 .LP
 116 When only the month is given (and no year), the month is taken to
 117 be the first such month equal to or after the current month.
 118 If no day is given, it is the first day of the month.
 119 .LP
 120 When no hour, minute and second are given, the current
 121 hour, minute and second are taken.
 122 .LP
 123 If no date is given, but we know the hour, then that hour is taken
 124 to be the first such hour equal to or after the current hour.
 125
 126 .BR getdate_r ()
 127 is a GNU extension that provides a reentrant version of
 128 .BR getdate ().
 129 Rather than using a global variable to report errors and a static buffer
 130 to return the broken down time,
 131 it returns errors via the function result value,
 132 and returns the resulting broken-down time in the
 133 caller-allocated buffer pointed to by the argument
 134 .IR res .
 135 .SH RETURN VALUE
 136 When successful,
 137 .BR getdate ()
 138 returns a pointer to a
 139 .IR "struct tm" .
 140 Otherwise, it returns NULL and sets the global variable
 141 .IR getdate_err
 142 to one of the error numbers shown below.
 143 Changes to
 144 .I errno
 145 are unspecified.
 146
 147 On success
 148 .BR getdate_r ()
 149 returns 0;
 150 on error it returns one of the error numbers shown below.
 151 .SH ERRORS
 152 The following errors are returned via
 153 .IR getdate_err
 154 (for
 155 .BR getdate ())
 156 or as the function result (for
 157 .BR getdate_r ()):
 158 .TP 4n
 159 .B 1
 160 The
 161 .B DATEMSK
 162 environment variable is not defined, or its value is an empty string.
 163 .TP
 164 .B 2
 165 The template file specified by
 166 .B DATEMSK
 167 cannot be opened for reading.
 168 .TP
 169 .B 3
 170 Failed to get file status information.
 171 .\" stat()
 172 .TP
 173 .B 4
 174 The template file is not a regular file.
 175 .TP
 176 .B 5
 177 An error was encountered while reading the template file.
 178 .TP
 179 .B 6
 180 Memory allocation failed (not enough memory available).
 181 .\" Error 6 doesn't seem to occur in glibc
 182 .TP
 183 .B 7
 184 There is no line in the file that matches the input.
 185 .TP
 186 .B 8
 187 Invalid input specification.
 188 .SH ENVIRONMENT
 189 .TP
 190 .B DATEMSK
 191 File containing format patterns.
 192 .TP
 193 .BR TZ ", " LC_TIME
 194 Variables used by
 195 .BR strptime (3).
 196 .SH ATTRIBUTES
 197 .SS Multithreading (see pthreads(7))
 198 The
 199 .BR getdate ()
 200 function is not thread-safe.
 201 .LP
 202 The
 203 .BR getdate_r ()
 204 function is thread-safe.
 205 .SH CONFORMING TO
 206 POSIX.1-2001.
 207 .SH NOTES
 208 The POSIX.1-2001 specification for
 209 .BR strptime (3)
 210 contains conversion specifications using the
 211 .B %E
 212 or
 213 .B %O
 214 modifier, while such specifications are not given for
 215 .BR getdate ().
 216 In glibc,
 217 .BR getdate ()
 218 is implemented using
 219 .BR strptime (3),
 220 so that precisely the same conversions are supported by both.
 221 .SH EXAMPLE
 222 The program below calls
 223 .BR getdate ()
 224 for each of its command-line arguments,
 225 and for each call displays the values in the fields of the returned
 226 .I tm
 227 structure.
 228 The following shell session demonstrates the operation of the program:
 229
 230 .in +4n
 231 .nf
 232 .RB "$" " TFILE=$PWD/tfile"
 233 .RB "$" " echo \(aq%A\(aq > $TFILE " "      # Full name of the day of the week"
 234 .RB "$" " echo \(aq%T\(aq >> $TFILE" "      # ISO date (YYYY-MM-DD)"
 235 .RB "$" " echo \(aq%F\(aq >> $TFILE" "      # Time (HH:MM:SS)"
 236 .RB "$" " date"
 237 .RB "$" " export DATEMSK=$TFILE"
 238 .RB "$" " ./a.out Tuesday \(aq2009-12-28\(aq \(aq12:22:33\(aq"
 239 Sun Sep  7 06:03:36 CEST 2008
 240 Call 1 ("Tuesday") succeeded:
 241     tm_sec   = 36
 242     tm_min   = 3
 243     tm_hour  = 6
 244     tm_mday  = 9
 245     tm_mon   = 8
 246     tm_year  = 108
 247     tm_wday  = 2
 248     tm_yday  = 252
 249     tm_isdst = 1
 250 Call 2 ("2009-12-28") succeeded:
 251     tm_sec   = 36
 252     tm_min   = 3
 253     tm_hour  = 6
 254     tm_mday  = 28
 255     tm_mon   = 11
 256     tm_year  = 109
 257     tm_wday  = 1
 258     tm_yday  = 361
 259     tm_isdst = 0
 260 Call 3 ("12:22:33") succeeded:
 261     tm_sec   = 33
 262     tm_min   = 22
 263     tm_hour  = 12
 264     tm_mday  = 7
 265     tm_mon   = 8
 266     tm_year  = 108
 267     tm_wday  = 0
 268     tm_yday  = 250
 269     tm_isdst = 1
 270 .fi
 271 .in
 272 .SS Program source
 273 \&
 274 .nf
 275 #define _GNU_SOURCE
 276 #include <time.h>
 277 #include <stdio.h>
 278 #include <stdlib.h>
 279
 280 int
 281 main(int argc, char *argv[])
 282 {
 283     struct tm *tmp;
 284     int j;
 285
 286     for (j = 1; j < argc; j++) {
 287         tmp = getdate(argv[j]);
 288
 289         if (tmp == NULL) {
 290             printf("Call %d failed; getdate_err = %d\\n",
 291                    j, getdate_err);
 292             continue;
 293         }
 294
 295         printf("Call %d (\\"%s\\") succeeded:\\n", j, argv[j]);
 296         printf("    tm_sec   = %d\\n", tmp\->tm_sec);
 297         printf("    tm_min   = %d\\n", tmp\->tm_min);
 298         printf("    tm_hour  = %d\\n", tmp\->tm_hour);
 299         printf("    tm_mday  = %d\\n", tmp\->tm_mday);
 300         printf("    tm_mon   = %d\\n", tmp\->tm_mon);
 301         printf("    tm_year  = %d\\n", tmp\->tm_year);
 302         printf("    tm_wday  = %d\\n", tmp\->tm_wday);
 303         printf("    tm_yday  = %d\\n", tmp\->tm_yday);
 304         printf("    tm_isdst = %d\\n", tmp\->tm_isdst);
 305     }
 306
 307     exit(EXIT_SUCCESS);
 308 }
 309 .fi
 310 .SH SEE ALSO
 311 .BR time (2),
 312 .BR localtime (3),
 313 .BR setlocale (3),
 314 .BR strftime (3),
 315 .BR strptime (3)