logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

strftime.3p (28556B)


  1. '\" et
  2. .TH STRFTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. strftime,
  12. strftime_l
  13. \(em convert date and time to a string
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <time.h>
  18. .P
  19. size_t strftime(char *restrict \fIs\fP, size_t \fImaxsize\fP,
  20. const char *restrict \fIformat\fP, const struct tm *restrict \fItimeptr\fP);
  21. size_t strftime_l(char *restrict \fIs\fP, size_t \fImaxsize\fP,
  22. const char *restrict \fIformat\fP, const struct tm *restrict \fItimeptr\fP,
  23. locale_t \fIlocale\fP);
  24. .fi
  25. .SH DESCRIPTION
  26. For
  27. \fIstrftime\fR():
  28. The functionality described on this reference page is aligned with the
  29. ISO\ C standard. Any conflict between the requirements described here and the
  30. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  31. .P
  32. The
  33. \fIstrftime\fR()
  34. function shall place bytes into the array pointed to by
  35. .IR s
  36. as controlled by the string pointed to by
  37. .IR format .
  38. The format is a character string, beginning and ending in its initial
  39. shift state, if any. The format string consists of zero or more conversion
  40. specifications and ordinary characters.
  41. .P
  42. Each conversion specification is introduced by the
  43. .BR '%'
  44. character after which the following appear in sequence:
  45. .IP " *" 4
  46. An optional flag:
  47. .RS 4
  48. .IP "\fR0\fR" 6
  49. The zero character (\c
  50. .BR '0' ),
  51. which specifies that the character used as the padding character is
  52. .BR '0' ,
  53. .IP "\fR+\fR" 6
  54. The
  55. <plus-sign>
  56. character (\c
  57. .BR '+' ),
  58. which specifies that the character used as the padding character is
  59. .BR '0' ,
  60. and that if and only if the field being produced consumes more than four
  61. bytes to represent a year (for
  62. .BR %F ,
  63. .BR %G ,
  64. or
  65. .BR %Y )
  66. or more than two bytes to represent the year divided by 100 (for
  67. .BR %C )
  68. then a leading
  69. <plus-sign>
  70. character shall be included if the year being processed is greater than
  71. or equal to zero or a leading
  72. <hyphen-minus>
  73. character (\c
  74. .BR '\-' )
  75. shall be included if the year is less than zero.
  76. .P
  77. The default padding character is unspecified.
  78. .RE
  79. .IP " *" 4
  80. An optional minimum field width. If the converted value, including
  81. any leading
  82. .BR '+'
  83. or
  84. .BR '\-'
  85. sign, has fewer bytes than the minimum field width and the padding
  86. character is not the NUL character, the output shall be padded on the left
  87. (after any leading
  88. .BR '+'
  89. or
  90. .BR '\-'
  91. sign) with the padding character.
  92. .IP " *" 4
  93. An optional
  94. .BR E
  95. or
  96. .BR O
  97. modifier.
  98. .IP " *" 4
  99. A terminating conversion specifier character that indicates the type of
  100. conversion to be applied.
  101. .P
  102. The results are unspecified if more than one flag character is specified,
  103. a flag character is specified without a minimum field width; a minimum
  104. field width is specified without a flag character; a modifier is specified
  105. with a flag or with a minimum field width; or if a minimum field width
  106. is specified for any conversion specifier other than
  107. .BR C ,
  108. .BR F ,
  109. .BR G ,
  110. or
  111. .BR Y .
  112. .P
  113. All ordinary characters (including the terminating NUL character)
  114. are copied unchanged into the array. If copying takes place between
  115. objects that overlap, the behavior is undefined. No more than maxsize
  116. bytes are placed into the array. Each conversion specifier is replaced by
  117. appropriate characters as described in the following list. The appropriate
  118. characters are determined using the
  119. .IR LC_TIME
  120. category of the current locale and by the values of zero or more members
  121. of the broken-down time structure pointed to by
  122. .IR timeptr ,
  123. as specified in brackets in the description. If any of the specified
  124. values are outside the normal range, the characters stored are
  125. unspecified.
  126. .P
  127. The
  128. \fIstrftime_l\fR()
  129. function shall be equivalent to the
  130. \fIstrftime\fR()
  131. function, except that the locale data used is from the
  132. locale represented by
  133. .IR locale .
  134. .P
  135. Local timezone information is used as though
  136. \fIstrftime\fR()
  137. called
  138. \fItzset\fR().
  139. .P
  140. The following conversion specifiers shall be supported:
  141. .IP "\fRa\fR" 8
  142. Replaced by the locale's abbreviated weekday name. [\c
  143. .IR tm_wday ]
  144. .IP "\fRA\fR" 8
  145. Replaced by the locale's full weekday name. [\c
  146. .IR tm_wday ]
  147. .IP "\fRb\fR" 8
  148. Replaced by the locale's abbreviated month name. [\c
  149. .IR tm_mon ]
  150. .IP "\fRB\fR" 8
  151. Replaced by the locale's full month name. [\c
  152. .IR tm_mon ]
  153. .IP "\fRc\fR" 8
  154. Replaced by the locale's appropriate date and time representation.
  155. (See the Base Definitions volume of POSIX.1\(hy2017,
  156. .IR <time.h> .)
  157. .IP "\fRC\fR" 8
  158. Replaced by the year divided by 100 and truncated to an integer,
  159. as a decimal number. [\c
  160. .IR tm_year ]
  161. .RS 8
  162. .P
  163. If a minimum field width is not specified, the number of characters
  164. placed into the array pointed to by
  165. .IR s
  166. will be the number of digits in the year divided by 100 or two, whichever
  167. is greater.
  168. If a minimum field width is specified, the number of characters placed
  169. into the array pointed to by
  170. .IR s
  171. will be the number of digits in the year divided by 100 or the minimum
  172. field width, whichever is greater.
  173. .RE
  174. .IP "\fRd\fR" 8
  175. Replaced by the day of the month as a decimal number [01,31]. [\c
  176. .IR tm_mday ]
  177. .IP "\fRD\fR" 8
  178. Equivalent to
  179. .BR %m /\c
  180. .BR %d /\c
  181. .BR %y .
  182. [\c
  183. .IR tm_mon ,
  184. .IR tm_mday ,
  185. .IR tm_year ]
  186. .IP "\fRe\fR" 8
  187. Replaced by the day of the month as a decimal number [1,31];
  188. a single digit is preceded by a space. [\c
  189. .IR tm_mday ]
  190. .IP "\fRF\fR" 8
  191. Equivalent to %\*!+4\*?Y-%m-%d if no flag and no minimum field width
  192. are specified. [\c
  193. .IR tm_year ,
  194. .IR tm_mon ,
  195. .IR tm_mday ]
  196. .RS 8
  197. .P
  198. If a minimum field width of
  199. .IR x
  200. is specified, the year shall be output as if by the
  201. .BR Y
  202. specifier (described below) with whatever flag was given and a minimum
  203. field width of
  204. .IR x \-6.
  205. If
  206. .IR x
  207. is less than 6, the behavior shall be as if
  208. .IR x
  209. equalled 6.
  210. .P
  211. If the minimum field width is specified to be 10, and the year is
  212. four digits long, then the output string produced will match the
  213. ISO\ 8601:\|2004 standard subclause 4.1.2.2 complete representation, extended format date
  214. representation of a specific day. If a + flag is specified, a minimum
  215. field width of
  216. .IR x
  217. is specified, and
  218. .IR x \-7
  219. bytes are sufficient to hold the digits of the year (not including any
  220. needed sign character), then the output will match the ISO\ 8601:\|2004 standard subclause
  221. 4.1.2.4 complete representation, expanded format date representation of
  222. a specific day.
  223. .RE
  224. .IP "\fRg\fR" 8
  225. Replaced by the last 2 digits of the week-based year (see below)
  226. as a decimal number [00,99]. [\c
  227. .IR tm_year ,
  228. .IR tm_wday ,
  229. .IR tm_yday ]
  230. .IP "\fRG\fR" 8
  231. Replaced by the week-based year (see below) as a decimal number
  232. (for example, 1977). [\c
  233. .IR tm_year ,
  234. .IR tm_wday ,
  235. .IR tm_yday ]
  236. .RS 8
  237. .P
  238. If a minimum field width is specified, the number of characters placed
  239. into the array pointed to by
  240. .IR s
  241. will be the number of digits and leading sign characters (if any) in
  242. the year, or the minimum field width, whichever is greater.
  243. .RE
  244. .IP "\fRh\fR" 8
  245. Equivalent to
  246. .BR %b .
  247. [\c
  248. .IR tm_mon ]
  249. .IP "\fRH\fR" 8
  250. Replaced by the hour (24-hour clock) as a decimal number [00,23]. [\c
  251. .IR tm_hour ]
  252. .IP "\fRI\fR" 8
  253. Replaced by the hour (12-hour clock) as a decimal number [01,12]. [\c
  254. .IR tm_hour ]
  255. .IP "\fRj\fR" 8
  256. Replaced by the day of the year as a decimal number [001,366]. [\c
  257. .IR tm_yday ]
  258. .IP "\fRm\fR" 8
  259. Replaced by the month as a decimal number [01,12]. [\c
  260. .IR tm_mon ]
  261. .IP "\fRM\fR" 8
  262. Replaced by the minute as a decimal number [00,59]. [\c
  263. .IR tm_min ]
  264. .IP "\fRn\fR" 8
  265. Replaced by a
  266. <newline>.
  267. .IP "\fRp\fR" 8
  268. Replaced by the locale's equivalent of either a.m. or p.m. [\c
  269. .IR tm_hour ]
  270. .IP "\fRr\fR" 8
  271. Replaced by the time in a.m. and p.m. notation;
  272. in the POSIX locale this shall be equivalent to
  273. .BR %I :\c
  274. .BR %M :\c
  275. .BR %S
  276. .BR %p .
  277. [\c
  278. .IR tm_hour ,
  279. .IR tm_min ,
  280. .IR tm_sec ]
  281. .IP "\fRR\fR" 8
  282. Replaced by the time in 24-hour notation (\c
  283. .BR %H :\c
  284. .BR %M ).
  285. [\c
  286. .IR tm_hour ,
  287. .IR tm_min ]
  288. .IP "\fRS\fR" 8
  289. Replaced by the second as a decimal number [00,60]. [\c
  290. .IR tm_sec ]
  291. .IP "\fRt\fR" 8
  292. Replaced by a
  293. <tab>.
  294. .IP "\fRT\fR" 8
  295. Replaced by the time (\c
  296. .BR %H :\c
  297. .BR %M :\c
  298. .BR %S ).
  299. [\c
  300. .IR tm_hour ,
  301. .IR tm_min ,
  302. .IR tm_sec ]
  303. .IP "\fRu\fR" 8
  304. Replaced by the weekday as a decimal number [1,7], with 1 representing
  305. Monday. [\c
  306. .IR tm_wday ]
  307. .IP "\fRU\fR" 8
  308. Replaced by the week number of the year as a decimal number [00,53].
  309. The first Sunday of January is the first day of week 1; days in the
  310. new year before this are in week 0. [\c
  311. .IR tm_year ,
  312. .IR tm_wday ,
  313. .IR tm_yday ]
  314. .IP "\fRV\fR" 8
  315. Replaced by the week number of the year (Monday as the first day of the
  316. week) as a decimal number [01,53]. If the week containing 1 January
  317. has four or more days in the new year, then it is considered week 1.
  318. Otherwise, it is the last week of the previous year, and the next week
  319. is week 1. Both January 4th and the first Thursday of January are
  320. always in week 1. [\c
  321. .IR tm_year ,
  322. .IR tm_wday ,
  323. .IR tm_yday ]
  324. .IP "\fRw\fR" 8
  325. Replaced by the weekday as a decimal number [0,6], with 0 representing
  326. Sunday. [\c
  327. .IR tm_wday ]
  328. .IP "\fRW\fR" 8
  329. Replaced by the week number of the year as a decimal number [00,53].
  330. The first Monday of January is the first day of week 1; days in the new
  331. year before this are in week 0. [\c
  332. .IR tm_year ,
  333. .IR tm_wday ,
  334. .IR tm_yday ]
  335. .IP "\fRx\fR" 8
  336. Replaced by the locale's appropriate date representation. (See
  337. the Base Definitions volume of POSIX.1\(hy2017,
  338. .IR <time.h> .)
  339. .IP "\fRX\fR" 8
  340. Replaced by the locale's appropriate time representation. (See
  341. the Base Definitions volume of POSIX.1\(hy2017,
  342. .IR <time.h> .)
  343. .IP "\fRy\fR" 8
  344. Replaced by the last two digits of the year as a decimal number
  345. [00,99]. [\c
  346. .IR tm_year ]
  347. .IP "\fRY\fR" 8
  348. Replaced by the year as a decimal number (for example, 1997). [\c
  349. .IR tm_year ]
  350. .RS 8
  351. .P
  352. If a minimum field width is specified, the number of characters placed
  353. into the array pointed to by
  354. .IR s
  355. will be the number of digits and leading sign characters (if any) in
  356. the year, or the minimum field width, whichever is greater.
  357. .RE
  358. .IP "\fRz\fR" 8
  359. Replaced by the offset from UTC in the ISO\ 8601:\|2004 standard format (\c
  360. .BR +hhmm
  361. or
  362. .BR \-hhmm ),
  363. or by no characters if no timezone is determinable. For example,
  364. .BR \(dq-0430\(dq
  365. means 4 hours 30 minutes behind UTC (west of Greenwich).
  366. If
  367. .IR tm_isdst
  368. is zero, the standard time offset is used. If
  369. .IR tm_isdst
  370. is greater than zero, the daylight savings time offset is used. If
  371. .IR tm_isdst
  372. is negative, no characters are returned.
  373. [\c
  374. .IR tm_isdst ]
  375. .IP "\fRZ\fR" 8
  376. Replaced by the timezone name or abbreviation, or by no bytes if no
  377. timezone information exists. [\c
  378. .IR tm_isdst ]
  379. .IP "\fR%\fR" 8
  380. Replaced by
  381. .BR % .
  382. .P
  383. If a conversion specification does not correspond to any of the above,
  384. the behavior is undefined.
  385. .P
  386. If a
  387. .BR "struct tm"
  388. broken-down time structure is created by
  389. \fIlocaltime\fR()
  390. or
  391. \fIlocaltime_r\fR(),
  392. or modified by
  393. \fImktime\fR(),
  394. and the value of
  395. .IR TZ
  396. is subsequently modified, the results of the
  397. .BR %Z
  398. and
  399. .BR %z
  400. \fIstrftime\fR()
  401. conversion specifiers are undefined, when
  402. \fIstrftime\fR()
  403. is called with such a broken-down time structure.
  404. .P
  405. If a
  406. .BR "struct tm"
  407. broken-down time structure is created or modified by
  408. \fIgmtime\fR()
  409. or
  410. \fIgmtime_r\fR(),
  411. it is unspecified whether the result of the
  412. .BR %Z
  413. and
  414. .BR %z
  415. conversion specifiers shall refer to UTC or the current local timezone,
  416. when
  417. \fIstrftime\fR()
  418. is called with such a broken-down time structure.
  419. .SS "Modified Conversion Specifiers"
  420. .P
  421. Some conversion specifiers can be modified by the
  422. .BR E
  423. or
  424. .BR O
  425. modifier characters to indicate that an alternative format or
  426. specification should be used rather than the one normally used by the
  427. unmodified conversion specifier. If the alternative format or
  428. specification does not exist for the current locale (see ERA in the Base Definitions volume of POSIX.1\(hy2017,
  429. .IR "Section 7.3.5" ", " "LC_TIME"),
  430. the behavior shall be as if the unmodified conversion
  431. specification were used.
  432. .IP "\fR%Ec\fR" 8
  433. Replaced by the locale's alternative appropriate date and time
  434. representation.
  435. .IP "\fR%EC\fR" 8
  436. Replaced by the name of the base year (period) in the locale's
  437. alternative representation.
  438. .IP "\fR%Ex\fR" 8
  439. Replaced by the locale's alternative date representation.
  440. .IP "\fR%EX\fR" 8
  441. Replaced by the locale's alternative time representation.
  442. .IP "\fR%Ey\fR" 8
  443. Replaced by the offset from
  444. .BR %EC
  445. (year only) in the locale's alternative representation.
  446. .IP "\fR%EY\fR" 8
  447. Replaced by the full alternative year representation.
  448. .IP "\fR%Od\fR" 8
  449. Replaced by the day of the month, using the locale's alternative
  450. numeric symbols, filled as needed with leading zeros if there is any
  451. alternative symbol for zero; otherwise, with leading
  452. <space>
  453. characters.
  454. .IP "\fR%Oe\fR" 8
  455. Replaced by the day of the month, using the locale's alternative
  456. numeric symbols, filled as needed with leading
  457. <space>
  458. characters.
  459. .IP "\fR%OH\fR" 8
  460. Replaced by the hour (24-hour clock) using the locale's alternative
  461. numeric symbols.
  462. .IP "\fR%OI\fR" 8
  463. Replaced by the hour (12-hour clock) using the locale's alternative
  464. numeric symbols.
  465. .IP "\fR%Om\fR" 8
  466. Replaced by the month using the locale's alternative numeric symbols.
  467. .IP "\fR%OM\fR" 8
  468. Replaced by the minutes using the locale's alternative numeric symbols.
  469. .IP "\fR%OS\fR" 8
  470. Replaced by the seconds using the locale's alternative numeric symbols.
  471. .IP "\fR%Ou\fR" 8
  472. Replaced by the weekday as a number in the locale's alternative
  473. representation (Monday=1).
  474. .IP "\fR%OU\fR" 8
  475. Replaced by the week number of the year (Sunday as the first day of the
  476. week, rules corresponding to
  477. .BR %U )
  478. using the locale's alternative numeric symbols.
  479. .IP "\fR%OV\fR" 8
  480. Replaced by the week number of the year (Monday as the first day of the
  481. week, rules corresponding to
  482. .BR %V )
  483. using the locale's alternative numeric symbols.
  484. .IP "\fR%Ow\fR" 8
  485. Replaced by the number of the weekday (Sunday=0) using the locale's
  486. alternative numeric symbols.
  487. .IP "\fR%OW\fR" 8
  488. Replaced by the week number of the year (Monday as the first day of the
  489. week) using the locale's alternative numeric symbols.
  490. .IP "\fR%Oy\fR" 8
  491. Replaced by the year (offset from
  492. .BR %C )
  493. using the locale's alternative numeric symbols.
  494. .P
  495. .BR %g ,
  496. .BR %G ,
  497. and
  498. .BR %V
  499. give values according to the ISO\ 8601:\|2004 standard week-based year. In this system,
  500. weeks begin on a Monday and week 1 of the year is the week that
  501. includes January 4th, which is also the week that includes the first
  502. Thursday of the year, and is also the first week that contains at least
  503. four days in the year. If the first Monday of January is the 2nd, 3rd,
  504. or 4th, the preceding days are part of the last week of the preceding
  505. year; thus, for Saturday 2nd January 1999,
  506. .BR %G
  507. is replaced by 1998 and
  508. .BR %V
  509. is replaced by 53. If December 29th, 30th, or 31st is a Monday, it and
  510. any following days are part of week 1 of the following year. Thus, for
  511. Tuesday 30th December 1997,
  512. .BR %G
  513. is replaced by 1998 and
  514. .BR %V
  515. is replaced by 01.
  516. .P
  517. If a conversion specifier is not one of the above, the behavior is
  518. undefined.
  519. .P
  520. The behavior is undefined if the
  521. .IR locale
  522. argument to
  523. \fIstrftime_l\fR()
  524. is the special locale object LC_GLOBAL_LOCALE or is not a valid locale
  525. object handle.
  526. .SH "RETURN VALUE"
  527. If the total number of resulting bytes including the terminating null
  528. byte is not more than
  529. .IR maxsize ,
  530. these functions shall return the number of bytes placed into the array
  531. pointed to by
  532. .IR s ,
  533. not including the terminating NUL character. Otherwise, 0 shall be returned
  534. and the contents of the array are unspecified.
  535. .SH ERRORS
  536. No errors are defined.
  537. .LP
  538. .IR "The following sections are informative."
  539. .SH EXAMPLES
  540. .SS "Getting a Localized Date String"
  541. .P
  542. The following example first sets the locale to the user's default. The
  543. locale information will be used in the
  544. \fInl_langinfo\fR()
  545. and
  546. \fIstrftime\fR()
  547. functions. The
  548. \fInl_langinfo\fR()
  549. function returns the localized date string which specifies how the date
  550. is laid out. The
  551. \fIstrftime\fR()
  552. function takes this information and, using the
  553. .BR tm
  554. structure for values, places the date and time information into
  555. .IR datestring .
  556. .sp
  557. .RS 4
  558. .nf
  559. #include <time.h>
  560. #include <locale.h>
  561. #include <langinfo.h>
  562. \&...
  563. struct tm *tm;
  564. char datestring[256];
  565. \&...
  566. setlocale (LC_ALL, "");
  567. \&...
  568. strftime (datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm);
  569. \&...
  570. .fi
  571. .P
  572. .RE
  573. .SH "APPLICATION USAGE"
  574. The range of values for
  575. .BR %S
  576. is [00,60] rather than [00,59] to allow for the occasional leap
  577. second.
  578. .P
  579. Some of the conversion specifications are duplicates of others. They
  580. are included for compatibility with
  581. \fInl_cxtime\fR()
  582. and
  583. \fInl_ascxtime\fR(),
  584. which were published in Issue 2.
  585. .P
  586. The
  587. .BR %C ,
  588. .BR %F ,
  589. .BR %G ,
  590. and
  591. .BR %Y
  592. format specifiers in
  593. \fIstrftime\fR()
  594. always print full values, but the
  595. \fIstrptime\fR()
  596. .BR %C ,
  597. .BR %F ,
  598. and
  599. .BR %Y
  600. format specifiers only scan two digits (assumed to be the first two
  601. digits of a four-digit year) for
  602. .BR %C
  603. and four digits (assumed to be the entire (four-digit) year) for
  604. .BR %F
  605. and
  606. .BR %Y .
  607. This mimics the behavior of
  608. \fIprintf\fR()
  609. and
  610. \fIscanf\fR();
  611. that is:
  612. .sp
  613. .RS 4
  614. .nf
  615. printf("%2d", x = 1000);
  616. .fi
  617. .P
  618. .RE
  619. .P
  620. prints
  621. .BR \(dq1000\(dq ,
  622. but:
  623. .sp
  624. .RS 4
  625. .nf
  626. scanf(%2d", &x);
  627. .fi
  628. .P
  629. .RE
  630. .P
  631. when given
  632. .BR \(dq1000\(dq
  633. as input will only store 10 in
  634. .IR x ).
  635. Applications using extended ranges of years must be sure that the number
  636. of digits specified for scanning years with
  637. \fIstrptime\fR()
  638. matches the number of digits that will actually be present in the input
  639. stream. Historic implementations of the
  640. .BR %Y
  641. conversion specification (with no flags and no minimum field width)
  642. produced different output formats. Some always produced at least four
  643. digits (with 0 fill for years from 0 through 999) while others only
  644. produced the number of digits present in the year (with no fill and no
  645. padding). These two forms can be produced with the
  646. .BR '0'
  647. flag and a minimum field width options using the conversions
  648. specifications
  649. .BR %04Y
  650. and
  651. .BR %01Y ,
  652. respectively.
  653. .P
  654. In the past, the C and POSIX standards specified that
  655. .BR %F
  656. produced an ISO\ 8601:\|2004 standard date format, but didn't specify which one. For
  657. years in the range [0001,9999], POSIX.1\(hy2008 requires that the output
  658. produced match the ISO\ 8601:\|2004 standard complete representation extended format
  659. (YYYY-MM-DD) and for years outside of this range produce output
  660. that matches the ISO\ 8601:\|2004 standard expanded representation extended format
  661. (<+/-><Underline>Y</Underline>YYYY-MM-DD). To fully meet ISO\ 8601:\|2004 standard
  662. requirements, the producer and consumer must agree on a date format that
  663. has a specific number of bytes reserved to hold the characters used to
  664. represent the years that is sufficiently large to hold all values that
  665. will be shared. For example, the
  666. .BR %+13F
  667. conversion specification will produce output matching the format
  668. .BR \(dq<+/->YYYYYY-MM-DD\(dq
  669. (a leading
  670. .BR '+'
  671. or
  672. .BR '\-'
  673. sign; a six-digit, 0-filled year; a
  674. .BR '\-' ;
  675. a two-digit, leading 0-filled month; another
  676. .BR '\-' ;
  677. and the two-digit, leading 0-filled day within the month).
  678. .P
  679. Note that if the year being printed is greater than 9999, the resulting
  680. string from the unadorned
  681. .BR %F
  682. conversion specifications will not conform to the ISO\ 8601:\|2004 standard extended format,
  683. complete representation for a date and will instead be an extended format,
  684. expanded representation (presumably without the required agreement
  685. between the date's producer and consumer).
  686. .P
  687. In the C or POSIX locale, the
  688. .BR E
  689. and
  690. .BR O
  691. modifiers are ignored and the replacement strings for the following
  692. specifiers are:
  693. .IP "\fR%a\fR" 8
  694. The first three characters of
  695. .BR %A .
  696. .IP "\fR%A\fR" 8
  697. One of Sunday, Monday, .\|.\|., Saturday.
  698. .IP "\fR%b\fR" 8
  699. The first three characters of
  700. .BR %B .
  701. .IP "\fR%B\fR" 8
  702. One of January, February, .\|.\|., December.
  703. .IP "\fR%c\fR" 8
  704. Equivalent to
  705. .BR %a
  706. .BR %b
  707. .BR %e
  708. .BR %T
  709. .BR %Y .
  710. .IP "\fR%p\fR" 8
  711. One of AM or PM.
  712. .IP "\fR%r\fR" 8
  713. Equivalent to
  714. .BR %I :\c
  715. .BR %M :\c
  716. .BR %S
  717. .BR %p .
  718. .IP "\fR%x\fR" 8
  719. Equivalent to
  720. .BR %m /\c
  721. .BR %d /\c
  722. .BR %y .
  723. .IP "\fR%X\fR" 8
  724. Equivalent to
  725. .BR %T .
  726. .IP "\fR%Z\fR" 8
  727. Implementation-defined.
  728. .SH RATIONALE
  729. The
  730. .BR %Y
  731. conversion specification to
  732. \fIstrftime\fR()
  733. was frequently assumed to be a four-digit year, but the ISO\ C standard does not
  734. specify that
  735. .BR %Y
  736. is restricted to any subset of allowed values from the
  737. .IR tm_year
  738. field. Similarly, the
  739. .BR %C
  740. conversion specification was assumed to be a two-digit field and the
  741. first part of the output from the
  742. .BR %F
  743. conversion specification was assumed to be a four-digit field. With
  744. .IR tm_year
  745. being a signed 32 or more-bit
  746. .BR int
  747. and with many current implementations supporting 64-bit
  748. .BR time_t
  749. types in one or more programming environments, these assumptions are
  750. clearly wrong.
  751. .P
  752. POSIX.1\(hy2008 now allows the format specifications
  753. .BR %0xC ,
  754. .BR %0xF ,
  755. .BR %0xG ,
  756. and
  757. .BR %0xY
  758. (where
  759. .BR 'x'
  760. is a string of decimal digits used to specify printing and scanning of a
  761. string of
  762. .IR x
  763. decimal digits) with leading zero fill characters. Allowing applications
  764. to set the field width enables them to agree on the number of digits
  765. to be printed and scanned in the ISO\ 8601:\|2004 standard expanded representation of a
  766. year (for
  767. .BR %F ,
  768. .BR %G ,
  769. and
  770. .BR %Y )
  771. or all but the last two digits of the year (for
  772. .BR %C ).
  773. This is based on a feature in some versions of GNU
  774. .BR libc 's
  775. \fIstrftime\fR().
  776. The GNU version allows specifying space, zero, or no-fill characters in
  777. \fIstrftime\fR()
  778. format strings, but does not allow any flags to be specified in
  779. \fIstrptime\fR()
  780. format strings. These implementations also allow these flags to be
  781. specified for any numeric field. POSIX.1\(hy2008 only requires the zero fill flag
  782. (\c
  783. .BR '0' )
  784. and only requires that it be recognized when processing
  785. .BR %C ,
  786. .BR %F ,
  787. .BR %G ,
  788. and
  789. .BR %Y
  790. specifications when a minimum field width is also specified. The
  791. .BR '0'
  792. flag is the only flag needed to produce and scan the ISO\ 8601:\|2004 standard
  793. year fields using the extended format forms. POSIX.1\(hy2008 also allows
  794. applications to specify the same flag and field width specifiers to be
  795. used in both
  796. \fIstrftime\fR()
  797. and
  798. \fIstrptime\fR()
  799. format strings for symmetry. Systems may provide other flag characters
  800. and may accept flags in conjunction with conversion specifiers other than
  801. .BR %C ,
  802. .BR %F ,
  803. .BR %G ,
  804. and
  805. .BR %Y ;
  806. but portable applications cannot depend on such extensions.
  807. .P
  808. POSIX.1\(hy2008 now also allows the format specifications
  809. .BR %+xC ,
  810. .BR %+xF ,
  811. .BR %+xG ,
  812. and
  813. .BR %+xY
  814. (where
  815. .BR 'x'
  816. is a string of decimal digits used to specify printing and scanning of
  817. a string of
  818. .BR 'x'
  819. decimal digits) with leading zero fill characters and a leading
  820. .BR '+'
  821. sign character if the year being converted is more than four digits
  822. or a minimum field width is specified that allows room for more than
  823. four digits for the year. This allows date providers and consumers to
  824. agree on a specific number of digits to represent a year as required by
  825. the ISO\ 8601:\|2004 standard expanded representation formats. The expanded representation
  826. formats all require the year to begin with a leading
  827. .BR '+'
  828. or
  829. .BR '\-'
  830. sign.
  831. (All of these specifiers can also provide a leading
  832. .BR '\-'
  833. sign for negative years. Since negative years and the year 0 don't fit
  834. well with the Gregorian or Julian calendars, the normal ranges of dates
  835. start with year 1. The ISO\ C standard allows
  836. .IR tm_year
  837. to assume values corresponding to years before year 1, but the use of
  838. such years provided unspecified results.)
  839. .P
  840. Some earlier version of this standard specified that applications wanting
  841. to use
  842. \fIstrptime\fR()
  843. to scan dates and times printed by
  844. \fIstrftime\fR()
  845. should provide non-digit characters between fields to separate years
  846. from months and days. It also supported
  847. .BR %F
  848. to print and scan the ISO\ 8601:\|2004 standard extended format, complete representation date
  849. for years 1 through 9999 (i.e., YYYY-MM-DD). However, many applications
  850. were written to print (using
  851. \fIstrftime\fR())
  852. and scan (using
  853. \fIstrptime\fR())
  854. dates written using the basic format complete representation
  855. (four-digit years) and truncated representation (two-digit years)
  856. specified by the ISO\ 8601:\|2004 standard representation of dates and times which do not
  857. have any separation characters between fields. The ISO\ 8601:\|2004 standard also specifies
  858. basic format expanded representation where the creator and consumer of
  859. these fields agree beforehand to represent years as leading zero-filled
  860. strings of an agreed length of more than four digits to represent a year
  861. (again with no separation characters when year, month, and day are all
  862. displayed). Applications producing and consuming expanded representations
  863. are encouraged to use the
  864. .BR '+'
  865. flag and an appropriate maximum field width to scan the year including
  866. the leading sign. Note that even without the
  867. .BR '+'
  868. flag, years less than zero may be represented with a leading
  869. <hyphen-minus>
  870. for
  871. .BR %F ,
  872. .BR %G ,
  873. and
  874. .BR %Y
  875. conversion specifications. Using negative years results in unspecified
  876. behavior.
  877. .P
  878. If a format specification
  879. .BR %+xF
  880. with the field width
  881. .IR x
  882. greater than 11 is specified and the width is large enough to display
  883. the full year, the output string produced will match the ISO\ 8601:\|2004 standard
  884. subclause 4.1.2.4 expanded representation, extended format date
  885. representation for a specific day. (For years in the range [1,99\|999],
  886. .BR %+12F
  887. is sufficient for an agreed five-digit year with a leading sign using
  888. the ISO\ 8601:\|2004 standard expanded representation, extended format for a specific day
  889. .BR \(dq<+/->YYYYY-MM-DD\(dq .)
  890. Note also that years less than 0 may produce a leading
  891. <hyphen-minus>
  892. character (\c
  893. .BR '\-' )
  894. when using
  895. .BR %Y
  896. or
  897. .BR %C
  898. whether or not the
  899. .BR '0'
  900. or
  901. .BR '+'
  902. flags are used.
  903. .P
  904. The difference between the
  905. .BR '0'
  906. flag and the
  907. .BR '+'
  908. flag is whether the leading
  909. .BR '+'
  910. character will be provided for years >9999 as required for the ISO\ 8601:\|2004 standard
  911. extended representation format containing a year. For example:
  912. .TS
  913. box center tab(!);
  914. cB | cB | cB | cB
  915. cB | cB | cB | cB
  916. l | lf5 | l | l.
  917. !!\fIstrftime\fP(\^)!\fIstrptime\fP(\^)
  918. Year!Conversion Specification!Output!Scan Back
  919. _
  920. 1970!%Y!1970!1970
  921. _
  922. 1970!%+4Y!1970!1970
  923. _
  924. 27!%Y!27 or 0027!27
  925. _
  926. 270!%Y!270 or 0270!270
  927. _
  928. 270!%+4Y!0270!270
  929. _
  930. 17!%C%y!0017!17
  931. _
  932. 270!%C%y!0270!270
  933. _
  934. 12345!%Y!12345!1234*
  935. _
  936. 12345!%+4Y!+12345!123*
  937. _
  938. 12345!%05Y!12345!12345
  939. _
  940. 270!%+5Y \fRor\fP %+3C%y!+0270!270
  941. _
  942. 12345!%+5Y \fRor\fP %+3C%y!+12345!1234*
  943. _
  944. 12345!%06Y \fRor\fP %04C%y!012345!12345
  945. _
  946. 12345!%+6Y \fRor\fP %+4C%y!+12345!12345
  947. _
  948. 123456!%08Y \fRor\fP %06C%y!00123456!123456
  949. _
  950. 123456!%+8Y \fRor\fP %+6C%y!+0123456!123456
  951. .TE
  952. .P
  953. In the cases above marked with a * in the
  954. \fIstrptime\fR()
  955. scan back field, the implied or specified number of characters scanned by
  956. \fIstrptime\fR()
  957. was less than the number of characters output by
  958. \fIstrftime\fR()
  959. using the same format; so the remaining digits of the year were dropped
  960. when the output date produced by
  961. \fIstrftime\fR()
  962. was scanned back in by
  963. \fIstrptime\fR().
  964. .SH "FUTURE DIRECTIONS"
  965. None.
  966. .SH "SEE ALSO"
  967. .IR "\fIasctime\fR\^(\|)",
  968. .IR "\fIclock\fR\^(\|)",
  969. .IR "\fIctime\fR\^(\|)",
  970. .IR "\fIdifftime\fR\^(\|)",
  971. .IR "\fIgetdate\fR\^(\|)",
  972. .IR "\fIgmtime\fR\^(\|)",
  973. .IR "\fIlocaltime\fR\^(\|)",
  974. .IR "\fImktime\fR\^(\|)",
  975. .IR "\fIstrptime\fR\^(\|)",
  976. .IR "\fItime\fR\^(\|)",
  977. .IR "\fItzset\fR\^(\|)",
  978. .IR "\fIuselocale\fR\^(\|)",
  979. .IR "\fIutime\fR\^(\|)"
  980. .P
  981. The Base Definitions volume of POSIX.1\(hy2017,
  982. .IR "Section 7.3.5" ", " "LC_TIME",
  983. .IR "\fB<time.h>\fP"
  984. .\"
  985. .SH COPYRIGHT
  986. Portions of this text are reprinted and reproduced in electronic form
  987. from IEEE Std 1003.1-2017, Standard for Information Technology
  988. -- Portable Operating System Interface (POSIX), The Open Group Base
  989. Specifications Issue 7, 2018 Edition,
  990. Copyright (C) 2018 by the Institute of
  991. Electrical and Electronics Engineers, Inc and The Open Group.
  992. In the event of any discrepancy between this version and the original IEEE and
  993. The Open Group Standard, the original IEEE and The Open Group Standard
  994. is the referee document. The original Standard can be obtained online at
  995. http://www.opengroup.org/unix/online.html .
  996. .PP
  997. Any typographical or formatting errors that appear
  998. in this page are most likely
  999. to have been introduced during the conversion of the source files to
  1000. man page format. To report such errors, see
  1001. https://www.kernel.org/doc/man-pages/reporting_bugs.html .