1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. 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.\" @(#)strftime.3 8.1 (Berkeley) 6/4/93 33.\" 34.Dd June 25, 2012 35.Dt STRFTIME 3 36.Os 37.Sh NAME 38.Nm strftime 39.Nd format date and time 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In time.h 44.Ft size_t 45.Fo strftime 46.Fa "char * restrict buf" 47.Fa "size_t maxsize" 48.Fa "const char * restrict format" 49.Fa "const struct tm * restrict timeptr" 50.Fc 51.Ft size_t 52.Fn strftime_l "char *restrict buf" "size_t maxsize" "const char * restrict format" "const struct tm *restrict timeptr" "locale_t loc" 53.Sh DESCRIPTION 54The 55.Fn strftime 56function formats the information from 57.Fa timeptr 58into the buffer 59.Fa buf 60according to the string pointed to by 61.Fa format . 62The function 63.Fn strftime_l 64does the same as 65.Fn strftime 66but takes an explicit locale rather than using the current locale. 67.Pp 68The 69.Fa format 70string consists of zero or more conversion specifications and 71ordinary characters. 72All ordinary characters are copied directly into the buffer. 73A conversion specification consists of a percent sign 74.Dq Ql % 75and one other character. 76.Pp 77No more than 78.Fa maxsize 79characters will be placed into the array. 80If the total number of resulting characters, including the terminating 81NUL character, is not more than 82.Fa maxsize , 83.Fn strftime 84returns the number of characters in the array, not counting the 85terminating NUL. 86Otherwise, zero is returned and the buffer contents are indeterminate. 87.Pp 88The conversion specifications are copied to the buffer after expansion 89as follows: 90.Bl -tag -width "xxxx" 91.It Cm \&%A 92is replaced by national representation of the full weekday name. 93.It Cm %a 94is replaced by national representation of 95the abbreviated weekday name. 96.It Cm \&%B 97is replaced by national representation of the full month name. 98.It Cm %b 99is replaced by national representation of 100the abbreviated month name. 101.It Cm \&%C 102is replaced by (year / 100) as decimal number; single 103digits are preceded by a zero. 104.It Cm %c 105is replaced by national representation of time and date. 106.It Cm \&%D 107is equivalent to 108.Dq Li %m/%d/%y . 109.It Cm %d 110is replaced by the day of the month as a decimal number (01-31). 111.It Cm %E* %O* 112POSIX locale extensions. 113The sequences 114%Ec %EC %Ex %EX %Ey %EY 115%Od %Oe %OH %OI %Om %OM 116%OS %Ou %OU %OV %Ow %OW %Oy 117are supposed to provide alternate 118representations. 119.Pp 120Additionally %OB implemented 121to represent alternative months names 122(used standalone, without day mentioned). 123.It Cm %e 124is replaced by the day of the month as a decimal number (1-31); single 125digits are preceded by a blank. 126.It Cm \&%F 127is equivalent to 128.Dq Li %Y-%m-%d . 129.It Cm \&%G 130is replaced by a year as a decimal number with century. 131This year is the one that contains the greater part of 132the week (Monday as the first day of the week). 133.It Cm %g 134is replaced by the same year as in 135.Dq Li %G , 136but as a decimal number without century (00-99). 137.It Cm \&%H 138is replaced by the hour (24-hour clock) as a decimal number (00-23). 139.It Cm %h 140the same as 141.Cm %b . 142.It Cm \&%I 143is replaced by the hour (12-hour clock) as a decimal number (01-12). 144.It Cm %j 145is replaced by the day of the year as a decimal number (001-366). 146.It Cm %k 147is replaced by the hour (24-hour clock) as a decimal number (0-23); 148single digits are preceded by a blank. 149.It Cm %l 150is replaced by the hour (12-hour clock) as a decimal number (1-12); 151single digits are preceded by a blank. 152.It Cm \&%M 153is replaced by the minute as a decimal number (00-59). 154.It Cm %m 155is replaced by the month as a decimal number (01-12). 156.It Cm %n 157is replaced by a newline. 158.It Cm %O* 159the same as 160.Cm %E* . 161.It Cm %p 162is replaced by national representation of either 163"ante meridiem" (a.m.) 164or 165"post meridiem" (p.m.) 166as appropriate. 167.It Cm \&%R 168is equivalent to 169.Dq Li %H:%M . 170.It Cm %r 171is equivalent to 172.Dq Li %I:%M:%S %p . 173.It Cm \&%S 174is replaced by the second as a decimal number (00-60). 175.It Cm %s 176is replaced by the number of seconds since the Epoch, UTC (see 177.Xr mktime 3 ) . 178.It Cm \&%T 179is equivalent to 180.Dq Li %H:%M:%S . 181.It Cm %t 182is replaced by a tab. 183.It Cm \&%U 184is replaced by the week number of the year (Sunday as the first day of 185the week) as a decimal number (00-53). 186.It Cm %u 187is replaced by the weekday (Monday as the first day of the week) 188as a decimal number (1-7). 189.It Cm \&%V 190is replaced by the week number of the year (Monday as the first day of 191the week) as a decimal number (01-53). 192If the week containing January 1931 has four or more days in the new year, then it is week 1; otherwise 194it is the last week of the previous year, and the next week is week 1. 195.It Cm %v 196is equivalent to 197.Dq Li %e-%b-%Y . 198.It Cm \&%W 199is replaced by the week number of the year (Monday as the first day of 200the week) as a decimal number (00-53). 201.It Cm %w 202is replaced by the weekday (Sunday as the first day of the week) 203as a decimal number (0-6). 204.It Cm \&%X 205is replaced by national representation of the time. 206.It Cm %x 207is replaced by national representation of the date. 208.It Cm \&%Y 209is replaced by the year with century as a decimal number. 210.It Cm %y 211is replaced by the year without century as a decimal number (00-99). 212.It Cm \&%Z 213is replaced by the time zone name. 214.It Cm %z 215is replaced by the time zone offset from UTC; a leading plus sign stands for 216east of UTC, a minus sign for west of UTC, hours and minutes follow 217with two digits each and no delimiter between them (common form for 218RFC 822 date headers). 219.It Cm %+ 220is replaced by national representation of the date and time 221(the format is similar to that produced by 222.Xr date 1 ) . 223.It Cm %-* 224GNU libc extension. 225Do not do any padding when performing numerical outputs. 226.It Cm %_* 227GNU libc extension. 228Explicitly specify space for padding. 229.It Cm %0* 230GNU libc extension. 231Explicitly specify zero for padding. 232.It Cm %% 233is replaced by 234.Ql % . 235.El 236.Sh SEE ALSO 237.Xr date 1 , 238.Xr printf 1 , 239.Xr ctime 3 , 240.Xr printf 3 , 241.Xr strptime 3 , 242.Xr wcsftime 3 243.Sh STANDARDS 244The 245.Fn strftime 246function 247conforms to 248.St -isoC 249with a lot of extensions including 250.Ql \&%C , 251.Ql \&%D , 252.Ql %E* , 253.Ql %e , 254.Ql %G , 255.Ql %g , 256.Ql %h , 257.Ql %k , 258.Ql %l , 259.Ql %n , 260.Ql %O* , 261.Ql \&%R , 262.Ql %r , 263.Ql %s , 264.Ql \&%T , 265.Ql %t , 266.Ql %u , 267.Ql \&%V , 268.Ql %z , 269.Ql %+ . 270.Pp 271The peculiar week number and year in the replacements of 272.Ql %G , 273.Ql %g 274and 275.Ql \&%V 276are defined in 277.St -iso8601 . 278The 279.Fn strftime_l 280function conforms to 281.St -p1003.1-2008 . 282.Sh BUGS 283There is no conversion specification for the phase of the moon. 284.Pp 285The 286.Fn strftime 287function does not correctly handle multibyte characters in the 288.Fa format 289argument. 290