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