man3/strptime.3

   1 '\" t
   2 .\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified, jmv@lucifer.dorms.spbu.ru, 1999-11-08
   7 .\" Modified, aeb, 2000-04-07
   8 .\" Updated from glibc docs, C. Scott Ananian, 2001-08-25
   9 .\" Modified, aeb, 2001-08-31
  10 .\" Modified, wharms 2001-11-12, remark on white space and example
  11 .\"
  12 .TH strptime 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 strptime \- convert a string representation of time to a time tm structure
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .BR "#define _XOPEN_SOURCE" "       /* See feature_test_macros(7) */"
  21 .B #include <time.h>
  22 .PP
  23 .BI "char *strptime(const char *restrict " s ", const char *restrict " format ,
  24 .BI "               struct tm *restrict " tm );
  25 .fi
  26 .SH DESCRIPTION
  27 The
  28 .BR strptime ()
  29 function is the converse of
  30 .BR strftime (3);
  31 it converts the character string pointed to by
  32 .I s
  33 to values which are stored in the
  34 "broken-down time"
  35 structure pointed to by
  36 .IR tm ,
  37 using the format specified by
  38 .IR format .
  39 .PP
  40 The broken-down time structure
  41 .I tm
  42 is described in
  43 .BR tm (3type).
  44 .PP
  45 The
  46 .I format
  47 argument
  48 is a character string that consists of field descriptors and text characters,
  49 reminiscent of
  50 .BR scanf (3).
  51 Each field descriptor consists of a
  52 .B %
  53 character followed by another character that specifies the replacement
  54 for the field descriptor.
  55 All other characters in the
  56 .I format
  57 string must have a matching character in the input string,
  58 except for whitespace, which matches zero or more
  59 whitespace characters in the input string.
  60 There should be white\%space or other alphanumeric characters
  61 between any two field descriptors.
  62 .PP
  63 The
  64 .BR strptime ()
  65 function processes the input string from left
  66 to right.
  67 Each of the three possible input elements (whitespace,
  68 literal, or format) are handled one after the other.
  69 If the input cannot be matched to the format string, the function stops.
  70 The remainder of the format and input strings are not processed.
  71 .PP
  72 The supported input field descriptors are listed below.
  73 In case a text string (such as the name of a day of the week or a month name)
  74 is to be matched, the comparison is case insensitive.
  75 In case a number is to be matched, leading zeros are
  76 permitted but not required.
  77 .TP
  78 .B %%
  79 The
  80 .B %
  81 character.
  82 .TP
  83 .BR %a " or " %A
  84 The name of the day of the week according to the current locale,
  85 in abbreviated form or the full name.
  86 .TP
  87 .BR %b " or " %B " or " %h
  88 The month name according to the current locale,
  89 in abbreviated form or the full name.
  90 .TP
  91 .B %c
  92 The date and time representation for the current locale.
  93 .TP
  94 .B %C
  95 The century number (0\[en]99).
  96 .TP
  97 .BR %d " or " %e
  98 The day of month (1\[en]31).
  99 .TP
 100 .B %D
 101 Equivalent to
 102 .BR %m/%d/%y .
 103 (This is the American style date, very confusing
 104 to non-Americans, especially since
 105 .B %d/%m/%y
 106 is widely used in Europe.
 107 The ISO 8601 standard format is
 108 .BR %Y\-%m\-%d .)
 109 .TP
 110 .B %H
 111 The hour (0\[en]23).
 112 .TP
 113 .B %I
 114 The hour on a 12-hour clock (1\[en]12).
 115 .TP
 116 .B %j
 117 The day number in the year (1\[en]366).
 118 .TP
 119 .B %m
 120 The month number (1\[en]12).
 121 .TP
 122 .B %M
 123 The minute (0\[en]59).
 124 .TP
 125 .B %n
 126 Arbitrary whitespace.
 127 .TP
 128 .B %p
 129 The locale's equivalent of AM or PM.
 130 (Note: there may be none.)
 131 .TP
 132 .B %r
 133 The 12-hour clock time (using the locale's AM or PM).
 134 In the POSIX locale equivalent to
 135 .BR "%I:%M:%S %p" .
 136 If
 137 .I t_fmt_ampm
 138 is empty in the
 139 .B LC_TIME
 140 part of the current locale,
 141 then the behavior is undefined.
 142 .TP
 143 .B %R
 144 Equivalent to
 145 .BR %H:%M .
 146 .TP
 147 .B %S
 148 The second (0\[en]60; 60 may occur for leap seconds;
 149 earlier also 61 was allowed).
 150 .TP
 151 .B %t
 152 Arbitrary whitespace.
 153 .TP
 154 .B %T
 155 Equivalent to
 156 .BR %H:%M:%S .
 157 .TP
 158 .B %U
 159 The week number with Sunday the first day of the week (0\[en]53).
 160 The first Sunday of January is the first day of week 1.
 161 .TP
 162 .B %w
 163 The ordinal number of the day of the week (0\[en]6), with Sunday = 0.
 164 .TP
 165 .B %W
 166 The week number with Monday the first day of the week (0\[en]53).
 167 The first Monday of January is the first day of week 1.
 168 .TP
 169 .B %x
 170 The date, using the locale's date format.
 171 .TP
 172 .B %X
 173 The time, using the locale's time format.
 174 .TP
 175 .B %y
 176 The year within century (0\[en]99).
 177 When a century is not otherwise specified, values in the range 69\[en]99 refer
 178 to years in the twentieth century (1969\[en]1999); values in the
 179 range 00\[en]68 refer to years in the twenty-first century (2000\[en]2068).
 180 .TP
 181 .B %Y
 182 The year, including century (for example, 1991).
 183 .PP
 184 Some field descriptors can be modified by the E or O modifier characters
 185 to indicate that an alternative format or specification should be used.
 186 If the
 187 alternative format or specification does not exist in the current locale, the
 188 unmodified field descriptor is used.
 189 .PP
 190 The E modifier specifies that the input string may contain
 191 alternative locale-dependent versions of the date and time representation:
 192 .TP
 193 .B %Ec
 194 The locale's alternative date and time representation.
 195 .TP
 196 .B %EC
 197 The name of the base year (period) in the locale's alternative representation.
 198 .TP
 199 .B %Ex
 200 The locale's alternative date representation.
 201 .TP
 202 .B %EX
 203 The locale's alternative time representation.
 204 .TP
 205 .B %Ey
 206 The offset from
 207 .B %EC
 208 (year only) in the locale's alternative representation.
 209 .TP
 210 .B %EY
 211 The full alternative year representation.
 212 .PP
 213 The O modifier specifies that the numerical input may be in an
 214 alternative locale-dependent format:
 215 .TP
 216 .BR %Od " or " %Oe
 217 The day of the month using the locale's alternative numeric symbols;
 218 leading zeros are permitted but not required.
 219 .TP
 220 .B %OH
 221 The hour (24-hour clock) using the locale's alternative numeric symbols.
 222 .TP
 223 .B %OI
 224 The hour (12-hour clock) using the locale's alternative numeric symbols.
 225 .TP
 226 .B %Om
 227 The month using the locale's alternative numeric symbols.
 228 .TP
 229 .B %OM
 230 The minutes using the locale's alternative numeric symbols.
 231 .TP
 232 .B %OS
 233 The seconds using the locale's alternative numeric symbols.
 234 .TP
 235 .B %OU
 236 The week number of the year (Sunday as the first day of the week)
 237 using the locale's alternative numeric symbols.
 238 .TP
 239 .B %Ow
 240 The ordinal number of the day of the week (Sunday=0),
 241 using the locale's alternative numeric symbols.
 242 .TP
 243 .B %OW
 244 The week number of the year (Monday as the first day of the week)
 245 using the locale's alternative numeric symbols.
 246 .TP
 247 .B %Oy
 248 The year (offset from
 249 .BR %C )
 250 using the locale's alternative numeric symbols.
 251 .SH RETURN VALUE
 252 The return value of the function is a pointer to the first character
 253 not processed in this function call.
 254 In case the input string
 255 contains more characters than required by the format string, the return
 256 value points right after the last consumed input character.
 257 In case the whole input string is consumed,
 258 the return value points to the null byte at the end of the string.
 259 If
 260 .BR strptime ()
 261 fails to match all
 262 of the format string and therefore an error occurred, the function
 263 returns NULL.
 264 .SH ATTRIBUTES
 265 For an explanation of the terms used in this section, see
 266 .BR attributes (7).
 267 .ad l
 268 .nh
 269 .TS
 270 allbox;
 271 lbx lb lb
 272 l l l.
 273 Interface       Attribute       Value
 274 T{
 275 .BR strptime ()
 276 T}      Thread safety   MT-Safe env locale
 277 .TE
 278 .hy
 279 .ad
 280 .sp 1
 281 .SH STANDARDS
 282 POSIX.1-2008.
 283 .SH HISTORY
 284 POSIX.1-2001, SUSv2.
 285 .SH NOTES
 286 In principle, this function does not initialize
 287 .I tm
 288 but
 289 stores only the values specified.
 290 This means that
 291 .I tm
 292 should be initialized before the call.
 293 Details differ a bit between different UNIX systems.
 294 The glibc implementation does not touch those fields which are not
 295 explicitly specified, except that it recomputes the
 296 .I tm_wday
 297 and
 298 .I tm_yday
 299 field if any of the year, month, or day elements changed.
 300 .\" .PP
 301 .\" This function is available since libc 4.6.8.
 302 .\" Linux libc4 and libc5 includes define the prototype unconditionally;
 303 .\" glibc2 includes provide a prototype only when
 304 .\" .B _XOPEN_SOURCE
 305 .\" or
 306 .\" .B _GNU_SOURCE
 307 .\" are defined.
 308 .\" .PP
 309 .\" Before libc 5.4.13 whitespace
 310 .\" (and the \[aq]n\[aq] and \[aq]t\[aq] specifications) was not handled,
 311 .\" no \[aq]E\[aq] and \[aq]O\[aq] locale modifier characters were accepted,
 312 .\" and the \[aq]C\[aq] specification was a synonym for the \[aq]c\[aq] specification.
 313 .PP
 314 The \[aq]y\[aq] (year in century) specification is taken to specify a year
 315 .\" in the 20th century by libc4 and libc5.
 316 .\" It is taken to be a year
 317 in the range 1950\[en]2049 by glibc 2.0.
 318 It is taken to be a year in
 319 1969\[en]2068 since glibc 2.1.
 320 .\" In libc4 and libc5 the code for %I is broken (fixed in glibc;
 321 .\" %OI was fixed in glibc 2.2.4).
 322 .SS glibc notes
 323 For reasons of symmetry, glibc tries to support for
 324 .BR strptime ()
 325 the same format characters as for
 326 .BR strftime (3).
 327 (In most cases, the corresponding fields are parsed, but no field in
 328 .I tm
 329 is changed.)
 330 This leads to
 331 .TP
 332 .B %F
 333 Equivalent to
 334 .BR %Y\-%m\-%d ,
 335 the ISO 8601 date format.
 336 .TP
 337 .B %g
 338 The year corresponding to the ISO week number, but without the century
 339 (0\[en]99).
 340 .TP
 341 .B %G
 342 The year corresponding to the ISO week number.
 343 (For example, 1991.)
 344 .TP
 345 .B %u
 346 The day of the week as a decimal number (1\[en]7, where Monday = 1).
 347 .TP
 348 .B %V
 349 The ISO 8601:1988 week number as a decimal number (1\[en]53).
 350 If the week (starting on Monday) containing 1 January has four or more days
 351 in the new year, then it is considered week 1.
 352 Otherwise, it is the last week
 353 of the previous year, and the next week is week 1.
 354 .TP
 355 .B %z
 356 An RFC-822/ISO 8601 standard timezone specification.
 357 .TP
 358 .B %Z
 359 The timezone name.
 360 .PP
 361 Similarly, because of GNU extensions to
 362 .BR strftime (3),
 363 .B %k
 364 is accepted as a synonym for
 365 .BR %H ,
 366 and
 367 .B %l
 368 should be accepted
 369 as a synonym for
 370 .BR %I ,
 371 and
 372 .B %P
 373 is accepted as a synonym for
 374 .BR %p .
 375 Finally
 376 .TP
 377 .B %s
 378 The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
 379 Leap seconds are not counted unless leap second support is available.
 380 .PP
 381 The glibc implementation does not require whitespace between
 382 two field descriptors.
 383 .SH EXAMPLES
 384 The following example demonstrates the use of
 385 .BR strptime ()
 386 and
 387 .BR strftime (3).
 388 .PP
 389 .\" SRC BEGIN (strptime.c)
 390 .EX
 391 #define _XOPEN_SOURCE
 392 #include <stdio.h>
 393 #include <stdlib.h>
 394 #include <string.h>
 395 #include <time.h>
 396 \&
 397 int
 398 main(void)
 399 {
 400     struct tm tm;
 401     char buf[255];
 402 \&
 403     memset(&tm, 0, sizeof(tm));
 404     strptime("2001\-11\-12 18:31:01", "%Y\-%m\-%d %H:%M:%S", &tm);
 405     strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm);
 406     puts(buf);
 407     exit(EXIT_SUCCESS);
 408 }
 409 .EE
 410 .\" SRC END
 411 .SH SEE ALSO
 412 .BR time (2),
 413 .BR getdate (3),
 414 .BR scanf (3),
 415 .BR setlocale (3),
 416 .BR strftime (3)