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