1.\" $OpenBSD: strftime.3,v 1.37 2017/09/05 03:16:14 schwarze Exp $ 2.\" 3.\" Copyright (c) 1989, 1991 The Regents of the University of California. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the American National Standards Committee X3, on Information 8.\" Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" from: @(#)strftime.3 5.12 (Berkeley) 6/29/91 35.\" 36.Dd $Mdocdate: September 5 2017 $ 37.Dt STRFTIME 3 38.Os 39.Sh NAME 40.Nm strftime , 41.Nm strftime_l 42.Nd format date and time 43.Sh SYNOPSIS 44.In time.h 45.Ft size_t 46.Fo strftime 47.Fa "char *buf" 48.Fa "size_t maxsize" 49.Fa "const char *format" 50.Fa "const struct tm *timeptr" 51.Fc 52.Ft size_t 53.Fo strftime_l 54.Fa "char *buf" 55.Fa "size_t maxsize" 56.Fa "const char *format" 57.Fa "const struct tm *timeptr" 58.Fa "locale_t locale" 59.Fc 60.Sh DESCRIPTION 61These functions format the information from 62.Fa timeptr 63(as described in 64.Xr mktime 3 ) 65into the buffer 66.Fa buf 67according to the string pointed to by 68.Fa format . 69.Pp 70The 71.Fa format 72string consists of zero or more conversion specifications and 73ordinary characters. 74All ordinary characters are copied directly into the buffer. 75A conversion specification consists of a percent sign 76.Ql % 77and one other character. 78.Pp 79No more than 80.Fa maxsize 81characters will be placed into the array. 82.Pp 83Each conversion specification is replaced by the characters as 84follows which are then copied into the buffer. 85.Bl -tag -width "xxxx" 86.It Cm \&%A 87is replaced by the locale's full weekday name. 88.It Cm \&%a 89is replaced by the locale's abbreviated weekday name. 90.It Cm \&%B 91is replaced by the locale's full month name. 92.It Cm \&%b No or Cm \&%h 93is replaced by the locale's abbreviated month name. 94.It Cm \&%C 95is replaced by the century (a year divided by 100 and truncated to an integer) 96as a decimal number (00\-99). 97.It Cm \&%c 98is replaced by the locale's appropriate date and time representation. 99.It Cm \&%D 100is replaced by the date in the format 101.Dq Li %m/%d/%y . 102.It Cm \&%d 103is replaced by the day of the month as a decimal number (01\-31). 104.It Cm \&%e 105is replaced by the day of month as a decimal number (1\-31); 106single digits are preceded by a blank. 107.It Cm \&%F 108is replaced by the date in the format 109.Dq Li %Y-%m-%d . 110.It Cm \&%G 111is replaced by the 112.St -iso8601 113year with century as a decimal number. 114.It Cm \&%g 115is replaced by the 116.St -iso8601 117year without century as a decimal number (00\-99). 118.It Cm \&%H 119is replaced by the hour (24-hour clock) as a decimal number (00\-23). 120.It Cm \&%I 121is replaced by the hour (12-hour clock) as a decimal number (01\-12). 122.It Cm \&%j 123is replaced by the day of the year as a decimal number (001\-366). 124.It Cm \&%k 125is replaced by the hour (24-hour clock) as a decimal number (0\-23); 126single digits are preceded by a blank. 127.It Cm \&%l 128is replaced by the hour (12-hour clock) as a decimal number (1\-12); 129single digits are preceded by a blank. 130.It Cm \&%M 131is replaced by the minute as a decimal number (00\-59). 132.It Cm %m 133is replaced by the month as a decimal number (01\-12). 134.It Cm %n 135is replaced by a newline. 136.It Cm %p 137is replaced by the locale's equivalent of either 138.Dq AM 139or 140.Dq PM . 141.It Cm \&%R 142is replaced by the time in the format 143.Dq Li %H:%M . 144.It Cm \&%r 145is replaced by the locale's representation of 12-hour clock time 146using AM/PM notation. 147.It Cm \&%S 148is replaced by the second as a decimal number (00\-60). 149The range of 150seconds is (00\-60) instead of (00\-59) to allow for the periodic occurrence 151of leap seconds. 152.It Cm %s 153is replaced by the number of seconds since the Epoch, UTC (see 154.Xr mktime 3 ) . 155.It Cm \&%T 156is replaced by the time in the format 157.Dq Li %H:%M:%S . 158.It Cm \&%t 159is replaced by a tab. 160.It Cm \&%U 161is replaced by the week number of the year (Sunday as the first day of 162the week) as a decimal number (00\-53). 163.It Cm \&%u 164is replaced by the weekday (Monday as the first day of the week) 165as a decimal number (1\-7). 166.It Cm \&%V 167is replaced by the week number of the year (Monday as the first day of 168the week) as a decimal number (01\-53). 169If the week containing January 1701 has four or more days in the new year, then it is week 1; otherwise 171it is week 53 of the previous year, and the next week is week 1. 172.It Cm \&%v 173is replaced by the date in the format 174.Dq Li "%e-%b-%Y" . 175.It Cm \&%W 176is replaced by the week number of the year (Monday as the first day of 177the week) as a decimal number (00\-53). 178.It Cm \&%w 179is replaced by the weekday (Sunday as the first day of the week) 180as a decimal number (0\-6). 181.It Cm \&%X 182is replaced by the locale's appropriate time representation. 183.It Cm \&%x 184is replaced by the locale's appropriate date representation. 185.It Cm \&%Y 186is replaced by the year with century as a decimal number. 187.It Cm \&%y 188is replaced by the year without century as a decimal number (00\-99). 189.It Cm \&%Z 190is replaced by the time zone name, 191or by the empty string if this is not determinable. 192.It Cm \&%z 193is replaced by the offset from UTC in the format 194.Dq Li +HHMM 195or 196.Dq Li -HHMM 197as appropriate, with positive values representing locations east 198of Greenwich, or by the empty string if this is not determinable. 199.It Cm %% 200is replaced by 201.Ql % . 202.It Cm %+ 203is replaced by the date and time in 204.Xr date 1 205format. 206.El 207.Pp 208The 209.Ox 210implementation always uses the C locale and ignores 211the global locale, the thread-specific locale, and the 212.Fa locale 213argument. 214.Sh RETURN VALUES 215If the total number of resulting characters, including the terminating 216NUL character, is not more than 217.Fa maxsize , 218.Fn strftime 219returns the number of characters placed in the array, not counting the 220terminating NUL. 221Otherwise, zero is returned. 222.Sh ENVIRONMENT 223On other operating systems, the behaviour of 224.Fn strftime 225may depend on the 226.Dv LC_TIME 227.Xr locale 1 . 228.Sh SEE ALSO 229.Xr date 1 , 230.Xr printf 1 , 231.Xr ctime 3 , 232.Xr getenv 3 , 233.Xr printf 3 , 234.Xr strptime 3 , 235.Xr time 3 , 236.Xr tzset 3 , 237.Xr tzfile 5 238.Sh STANDARDS 239The 240.Fn strftime 241function 242conforms to 243.St -isoC-99 , 244and 245.Fn strftime_l 246to 247.St -p1003.1-2008 , 248except that the 249.Ql E 250and 251.Ql O 252conversion modifiers are ignored by this implementation. 253.Pp 254The 255.Ql \&%k , 256.Ql \&%l , 257.Ql \&%s , 258.Ql \&%v , 259and 260.Ql \&%+ 261conversion specifications are extensions. 262.Pp 263Use of the 264.St -iso8601 265conversions may produce non-intuitive results. 266Week 01 of a year is per definition the first week which has the Thursday 267in this year, which is equivalent to the week which contains the fourth 268day of January. 269In other words, the first week of a new year is the week which has the 270majority of its days in the new year. 271Week 01 might also contain days from the previous year and the week 272before week 01 of a year is the last week (52 or 53) of the previous 273year even if it contains days from the new year. 274A week starts with Monday (day 1) and ends with Sunday (day 7). 275For example, the first week of the year 1997 lasts from 2761996-12-30 to 1997-01-05. 277.Sh HISTORY 278A predecessor to 279.Fn strftime , 280.Fn ptime , 281first appeared in 282.At v1 . 283The 284.Fn strftime 285function has been available since 286.Bx 4.3 Reno , 287and 288.Fn strftime_l 289since 290.Ox 6.2 . 291.Sh AUTHORS 292.An Keith Bostic 293implemented the 294.Bx 295version of 296.Fn strftime 297in 1989. 298.Sh BUGS 299There is no conversion specification for the phase of the moon. 300.Pp 301Note that while this implementation of 302.Fn strftime 303will always NUL terminate 304.Fa buf , 305other implementations may not do so when 306.Fa maxsize 307is not large enough to store the entire time string. 308The contents of 309.Fa buf 310are implementation specific in this case. 311