strftime.man (5821B)
1 .TH STRFTIME 3 scc\-VERSION 2 .SH NAME 3 strftime - format a broken-down time value into a string 4 .SH SYNOPSIS 5 #include <time.h> 6 7 .nf 8 size_t strftime(char * restrict s, 9 size_t maxsize, 10 const char * restrict format, 11 const struct tm * restrict timeptr); 12 .fi 13 .SH DESCRIPTION 14 The 15 .BR strftime () 16 function writes characters into the array pointed to by 17 .I s 18 under control of the string pointed to by 19 .IR format . 20 21 The 22 .I format 23 string is a multibyte character sequence that begins and ends 24 in its initial shift state. 25 It consists of zero or more conversion specifiers 26 interspersed with ordinary characters. 27 Each conversion specifier begins with a 28 .B % 29 character, optionally followed by an 30 .B E 31 or 32 .B O 33 modifier, and ends with a character that determines what is substituted. 34 Ordinary characters, including the terminating null byte, 35 are copied to the output without modification. 36 No more than 37 .I maxsize 38 characters are placed into the array. 39 40 The following conversion specifiers are recognized: 41 .TP 42 .B %a 43 The abbreviated weekday name for the current locale. 44 .TP 45 .B %A 46 The full weekday name for the current locale. 47 .TP 48 .B %b 49 The abbreviated month name for the current locale. 50 .TP 51 .B %B 52 The full month name for the current locale. 53 .TP 54 .B %c 55 The preferred date and time representation for the current locale. 56 .TP 57 .B %C 58 The year divided by 100, truncated to an integer (the century). 59 .TP 60 .B %d 61 The day of the month as a two-digit decimal number (01 to 31). 62 .TP 63 .B %D 64 Equivalent to "%m/%d/%y". 65 .TP 66 .B %e 67 The day of the month as a decimal number; single digits are padded with a space. 68 .TP 69 .B %F 70 Equivalent to "%Y-%m-%d" (ISO 8601 date format). 71 .TP 72 .B %G 73 The ISO 8601 week-based year, including the century. 74 (Derived from 75 .BR tm_year , 76 .BR tm_yday , 77 and 78 .BR tm_wday .) 79 .TP 80 .B %g 81 Like 82 .B %G 83 but without the century (two-digit year, 00 to 99). 84 (Derived from 85 .BR tm_year , 86 .BR tm_yday , 87 and 88 .BR tm_wday .) 89 .TP 90 .B %h 91 Equivalent to 92 .BR %b . 93 (Derived from 94 .BR tm_mon .) 95 .TP 96 .B %H 97 The hour on a 24-hour clock as a two-digit decimal number (00 to 23). 98 (Derived from 99 .BR tm_hour .) 100 .TP 101 .B %I 102 The hour on a 12-hour clock as a two-digit decimal number (01 to 12). 103 (Derived from 104 .BR tm_hour .) 105 .TP 106 .B %j 107 The day of the year as a three-digit decimal number (001 to 366). 108 (Derived from 109 .BR tm_yday .) 110 .TP 111 .B %m 112 The month as a two-digit decimal number (01 to 12). 113 (Derived from 114 .BR tm_mon .) 115 .TP 116 .B %M 117 The minute as a two-digit decimal number (00 to 59). 118 .TP 119 .B %n 120 A newline character. 121 .TP 122 .B %p 123 Either "AM" or "PM" according to the time of day. 124 (Derived from 125 .BR tm_hour .) 126 .TP 127 .B %r 128 The locale's 12-hour clock time. 129 .TP 130 .B %R 131 The time in 24-hour notation (%H:%M). 132 .TP 133 .B %S 134 The second as a two-digit decimal number (00 to 60). 135 (Derived from 136 .BR tm_sec .) 137 .TP 138 .B %t 139 A tab character. 140 .TP 141 .B %T 142 The time in 24-hour notation (%H:%M:%S). 143 .TP 144 .B %u 145 The weekday as a decimal number per ISO 8601 (1 to 7, Monday = 1). 146 (Derived from 147 .BR tm_wday .) 148 .TP 149 .B %U 150 The week number of the year as a two-digit decimal (00 to 53), 151 counting from the first Sunday as day 1 of week 1. 152 (Derived from 153 .BR tm_year , 154 .BR tm_wday , 155 .BR tm_yday .) 156 .TP 157 .B %V 158 The ISO 8601 week number of the year (01 to 53), 159 where week 1 is the first week containing at least four days of the new year. 160 .TP 161 .B %w 162 The weekday as a decimal number (0 to 6, Sunday = 0). 163 .TP 164 .B %W 165 The week number of the year as a two-digit decimal (00 to 53), 166 counting from the first Monday as day 1 of week 1. 167 (Derived from 168 .B tm_yday 169 and 170 .BR tm_wday .) 171 .TP 172 .B %x 173 The preferred date representation for the current locale, without the time. 174 .TP 175 .B %X 176 The preferred time representation for the current locale, without the date. 177 .TP 178 .B %y 179 The year without the century (00 to 99). 180 .TP 181 .B %Y 182 The year including the century. 183 .TP 184 .B %z 185 The UTC offset as +hhmm or -hhmm (ISO 8601 format). 186 .TP 187 .B %Z 188 The timezone name or abbreviation. 189 .TP 190 .B %% 191 A literal percent sign. 192 .P 193 The 194 .B E 195 and 196 .B O 197 modifier characters may precede certain conversion specifiers 198 to request an alternative locale-specific representation. 199 When no alternative exists, the modifier is ignored. 200 201 The C standard recognizes the following modified specifiers: 202 .BR %Ec , 203 .BR %EC , 204 .BR %Ex , 205 .BR %EX , 206 .BR %Ey , 207 .BR %EY , 208 .BR %Od , 209 .BR %Oe , 210 .BR %OH , 211 .BR %OI , 212 .BR %Om , 213 .BR %OM , 214 .BR %OS , 215 .BR %Ou , 216 .BR %OU , 217 .BR %OV , 218 .BR %Ow , 219 .BR %OW , 220 .BR %Oy . 221 The 222 .B O 223 modifier requests locale alternative numeric symbols; 224 the 225 .B E 226 modifier requests a locale-dependent alternative representation. 227 228 In the "C" locale, both modifiers are ignored and 229 the following substitutions apply: 230 .TP 231 .B %a 232 the first three characters of %A 233 .TP 234 .B %A 235 one of Sunday, Monday, ..., Saturday 236 .TP 237 .B %b 238 the first three characters of %B 239 .TP 240 .B %B 241 one of January, February, ..., December 242 .TP 243 .B %c 244 equivalent to %a %b %e %T %Y 245 .TP 246 .B %p 247 one of AM or PM 248 .TP 249 .B %r 250 equivalent to %I:%M:%S %p 251 .TP 252 .B %x 253 equivalent to %m/%d/%y 254 .TP 255 .B %X 256 equivalent to %T 257 .TP 258 .B %Z 259 the timezone name or abbreviation 260 .SH RETURN VALUE 261 When the formatted result, including the terminating null byte, 262 fits within 263 .I maxsize 264 characters, 265 .B strftime 266 returns the number of characters written, excluding the null byte. 267 If the result does not fit, zero is returned and the contents 268 of the array are unspecified. 269 .SH NOTES 270 ISO 8601 week-based years begin on Monday, with week 1 defined as 271 the week containing January 4th (equivalently, the first week with 272 at least four days in the new year, or the week containing the 273 first Thursday of the year). 274 The specifiers 275 .BR %g , 276 .BR %G , 277 and 278 .B %V 279 follow this convention. For example, Saturday January 2nd 1999 280 falls in week 53 of 1998 (%G = 1998, %V = 53); 281 Tuesday December 30th 1997 falls in week 1 of 1998 (%G = 1998, %V = 01). 282 .SH STANDARDS 283 ISO/IEC 9899:1999 Section 7.23.3.5 Paragraph 1,2,3,4,5,6,7 284 .SH SEE ALSO 285 .BR time.h (3)