strftime.3 (6954B)
1 .TH STRFTIME 3 2 .SH NAME 3 strftime - formats the broken-down time according to specified format 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 places characters into the array pointed to by 17 .I s 18 as controlled by the string pointed to by 19 .IR format . 20 21 The 22 .I format 23 shall be a multibyte character sequence, 24 beginning and ending in its initial shift state. 25 The 26 .I format 27 shall consist of zero or more conversion specifiers and 28 ordinary characters. 29 A conversion specifier consists of a % character, 30 possibly followed by an E or O modifier character, 31 followed by a character that determines the behavior of the conversion 32 specifier. 33 All ordinary characters 34 (including the terminating null character) are copied unchanged into the 35 array. 36 No more than 37 .I maxsize 38 characters are placed into the array. 39 40 The format specification is a null-terminated string and 41 shall contain special character sequences, called conversion specifiers, 42 which get replaced with the appropriate characters as described in the 43 following list: 44 .TP 45 .B %a 46 The abbreviated name of the day of the week according to the current 47 locale. 48 .TP 49 .B %A 50 THe full name of the day of the week according to the current locale. 51 .TP 52 .B %b 53 The abbreviated name of the month according to the current locale. 54 .TP 55 .B %B 56 The full name of the month according to the current locale. 57 .TP 58 .B %c 59 The preferred date and time representation for the current locale. 60 .TP 61 .B %C 62 The decimal number representing the year divided by 100 and truncated 63 to an integer (century number). 64 .TP 65 .B %d 66 The day of the month as a decimal number between 01 and 31. 67 .TP 68 .B %D 69 Equivalent to "%m/%d/%y" 70 .TP 71 .B %e 72 The day of the month as a decimal number between 0 and 31; 73 a single digit is preceded by a space. 74 .TP 75 .B %F 76 Equivalent to "%y-%m-%d" 77 (the ISO 8601 date format). 78 .TP 79 .B %G 80 The ISO 8601 week-based-year with century as a decimal number. 81 The 4-digit year corresponding to the ISO week number. (Calculated 82 from 83 .BR tm_year , 84 .BR tm_yday , 85 and 86 .BR tm_wday ) 87 .TP 88 .B %g 89 Like 90 .B %G 91 but without century, that is, with a 2-digit year (00-99). 92 (Calculated from 93 .BR tm_year , 94 .BR tm_yday , 95 and 96 .BR tm_wday ) 97 .TP 98 .B %h 99 Equivalent to 100 .BR %b . 101 (Calculated from 102 .BR tm_mon ) 103 .TP 104 .B %H 105 The hour as a decimal number using a 24-hour clock between 106 00 and 23. 107 (Calculated from 108 .BR tm_hour ) 109 .TP 110 .B %I 111 The hour as a decimal number using a 12-hour clock between 01 and 12 112 (Calculated from 113 .BR tm_hour ) 114 .TP 115 .B %j 116 The day of the year as a decimal number between 001 and 366. 117 (Calculated from 118 .BR tm_yday ) 119 .TP 120 .B %m 121 The month as a decimal number between 01 and 12 122 (Calculated from 123 .BR tm_mon ) 124 .TP 125 .B %M 126 The minute as a decimal number between 00 and 59 127 .TP 128 .B %n 129 A newline character. 130 .TP 131 .B %p 132 Either "AM" or "PM" according to the given time value. 133 (Calculated from 134 .BR tm_hour ) 135 .B %r 136 The locale's 12-hour clock time. 137 .TP 138 .B %R 139 The time in 24-hour notation (%H:%M). 140 .TP 141 .B %S 142 The second as a decimal number between 00 and 60. 143 (Calculated from 144 .BR tm_sec ). 145 .TP 146 .B %t 147 A tab character. 148 .TP 149 .B %T 150 The time in 24-hour notation (%H:%M:%S). 151 .TP 152 .B %u 153 The day of the week (ISO 8601) as a decimal between 1 and 7, 154 Monday being 1. 155 (Calculated from 156 .BR tm_wday ) 157 .TP 158 .B %U 159 The week number of the current year as a decimal number 160 between 00 and 53, 161 starting with the first Sunday as the first day of week 01. (Calculated from 162 .BR tm_year , 163 .BR tm_wday , 164 .BR tm_yday ) 165 .TP 166 .B %V 167 The ISO 8601 week (see NOTES) number of the current year as a decimal number 168 between 01 and 53, 169 where week 1 is the first week that has at least 4 days in the new year. 170 .TP 171 .B %w 172 The day of the week as a decimal between 0 and 6, 173 Sunday being 0. 174 .TP 175 .B %W 176 The week number of the current year as a decimal number 177 between 00 and 53, 178 starting with the first Monday as the first day of week 01. 179 (Calculated from 180 .B tm_yday 181 and 182 .BR tm_wday ). 183 .TP 184 .B %x 185 The preferred date representation for the current locale without the 186 time. 187 .TP 188 .B %X 189 The preferred time representation for the current locale without the 190 date. 191 .TP 192 .B %y 193 The year as a decimal number without a century between 00 and 99. 194 .TP 195 .B %Y 196 The year as a decimal number including the century. 197 .TP 198 .B %z 199 The +hhmm or -hhmm numeric timezone 200 (that is, the hour and minute offset from UTC in ISO 8601 format). 201 .TP 202 .B %Z 203 The timezone name or abbreviation. 204 .TP 205 .B %% 206 This is replaced with %. 207 .P 208 Some conversion specifiers can be modified by the inclusion of an 209 .B E 210 or 211 .B O 212 modifier character to indicate an alternative format or specification. 213 If the alternative format or character doesn't exist for the current locale, 214 the modifier is ignored. 215 216 The C Standard mentions the following specifiers: 217 .BR %Ec , 218 .BR %EC , 219 .BR %Ex , 220 .BR %EX , 221 .BR %Ey , 222 .BR %EY , 223 .BR %Od , 224 .BR %Oe , 225 .BR %OH , 226 .BR %OI , 227 .BR %Om , 228 .BR %OM , 229 .BR %OS , 230 .BR %Ou , 231 .BR %OU , 232 .BR %OV , 233 .BR %Ow , 234 .BR %OW , 235 .BR %Oy , 236 where the effect of the 237 .B O 238 modifier is to use 239 alternative numeric symbols, and that of the 240 .B E 241 modifier is to use a locale-dependent alternative representation. 242 243 In the "C" locale, the E and O modifiers are ignored and the 244 replacement strings for the following specifiers are: 245 .TP 246 .B %a 247 the first three characters of %A 248 .TP 249 .B %A 250 one of Sunday ,Monday, ..., Saturday 251 .TP 252 .B %b 253 the first three characters of %B 254 .TP 255 .B %B 256 one of January, February, ..., December 257 .TP 258 .B %c 259 equivalent to %a %b %e %T %Y 260 .TP 261 .B %p 262 one of AM or PM 263 .TP 264 .B %r 265 equivalent to %I:%M:%S %p 266 .TP 267 .B %x 268 equivalent to %m/%d/%y 269 .TP 270 .B %X 271 equivalent to %T 272 .TP 273 .B %Z 274 The timezone name or abbreviation. 275 .SH RETURN VALUE 276 If the total number of resulting characters 277 including the terminating null character doesn't exceed 278 .IR maxsize , 279 then 280 .I strftime 281 function returns the number of characters 282 placed into the array pointed to by 283 .I s 284 not including the terminating null character. Otherwise, zero is 285 returned and the contents of the array are indeterminate. 286 .SH NOTES 287 In the ISO 8601 week-based year, weeks begin on a Monday and week 1 288 of the year is the week that includes January 4th, which also includes 289 the first Thursday of the year, and is also the first week that 290 contains at least four days in the year. As mentioned above, 291 .B %g, %G, 292 and 293 .B %V 294 are dependent on ISO 8601 week-based year, and the following examples 295 are provided for illustrative purposes: 296 297 If the first Monday of January is the 2nd, 3rd, or 4th, 298 the preceding days are part of the last week of the preceding year; 299 thus, for Saturday 2nd January 1999, 300 .B %G 301 is replaced by 1998 and 302 .B %V 303 is replaced with 53. Similarly, 304 if December 29th, 30th or 31st is a Monday, 305 it and following days are part of week 1 and hence, 306 for Tuesday 30th December 1997, 307 .B %G 308 is replaced by 1998 and 309 .B %V 310 is replaced with 01. 311 .SH STANDARDS 312 ISO/IEC 9899:1999 Section 7.23.3.5 Paragraph 1,2,3,4,5,6,7 313 .SH SEE ALSO 314 .BR time.h (3)