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.36 2020/10/09 18:38:48 christos Exp $ 34.\" 35.Dd October 9, 2020 36.Dt STRFTIME 3 37.Os 38.Sh NAME 39.Nm strftime , 40.Nm strftime_z 41.Nd format date and time 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In time.h 46.Ft size_t 47.Fn strftime "char * restrict buf" "size_t maxsize" "const char * restrict format" "const struct tm * restrict timeptr" 48.Ft size_t 49.Fn strftime_z "const timezone_t tz" "char * restrict buf" "size_t maxsize" "const char * restrict format" "const struct tm * restrict timeptr" 50.Sh DESCRIPTION 51The 52.Fn strftime 53function formats the information from 54.Fa timeptr 55into the array pointed to by 56.Fa buf 57according to the string pointed to by 58.Fa format . 59.Pp 60The 61.Fa format 62string consists of zero or more conversion specifications and 63ordinary characters. 64All ordinary characters are copied directly into the array. 65A conversion specification consists of a percent sign 66.Ql % 67and one other character. 68.Pp 69No more than 70.Fa maxsize 71bytes will be placed into the array. 72Otherwise, zero is returned. 73.Pp 74Each conversion specification is replaced by the characters as 75follows which are then copied into the array. 76.Bl -tag -width "xxxx" 77.It Cm \&%A 78is replaced by the locale's full weekday name. 79.It Cm %a 80is replaced by the locale's abbreviated weekday name. 81.It Cm \&%B 82is replaced by the locale's full month name. 83.It Cm \&%b No or Cm \&%h 84is replaced by the locale's abbreviated month name. 85.It Cm \&%C 86is replaced by the century (a year divided by 100 and truncated to an integer) 87as a decimal number [00,99]. 88.It Cm \&%c 89is replaced by the locale's appropriate date and time representation. 90.It Cm \&%D 91is replaced by the date in the format 92.Dq Li %m/%d/%y . 93.It Cm \&%d 94is replaced by the day of the month as a decimal number [01,31]. 95.It Cm \&%e 96is replaced by the day of month as a decimal number [1,31]; 97single digits are preceded by a blank. 98.It Cm \&%F 99is equivalent to 100.Dq Li %Y-%m-%d 101(the ISO 8601 date format). 102.It Cm \&%G 103is replaced by the ISO 8601 year with century as a decimal number. 104See also the 105.Cm \&%V 106conversion specification 107.It Cm \&%g 108is replaced by the ISO 8601 year without century as a decimal number [00-99]. 109This is the year that includes the greater part of the week. 110(Monday as the first day of a week). 111See also the 112.Ql \&%V 113conversion specification. 114.It Cm \&%H 115is replaced by the hour (24-hour clock) as a decimal number [00,23]. 116.It Cm \&%I 117is replaced by the hour (12-hour clock) as a decimal number [01,12]. 118.It Cm \&%j 119is replaced by the day of the year as a decimal number [001,366]. 120.It Cm \&%k 121is replaced by the hour (24-hour clock) as a decimal number [0,23]; 122single digits are preceded by a blank. 123.It Cm \&%l 124is replaced by the hour (12-hour clock) as a decimal number [1,12]; 125single digits are preceded by a blank. 126.It Cm \&%M 127is replaced by the minute as a decimal number [00,59]. 128.It Cm %m 129is replaced by the month as a decimal number [01,12]. 130.It Cm %n 131is replaced by a newline. 132.It Cm %p 133is replaced by the locale's equivalent of either 134.Dq Tn AM 135or 136.Dq Tn PM . 137.It Cm \&%R 138is replaced by the time in the format 139.Dq Li %H:%M . 140.It Cm \&%r 141is replaced by the locale's representation of 12-hour clock time 142using AM/PM notation. 143.It Cm \&%S 144is replaced by the second as a decimal number [00,60]. 145The range of 146seconds is [00-60] instead of [00-59] to allow for the periodic occurrence 147of leap seconds. 148.It Cm \&%s 149is replaced by the number of seconds since the Epoch (see 150.Xr ctime 3 ) . 151.It Cm \&%T 152is replaced by the time in the format 153.Dq Li %H:%M:%S . 154.It Cm \&%t 155is replaced by a tab. 156.It Cm \&%U 157is replaced by the week number of the year (Sunday as the first day of 158the week) as a decimal number [00,53]. 159.It Cm \&%u 160is replaced by the weekday (Monday as the first day of the week) 161as a decimal number [1,7]. 162.It Cm \&%V 163is replaced by the week number of the year (Monday as the first day of 164the week) as a decimal number [01,53]. According to ISO 8601 the week 165containing January 1 is week 1 if it has four or more days in the new year, 166otherwise it is week 53 of the previous year, and the next week is week 1. 167The year is given by the 168.Ql \&%G 169conversion specification. 170.It Cm \&%v 171is replaced by the date in the format 172.Dq Li %e-%b-%Y . 173.It Cm \&%W 174is replaced by the week number of the year (Monday as the first day of 175the week) as a decimal number [00,53]. 176.It Cm \&%w 177is replaced by the weekday (Sunday as the first day of the week) 178as a decimal number [0,6]. 179.It Cm \&%X 180is replaced by the locale's appropriate time representation. 181.It Cm \&%x 182is replaced by the locale's appropriate date representation. 183.It Cm \&%Y 184is replaced by the year with century as a decimal number. 185.It Cm \&%y 186is replaced by the year without century as a decimal number [00,99]. 187.It Cm \&%Z 188is replaced by the time zone abbreviation, 189or the empty string if this is not determinable. 190.It Cm \&%z 191is replaced by the offset from the Prime Meridian in the format 192+HHMM or -HHMM (ISO 8601) as appropriate, with positive values representing 193locations east of Greenwich, or by the empty string if this is 194not determinable. 195The numeric time zone abbreviation \&-0000 is used when the time is 196Universal Time 197but local time is indeterminate; by convention this is used for 198locations while uninhabited, and corresponds to a zero offset when the 199time zone abbreviation begins with 200.Dq Li [-] . 201.It Cm %+ 202is replaced by locale's date and time in 203.Xr date 1 204format. 205On 206.Nx 207currently this only works for the C locale. 208.It Cm %-* 209GNU libc extension. 210Do not do any padding when performing numerical outputs. 211.It Cm %_* 212GNU libc extension. 213Explicitly specify space for padding. 214.It Cm %0* 215GNU libc extension. 216Explicitly specify zero for padding. 217.It Cm %% 218is replaced by 219.Ql % . 220.El 221.Pp 222The 223.Fn strftime_z 224function is similar to 225.Fn strftime , 226but it also takes a 227.Ft "const timezone_t" 228.Fa tz 229argument. 230.Sh RETURN VALUES 231If the conversion is successful, 232.Nm 233returns the number of bytes placed into the array, not counting the 234terminating 235.Dv NUL ; 236.Va errno 237is unchanged if the returned value is zero. 238Otherwise, 239.Va errno 240is set to indicate the error, zero is returned, 241and the array contents are unspecified. 242.Sh ERRORS 243This function fails if: 244.Bl -tag -width Er 245.It Bq Er ERANGE 246The specified file offset is invalid. 247The total number of resulting bytes, including the terminating 248.Dv NUL 249character, is more than 250.Fa maxsize . 251.It Bq Er EOVERFLOW 252The format includes an 253.Cm \&%s 254conversion and the number of seconds since the Epoch cannot be represented 255in a 256.Ft time_t . 257.El 258.Sh SEE ALSO 259.Xr date 1 , 260.Xr printf 1 , 261.Xr ctime 3 , 262.Xr printf 3 , 263.Xr strptime 3 , 264.Xr tm 3 265.Sh STANDARDS 266The 267.SH BUGS 268There is no conversion specification for the phase of the moon. 269.Fn strftime 270function 271conforms to 272.St -isoC-99 . 273The 274.Ql \&%C , 275.Ql \&%D , 276.Ql \&%e , 277.Ql \&%g , 278.Ql \&%G , 279.Ql \&%h , 280.Ql \&%k , 281.Ql \&%l , 282.Ql \&%n , 283.Ql \&%r , 284.Ql \&%R , 285.Ql \&%s , 286.Ql \&%t , 287.Ql \&%T , 288.Ql \&%u , 289.Ql \&%V , 290and 291.Ql \&%v 292conversion specifications are extensions. 293.Pp 294Use of the ISO 8601 conversions may produce non-intuitive results. 295Week 01 of a year is per definition the first week which has the Thursday 296in this year, which is equivalent to the week which contains the fourth 297day of January. 298In other words, the first week of a new year is the week which has the 299majority of its days in the new year. 300Week 01 might also contain days from the previous year and the week 301before week 01 of a year is the last week (52 or 53) of the previous 302year even if it contains days from the new year. 303A week starts with Monday (day 1) and ends with Sunday (day 7). 304For example, the first week of the year 1997 lasts from 3051996-12-30 to 1997-01-05. 306.Sh BUGS 307There is no conversion specification for the phase of the moon. 308.Pp 309A return value of zero does not necessarily indicate an error. 310If the resulting string is an empty string, the result value is 311zero and it is not possible to distinguish between success and error. 312For example, in many locales 313.Cm \&%p 314yields an empty string. 315This problem can be avoided by inserting an extra space at the 316beginning of the format string and then skipping over it or removing 317it from the result. 318