1.\" $OpenBSD: strftime.3,v 1.39 2024/04/29 13:34:19 naddy 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: April 29 2024 $ 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 113week-numbering year with century as a decimal number. 114See also the 115.Cm \&%V 116conversion specification and the 117.Sx STANDARDS 118section for more details. 119.It Cm \&%g 120is replaced by the 121.St -iso8601 122week-numbering year without century as a decimal number (00\-99). 123See also the 124.Cm \&%V 125conversion specification and the 126.Sx STANDARDS 127section for more details. 128.It Cm \&%H 129is replaced by the hour (24-hour clock) as a decimal number (00\-23). 130.It Cm \&%I 131is replaced by the hour (12-hour clock) as a decimal number (01\-12). 132.It Cm \&%j 133is replaced by the day of the year as a decimal number (001\-366). 134.It Cm \&%k 135is replaced by the hour (24-hour clock) as a decimal number (0\-23); 136single digits are preceded by a blank. 137.It Cm \&%l 138is replaced by the hour (12-hour clock) as a decimal number (1\-12); 139single digits are preceded by a blank. 140.It Cm \&%M 141is replaced by the minute as a decimal number (00\-59). 142.It Cm %m 143is replaced by the month as a decimal number (01\-12). 144.It Cm %n 145is replaced by a newline. 146.It Cm %p 147is replaced by the locale's equivalent of either 148.Dq AM 149or 150.Dq PM . 151.It Cm \&%R 152is replaced by the time in the format 153.Dq Li %H:%M . 154.It Cm \&%r 155is replaced by the locale's representation of 12-hour clock time 156using AM/PM notation. 157.It Cm \&%S 158is replaced by the second as a decimal number (00\-60). 159The range of 160seconds is (00\-60) instead of (00\-59) to allow for the periodic occurrence 161of leap seconds. 162.It Cm %s 163is replaced by the number of seconds since the Epoch, UTC (see 164.Xr mktime 3 ) . 165.It Cm \&%T 166is replaced by the time in the format 167.Dq Li %H:%M:%S . 168.It Cm \&%t 169is replaced by a tab. 170.It Cm \&%U 171is replaced by the week number of the year (Sunday as the first day of 172the week) as a decimal number (00\-53). 173.It Cm \&%u 174is replaced by the weekday (Monday as the first day of the week) 175as a decimal number (1\-7). 176.It Cm \&%V 177is replaced by the week number of the year (Monday as the first day of 178the week) as a decimal number (01\-53). 179If the week containing January 1801 has four or more days in the new year, then it is week 1; otherwise 181it is week 53 of the previous year, and the next week is week 1. 182The year is given by the 183.Cm \&%G 184conversion specification. 185See the 186.Sx STANDARDS 187section for more details. 188.It Cm \&%v 189is replaced by the date in the format 190.Dq Li "%e-%b-%Y" . 191.It Cm \&%W 192is replaced by the week number of the year (Monday as the first day of 193the week) as a decimal number (00\-53). 194.It Cm \&%w 195is replaced by the weekday (Sunday as the first day of the week) 196as a decimal number (0\-6). 197.It Cm \&%X 198is replaced by the locale's appropriate time representation. 199.It Cm \&%x 200is replaced by the locale's appropriate date representation. 201.It Cm \&%Y 202is replaced by the year with century as a decimal number. 203.It Cm \&%y 204is replaced by the year without century as a decimal number (00\-99). 205.It Cm \&%Z 206is replaced by the time zone name, 207or by the empty string if this is not determinable. 208.It Cm \&%z 209is replaced by the offset from UTC in the format 210.Dq Li +HHMM 211or 212.Dq Li -HHMM 213as appropriate, with positive values representing locations east 214of Greenwich, or by the empty string if this is not determinable. 215.It Cm %% 216is replaced by 217.Ql % . 218.It Cm %+ 219is replaced by the date and time in 220.Xr date 1 221format. 222.El 223.Pp 224The 225.Ox 226implementation always uses the C locale and ignores 227the global locale, the thread-specific locale, and the 228.Fa locale 229argument. 230.Sh RETURN VALUES 231If the total number of resulting characters, including the terminating 232NUL character, is not more than 233.Fa maxsize , 234.Fn strftime 235returns the number of characters placed in the array, not counting the 236terminating NUL. 237Otherwise, zero is returned. 238.Sh SEE ALSO 239.Xr date 1 , 240.Xr printf 1 , 241.Xr ctime 3 , 242.Xr getenv 3 , 243.Xr printf 3 , 244.Xr strptime 3 , 245.Xr time 3 , 246.Xr tzset 3 , 247.Xr tzfile 5 248.Sh STANDARDS 249The 250.Fn strftime 251function 252conforms to 253.St -isoC-99 , 254and 255.Fn strftime_l 256to 257.St -p1003.1-2008 , 258except that the 259.Ql E 260and 261.Ql O 262conversion modifiers are ignored by this implementation. 263.Pp 264The 265.Ql \&%k , 266.Ql \&%l , 267.Ql \&%s , 268.Ql \&%v , 269and 270.Ql \&%+ 271conversion specifications are extensions. 272.Pp 273Use of the 274.St -iso8601 275conversions may produce non-intuitive results. 276Week 01 of a year is per definition the first week which has the Thursday 277in this year, which is equivalent to the week which contains the fourth 278day of January. 279In other words, the first week of a new year is the week which has the 280majority of its days in the new year. 281Week 01 might also contain days from the previous year and the week 282before week 01 of a year is the last week (52 or 53) of the previous 283year even if it contains days from the new year. 284A week starts with Monday (day 1) and ends with Sunday (day 7). 285For example, the first week of the year 1997 lasts from 2861996-12-30 to 1997-01-05. 287.Sh HISTORY 288A predecessor to 289.Fn strftime , 290.Fn ptime , 291first appeared in 292.At v1 . 293The 294.Fn strftime 295function has been available since 296.Bx 4.3 Reno , 297and 298.Fn strftime_l 299since 300.Ox 6.2 . 301.Sh AUTHORS 302.An Keith Bostic 303implemented the 304.Bx 305version of 306.Fn strftime 307in 1989. 308.Sh CAVEATS 309On systems other than 310.Ox , 311the 312.Dv LC_TIME 313.Xr locale 1 314category can cause erratic output; see CAVEATS in 315.Xr setlocale 3 316for details. 317.Sh BUGS 318There is no conversion specification for the phase of the moon. 319.Pp 320Note that while this implementation of 321.Fn strftime 322will always NUL terminate 323.Fa buf , 324other implementations may not do so when 325.Fa maxsize 326is not large enough to store the entire time string. 327The contents of 328.Fa buf 329are implementation specific in this case. 330