lib/libc/stdtime/strptime.3

   1 .\"     $NetBSD: strptime.3,v 1.22 2008/11/04 18:37:28 christos Exp $
   2 .\"
   3 .\" Copyright (c) 1997, 1998, 2008 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This file was contributed to The NetBSD Foundation by Klaus Klein.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  19 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  20 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  21 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 .\" POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .Dd November 4, 2008
  30 .Dt STRPTIME 3
  31 .Os
  32 .Sh NAME
  33 .Nm strptime
  34 .Nd converts a character string to a time value
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In time.h
  39 .Ft char *
  40 .Fn strptime "const char * restrict buf" "const char * restrict format" "struct tm * restrict tm"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn strptime
  44 function converts the character string pointed to by
  45 .Fa buf
  46 to values which are stored in the
  47 .Va tm
  48 structure pointed to by
  49 .Fa tm ,
  50 using the format specified by
  51 .Fa format .
  52 .Pp
  53 The
  54 .Fa format
  55 string consists of zero or more conversion specifications, whitespace
  56 characters as defined by
  57 .Fn isspace ,
  58 and ordinary characters.
  59 All ordinary characters in
  60 .Fa format
  61 are compared directly against the corresponding characters in
  62 .Fa buf ;
  63 comparisons which fail will cause
  64 .Fn strptime
  65 to fail.
  66 Whitespace characters in
  67 .Fa format
  68 match any number of whitespace characters in
  69 .Fa buf ,
  70 including none.
  71 .Pp
  72 A conversion specification consists of a percent sign
  73 .Ql %
  74 followed by one
  75 or two conversion characters which specify the replacement required.
  76 There must be white-space or other non-alphanumeric characters between any
  77 two conversion specifications.
  78 .Pp
  79 Conversion of alphanumeric strings (such as month and weekday names) is
  80 done without regard to case.
  81 Conversion specifications which cannot be matched will cause
  82 .Fn strptime
  83 to fail.
  84 .Pp
  85 The LC_TIME category defines the locale values for the conversion
  86 specifications.
  87 The following conversion specifications are supported:
  88 .Bl -tag -width "xxxx"
  89 .It Cm \&%a
  90 the day of week, using the locale's weekday names;
  91 either the abbreviated or full name may be specified.
  92 .It Cm \&%A
  93 the same as
  94 .Cm \&%a .
  95 .It Cm \&%b
  96 the month, using the locale's month names;
  97 either the abbreviated or full name may be specified.
  98 .It Cm \&%B
  99 the same as
 100 .Cm \&%b .
 101 .It Cm \&%c
 102 the date and time, using the locale's date and time format.
 103 .It Cm \&%C
 104 the century number [0,99];
 105 leading zeros are permitted but not required.
 106 This conversion should be used in conjunction with the \&%y conversion.
 107 .It Cm \&%d
 108 the day of month [1,31];
 109 leading zeros are permitted but not required.
 110 .It Cm \&%D
 111 the date as %m/%d/%y.
 112 .It Cm \&%e
 113 the same as
 114 .Cm \&%d .
 115 .It Cm \&%F
 116 the date as %Y-%m-%d
 117 (the ISO 8601 date format).
 118 .It Cm \&%g
 119 the year corresponding to the ISO week number, without the century.
 120 .Po
 121 A
 122 .Nx
 123 extension.
 124 .Pc
 125 .It Cm \&%G
 126 the year corresponding to the ISO week number, with the century.
 127 .Po
 128 A
 129 .Nx
 130 extension.
 131 .Pc
 132 .It Cm \&%h
 133 the same as
 134 .Cm \&%b .
 135 .It Cm \&%H
 136 the hour (24-hour clock) [0,23];
 137 leading zeros are permitted but not required.
 138 .It Cm \&%I
 139 the hour (12-hour clock) [1,12];
 140 leading zeros are permitted but not required.
 141 .It Cm \&%j
 142 the day number of the year [1,366];
 143 leading zeros are permitted but not required.
 144 .It Cm \&%k
 145 the same as
 146 .Cm \&%H .
 147 .It Cm \&%l
 148 the same as
 149 .Cm \&%I .
 150 .It Cm \&%m
 151 the month number [1,12];
 152 leading zeros are permitted but not required.
 153 .It Cm \&%M
 154 the minute [0,59];
 155 leading zeros are permitted but not required.
 156 .It Cm \&%n
 157 any white-space, including none.
 158 .It Cm \&%p
 159 the locale's equivalent of a.m. or p.m.
 160 .It Cm \&%r
 161 the time (12-hour clock) with %p, using the locale's time format.
 162 .It Cm \&%R
 163 the time as %H:%M.
 164 .It Cm \&%S
 165 the seconds [0,61];
 166 leading zeros are permitted but not required.
 167 .It Cm \&%t
 168 any white-space, including none.
 169 .It Cm \&%T
 170 the time as %H:%M:%S.
 171 .It Cm \&%u
 172 the day of the week as a decimal number, where Monday = 1.
 173 .Po
 174 A
 175 .Nx
 176 extension.
 177 .Pc
 178 .It Cm \&%U
 179 the week number of the year (Sunday as the first day of the week)
 180 as a decimal number [0,53];
 181 leading zeros are permitted but not required.
 182 All days in a year preceding the first Sunday are considered to be in week 0.
 183 .It Cm \&%V
 184 the ISO 8601:1988 week number as a decimal number.
 185 If the week (starting on Monday) that contains January 1 has more than
 186 three days in the new year, then it is considered the first week of the
 187 year.
 188 If it has fewer than four days in the new year, then it is considered
 189 the last week of the previous year.
 190 Weeks are numbered from 1 to 53.
 191 A
 192 .Nx
 193 extension.
 194 .It Cm \&%w
 195 the weekday as a decimal number [0,6], with 0 representing Sunday;
 196 leading zeros are permitted but not required.
 197 .It Cm \&%W
 198 the week number of the year (Monday as the first day of the week)
 199 as a decimal number [0,53];
 200 leading zeros are permitted but not required.
 201 All days in a year preceding the first Monday are considered to be in week 0.
 202 .It Cm \&%x
 203 the date, using the locale's date format.
 204 .It Cm \&%X
 205 the time, using the locale's time format.
 206 .It Cm \&%y
 207 the year within the 20th century [69,99] or the 21st century [0,68];
 208 leading zeros are permitted but not required.
 209 If specified in conjunction
 210 with \&%C, specifies the year [0,99] within that century.
 211 .It Cm \&%Y
 212 the year, including the century (i.e., 1996).
 213 .It Cm \&%z
 214 an ISO 8601 timezone specification.
 215 This is either,
 216 .Dq Z
 217 for
 218 .Ql UTC ,
 219 or the offset specified as:
 220 .Dq [+-]hhmm
 221 or
 222 .Dq [+-]hh:mm
 223 or
 224 .Dq [+-]hh .
 225 .Po
 226 A
 227 .Nx
 228 extension.
 229 .Pc
 230 .It Cm \&%Z
 231 timezone name or no characters when time zone information is unavailable.
 232 .Po
 233 A
 234 .Nx
 235 extension.
 236 .Pc
 237 .It Cm \&%%
 238 matches a literal `%'.
 239 No argument is converted.
 240 .El
 241 .Ss Modified conversion specifications
 242 For compatibility, certain conversion specifications can be modified
 243 by the
 244 .Cm E
 245 and
 246 .Cm O
 247 modifier characters to indicate that an alternative format or specification
 248 should be used rather than the one normally used by the unmodified
 249 conversion specification.
 250 As there are currently neither alternative formats
 251 nor specifications supported by the system, the behavior will be as if the
 252 unmodified conversion specification were used.
 253 .Pp
 254 Case is ignored when matching string items in
 255 .Fa buf ,
 256 such as month and weekday names.
 257 .Sh RETURN VALUES
 258 If successful, the
 259 .Fn strptime
 260 function returns a pointer to the character following the last character
 261 parsed.
 262 Otherwise, a null pointer is returned.
 263 .Sh SEE ALSO
 264 .Xr ctime 3 ,
 265 .Xr isspace 3 ,
 266 .Xr localtime 3 ,
 267 .Xr strftime 3
 268 .Sh STANDARDS
 269 The
 270 .Fn strptime
 271 function conforms to
 272 .St -xpg4 .
 273 .Sh BUGS
 274 The
 275 .Cm \&%Z
 276 format specifier only accepts timezone
 277 abbreviations of the local timezone,
 278 or the value
 279 .Dq GMT .
 280 This limitation is caused by the ambiguity
 281 of overloaded timezone abbreviations,
 282 for example EST is both Eastern Standard
 283 Time and Eastern Australia Summer Time.