lib/libc/time/strftime.3

   1 .\" Copyright (c) 1989, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   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 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     from: @(#)strftime.3    5.12 (Berkeley) 6/29/91
  33 .\"     $NetBSD: strftime.3,v 1.23 2006/06/17 04:58:14 reed Exp $
  34 .\"
  35 .Dd April 14, 2004
  36 .Dt STRFTIME 3
  37 .Os
  38 .Sh NAME
  39 .Nm strftime
  40 .Nd format date and time
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In time.h
  45 .Ft size_t
  46 .Fn strftime "char * restrict buf" "size_t maxsize" "const char * restrict format" "const struct tm * restrict timeptr"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn strftime
  50 function formats the information from
  51 .Fa timeptr
  52 into the buffer
  53 .Fa buf
  54 according to the string pointed to by
  55 .Fa format .
  56 .Pp
  57 The
  58 .Fa format
  59 string consists of zero or more conversion specifications and
  60 ordinary characters.
  61 All ordinary characters are copied directly into the buffer.
  62 A conversion specification consists of a percent sign
  63 .Ql %
  64 and one other character.
  65 .Pp
  66 No more than
  67 .Fa maxsize
  68 characters will be placed into the array.
  69 If the total number of resulting characters, including the terminating
  70 null character, is not more than
  71 .Fa maxsize ,
  72 .Fn strftime
  73 returns the number of characters in the array, not counting the
  74 terminating null.
  75 Otherwise, zero is returned and the contents of the array are undefined.
  76 .Pp
  77 Each conversion specification is replaced by the characters as
  78 follows which are then copied into the buffer.
  79 .Bl -tag -width "xxxx"
  80 .It Cm \&%A
  81 is replaced by the locale's full weekday name.
  82 .It Cm %a
  83 is replaced by the locale's abbreviated weekday name.
  84 .It Cm \&%B
  85 is replaced by the locale's full month name.
  86 .It Cm \&%b No or Cm \&%h
  87 is replaced by the locale's abbreviated month name.
  88 .It Cm \&%C
  89 is replaced by the century (a year divided by 100 and truncated to an integer)
  90 as a decimal number [00,99].
  91 .It Cm \&%c
  92 is replaced by the locale's appropriate date and time representation.
  93 .It Cm \&%D
  94 is replaced by the date in the format
  95 .Dq Li %m/%d/%y .
  96 .It Cm \&%d
  97 is replaced by the day of the month as a decimal number [01,31].
  98 .It Cm \&%e
  99 is replaced by the day of month as a decimal number [1,31];
 100 single digits are preceded by a blank.
 101 .It Cm \&%F
 102 is replaced by the date in the format
 103 .Dq Li %Y-%m-%d
 104 (the ISO 8601 date format).
 105 .It Cm \&%G
 106 is replaced by the ISO 8601 year with century as a decimal number.
 107 .It Cm \&%g
 108 is replaced by the ISO 8601 year without century as a decimal number (00-99).
 109 This is the year that includes the greater part of the week.
 110 (Monday as the first day of a week).
 111 See also the
 112 .Ql \&%V
 113 conversion specification.
 114 .It Cm \&%H
 115 is replaced by the hour (24-hour clock) as a decimal number [00,23].
 116 .It Cm \&%I
 117 is replaced by the hour (12-hour clock) as a decimal number [01,12].
 118 .It Cm \&%j
 119 is replaced by the day of the year as a decimal number [001,366].
 120 .It Cm \&%k
 121 is replaced by the hour (24-hour clock) as a decimal number [0,23];
 122 single digits are preceded by a blank.
 123 .It Cm \&%l
 124 is replaced by the hour (12-hour clock) as a decimal number [1,12];
 125 single digits are preceded by a blank.
 126 .It Cm \&%M
 127 is replaced by the minute as a decimal number [00,59].
 128 .It Cm %m
 129 is replaced by the month as a decimal number [01,12].
 130 .It Cm %n
 131 is replaced by a newline.
 132 .It Cm %p
 133 is replaced by the locale's equivalent of either
 134 .Dq Tn AM
 135 or
 136 .Dq Tn PM .
 137 .It Cm \&%R
 138 is replaced by the time in the format
 139 .Dq Li %H:%M .
 140 .It Cm \&%r
 141 is replaced by the locale's representation of 12-hour clock time
 142 using AM/PM notation.
 143 .It Cm \&%S
 144 is replaced by the second as a decimal number [00,61].
 145 The range of
 146 seconds is (00-61) instead of (00-59) to allow for the periodic occurrence
 147 of leap seconds and double leap seconds.
 148 .It Cm %s
 149 is replaced by the number of seconds since the Epoch, UTC (see
 150 .Xr mktime 3 ) .
 151 .It Cm \&%T
 152 is replaced by the time in the format
 153 .Dq Li %H:%M:%S .
 154 .It Cm \&%t
 155 is replaced by a tab.
 156 .It Cm \&%U
 157 is replaced by the week number of the year (Sunday as the first day of
 158 the week) as a decimal number [00,53].
 159 .It Cm \&%u
 160 is replaced by the weekday (Monday as the first day of the week)
 161 as a decimal number [1,7].
 162 .It Cm \&%V
 163 is replaced by the week number of the year (Monday as the first day of
 164 the week) as a decimal number [01,53]. According to ISO 8601 the week
 165 containing January 1 is week 1 if it has four or more days in the new year,
 166 otherwise it is week 53 of the previous year, and the next week is week 1.
 167 The year is given by the
 168 .Ql \&%G
 169 conversion specification.
 170 .It Cm \&%v
 171 is replaced by the date in the format
 172 .Dq Li %e-%b-%Y .
 173 .It Cm \&%W
 174 is replaced by the week number of the year (Monday as the first day of
 175 the week) as a decimal number [00,53].
 176 .It Cm \&%w
 177 is replaced by the weekday (Sunday as the first day of the week)
 178 as a decimal number [0,6].
 179 .It Cm \&%X
 180 is replaced by the locale's appropriate time representation.
 181 .It Cm \&%x
 182 is replaced by the locale's appropriate date representation.
 183 .It Cm \&%Y
 184 is replaced by the year with century as a decimal number.
 185 .It Cm \&%y
 186 is replaced by the year without century as a decimal number [00,99].
 187 .It Cm \&%Z
 188 is replaced by the time zone name.
 189 .It Cm \&%z
 190 is replaced by the offset from ITC in the ISO 8601 format
 191 .Dq Li [-]hhmm .
 192 .It Cm %%
 193 is replaced by
 194 .Ql % .
 195 .El
 196 .Sh SEE ALSO
 197 .Xr date 1 ,
 198 .Xr printf 1 ,
 199 .Xr ctime 3 ,
 200 .Xr printf 3 ,
 201 .Xr strptime 3
 202 .Sh STANDARDS
 203 The
 204 .Fn strftime
 205 function
 206 conforms to
 207 .St -isoC-99 .
 208 The
 209 .Ql \&%C ,
 210 .Ql \&%D ,
 211 .Ql \&%e ,
 212 .Ql \&%g ,
 213 .Ql \&%G ,
 214 .Ql \&%h ,
 215 .Ql \&%k ,
 216 .Ql \&%l ,
 217 .Ql \&%n ,
 218 .Ql \&%r ,
 219 .Ql \&%R ,
 220 .Ql \&%s ,
 221 .Ql \&%t ,
 222 .Ql \&%T ,
 223 .Ql \&%u ,
 224 .Ql \&%V ,
 225 and
 226 .Ql \&%v
 227 conversion specifications are extensions.
 228 .Pp
 229 Use of the ISO 8601 conversions may produce non-intuitive results.
 230 Week 01 of a year is per definition the first week which has the Thursday
 231 in this year, which is equivalent to the week which contains the fourth
 232 day of January.
 233 In other words, the first week of a new year is the week which has the
 234 majority of its days in the new year.
 235 Week 01 might also contain days from the previous year and the week
 236 before week 01 of a year is the last week (52 or 53) of the previous
 237 year even if it contains days from the new year.
 238 A week starts with Monday (day 1) and ends with Sunday (day 7).
 239 For example, the first week of the year 1997 lasts from
 240 1996-12-30 to 1997-01-05.
 241 .Sh BUGS
 242 There is no conversion specification for the phase of the moon.