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