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