lib/libc/stdtime/strptime.3

   1 .\"
   2 .\" Copyright (c) 1997 Joerg Wunsch
   3 .\"
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\" "
  26 .Dd October 2, 2014
  27 .Dt STRPTIME 3
  28 .Os
  29 .Sh NAME
  30 .Nm strptime
  31 .Nd parse date and time string
  32 .Sh LIBRARY
  33 .Lb libc
  34 .Sh SYNOPSIS
  35 .In time.h
  36 .Ft char *
  37 .Fo strptime
  38 .Fa "const char * restrict buf"
  39 .Fa "const char * restrict format"
  40 .Fa "struct tm * restrict timeptr"
  41 .Fc
  42 .In time.h
  43 .In xlocale.h
  44 .Ft char *
  45 .Fn strptime_l "const char * restrict buf" "const char * restrict format" "struct tm * restrict timeptr" "locale_t loc"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn strptime
  49 function parses the string in the buffer
  50 .Fa buf
  51 according to the string pointed to by
  52 .Fa format ,
  53 and fills in the elements of the structure pointed to by
  54 .Fa timeptr .
  55 The resulting values will be relative to the local time zone.
  56 Thus, it can be considered the reverse operation of
  57 .Xr strftime 3 .
  58 The
  59 .Fn strptime_l
  60 function does the same as
  61 .Fn strptime ,
  62 but takes an explicit locale rather than using the current locale.
  63 .Pp
  64 The
  65 .Fa format
  66 string consists of zero or more conversion specifications and
  67 ordinary characters.
  68 All ordinary characters are matched exactly with the buffer, where
  69 white space in the format string will match any amount of white space
  70 in the buffer.
  71 All conversion specifications are identical to those described in
  72 .Xr strftime 3 .
  73 .Pp
  74 Two-digit year values, including formats
  75 .Fa %y
  76 and
  77 .Fa \&%D ,
  78 are now interpreted as beginning at 1969 per POSIX requirements.
  79 Years 69-00 are interpreted in the 20th century (1969-2000), years
  80 01-68 in the 21st century (2001-2068).
  81 The
  82 .Fa \&%U
  83 and
  84 .Fa %W
  85 format specifiers accept any value within the range 00 to 53.
  86 .Pp
  87 If the
  88 .Fa format
  89 string does not contain enough conversion specifications to completely
  90 specify the resulting
  91 .Vt struct tm ,
  92 the unspecified members of
  93 .Va timeptr
  94 are left untouched.
  95 For example, if
  96 .Fa format
  97 is
  98 .Dq Li "%H:%M:%S" ,
  99 only
 100 .Va tm_hour ,
 101 .Va tm_sec
 102 and
 103 .Va tm_min
 104 will be modified.
 105 If time relative to today is desired, initialize the
 106 .Fa timeptr
 107 structure with today's date before passing it to
 108 .Fn strptime .
 109 .Sh RETURN VALUES
 110 Upon successful completion,
 111 .Fn strptime
 112 returns the pointer to the first character in
 113 .Fa buf
 114 that has not been required to satisfy the specified conversions in
 115 .Fa format .
 116 It returns
 117 .Dv NULL
 118 if one of the conversions failed.
 119 .Fn strptime_l
 120 returns the same values as
 121 .Fn strptime .
 122 .Sh SEE ALSO
 123 .Xr date 1 ,
 124 .Xr scanf 3 ,
 125 .Xr strftime 3
 126 .Sh HISTORY
 127 The
 128 .Fn strptime
 129 function appeared in
 130 .Fx 3.0 .
 131 .Sh AUTHORS
 132 The
 133 .Fn strptime
 134 function has been contributed by Powerdog Industries.
 135 .Pp
 136 This man page was written by
 137 .An J\(:org Wunsch .
 138 .Sh BUGS
 139 Both the
 140 .Fa %e
 141 and
 142 .Fa %l
 143 format specifiers may incorrectly scan one too many digits
 144 if the intended values comprise only a single digit
 145 and that digit is followed immediately by another digit.
 146 Both specifiers accept zero-padded values,
 147 even though they are both defined as taking unpadded values.
 148 .Pp
 149 The
 150 .Fa %p
 151 format specifier has no effect unless it is parsed
 152 .Em after
 153 hour-related specifiers.
 154 Specifying
 155 .Fa %l
 156 without
 157 .Fa %p
 158 will produce undefined results.
 159 Note that 12AM
 160 (ante meridiem)
 161 is taken as midnight
 162 and 12PM
 163 (post meridiem)
 164 is taken as noon.
 165 .Pp
 166 The
 167 .Fa %Z
 168 format specifier only accepts time zone abbreviations of the local time zone,
 169 or the value "GMT".
 170 This limitation is because of ambiguity due to of the over loading of time
 171 zone abbreviations.
 172 One such example is
 173 .Fa EST
 174 which is both Eastern Standard Time and Eastern Australia Summer Time.
 175 .Pp
 176 The
 177 .Fn strptime
 178 function does not correctly handle multibyte characters in the
 179 .Fa format
 180 argument.