1.\" $OpenBSD: strftime.3,v 1.38 2019/05/16 13:35:17 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: May 16 2019 $ 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 SEE ALSO 223.Xr date 1 , 224.Xr printf 1 , 225.Xr ctime 3 , 226.Xr getenv 3 , 227.Xr printf 3 , 228.Xr strptime 3 , 229.Xr time 3 , 230.Xr tzset 3 , 231.Xr tzfile 5 232.Sh STANDARDS 233The 234.Fn strftime 235function 236conforms to 237.St -isoC-99 , 238and 239.Fn strftime_l 240to 241.St -p1003.1-2008 , 242except that the 243.Ql E 244and 245.Ql O 246conversion modifiers are ignored by this implementation. 247.Pp 248The 249.Ql \&%k , 250.Ql \&%l , 251.Ql \&%s , 252.Ql \&%v , 253and 254.Ql \&%+ 255conversion specifications are extensions. 256.Pp 257Use of the 258.St -iso8601 259conversions may produce non-intuitive results. 260Week 01 of a year is per definition the first week which has the Thursday 261in this year, which is equivalent to the week which contains the fourth 262day of January. 263In other words, the first week of a new year is the week which has the 264majority of its days in the new year. 265Week 01 might also contain days from the previous year and the week 266before week 01 of a year is the last week (52 or 53) of the previous 267year even if it contains days from the new year. 268A week starts with Monday (day 1) and ends with Sunday (day 7). 269For example, the first week of the year 1997 lasts from 2701996-12-30 to 1997-01-05. 271.Sh HISTORY 272A predecessor to 273.Fn strftime , 274.Fn ptime , 275first appeared in 276.At v1 . 277The 278.Fn strftime 279function has been available since 280.Bx 4.3 Reno , 281and 282.Fn strftime_l 283since 284.Ox 6.2 . 285.Sh AUTHORS 286.An Keith Bostic 287implemented the 288.Bx 289version of 290.Fn strftime 291in 1989. 292.Sh CAVEATS 293On systems other than 294.Ox , 295the 296.Dv LC_TIME 297.Xr locale 1 298category can cause erratic output; see CAVEATS in 299.Xr setlocale 3 300for details. 301.Sh BUGS 302There is no conversion specification for the phase of the moon. 303.Pp 304Note that while this implementation of 305.Fn strftime 306will always NUL terminate 307.Fa buf , 308other implementations may not do so when 309.Fa maxsize 310is not large enough to store the entire time string. 311The contents of 312.Fa buf 313are implementation specific in this case. 314