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

strptime.3p (13262B)


  1. '\" et
  2. .TH STRPTIME "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. strptime
  12. \(em date and time conversion
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <time.h>
  17. .P
  18. char *strptime(const char *restrict \fIbuf\fP, const char *restrict \fIformat\fP,
  19. struct tm *restrict \fItm\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fIstrptime\fR()
  24. function shall convert the character string pointed to by
  25. .IR buf
  26. to values which are stored in the
  27. .BR tm
  28. structure pointed to by
  29. .IR tm ,
  30. using the format specified by
  31. .IR format .
  32. .P
  33. The format is composed of zero or more directives. Each directive is
  34. composed of one of the following: one or more white-space characters
  35. (as specified by
  36. \fIisspace\fR());
  37. an ordinary character (neither
  38. .BR '%'
  39. nor a white-space character); or a conversion specification.
  40. .P
  41. Each conversion specification is introduced by the
  42. .BR '%'
  43. character after which the following appear in sequence:
  44. .IP " *" 4
  45. An optional flag, the zero character (\c
  46. .BR '0' )
  47. or the
  48. <plus-sign>
  49. character (\c
  50. .BR '+' ),
  51. which is ignored.
  52. .IP " *" 4
  53. An optional field width. If a field width is specified, it shall be
  54. interpreted as a string of decimal digits that will determine the maximum
  55. number of bytes converted for the conversion rather than the number of
  56. bytes specified below in the description of the conversion specifiers.
  57. .IP " *" 4
  58. An optional
  59. .BR E
  60. or
  61. .BR O
  62. modifier.
  63. .IP " *" 4
  64. A terminating conversion specifier character that indicates the type of
  65. conversion to be applied.
  66. .P
  67. The conversions are determined using the
  68. .IR LC_TIME
  69. category of the current locale. The application shall ensure that
  70. there is white-space or other non-alphanumeric characters between any
  71. two conversion specifications unless all of the adjacent conversion
  72. specifications convert a known, fixed number of characters. In the
  73. following list, the maximum number of characters scanned (excluding the
  74. one matching the next directive) is as follows:
  75. .IP " *" 4
  76. If a maximum field width is specified, then that number
  77. .IP " *" 4
  78. Otherwise, the pattern
  79. .BR \(dq{x}\(dq
  80. indicates that the maximum is
  81. .IR x
  82. .IP " *" 4
  83. Otherwise, the pattern
  84. .BR \(dq[x,y]\(dq
  85. indicates that the value shall fall within the range given (both bounds
  86. being inclusive), and the maximum number of characters scanned shall be
  87. the maximum required to represent any value in the range without leading
  88. zeros and without a leading
  89. <plus-sign>
  90. .P
  91. The following conversion specifiers are supported.
  92. .P
  93. The results are unspecified if a modifier is specified with a flag or
  94. with a minimum field width, or if a field width is specified for any
  95. conversion specifier other than
  96. .BR C
  97. or
  98. .BR Y .
  99. .IP "\fRa\fR" 8
  100. The day of the week, using the locale's weekday names; either the
  101. abbreviated or full name may be specified.
  102. .IP "\fRA\fR" 8
  103. Equivalent to
  104. .BR %a .
  105. .IP "\fRb\fR" 8
  106. The month, using the locale's month names; either the abbreviated or
  107. full name may be specified.
  108. .IP "\fRB\fR" 8
  109. Equivalent to
  110. .BR %b .
  111. .IP "\fRc\fR" 8
  112. Replaced by the locale's appropriate date and time representation.
  113. .IP "\fRC\fR" 8
  114. All but the last two digits of the year {2}; leading zeros shall be
  115. permitted but shall not be required. A leading
  116. .BR '+'
  117. or
  118. .BR '\-'
  119. character shall be permitted before any leading zeros but shall not
  120. be required.
  121. .IP "\fRd\fR" 8
  122. The day of the month [01,31]; leading zeros shall be permitted but shall
  123. not be required.
  124. .IP "\fRD\fR" 8
  125. The date as
  126. .BR %m /\c
  127. .BR %d /\c
  128. .BR %y .
  129. .IP "\fRe\fR" 8
  130. Equivalent to
  131. .BR %d .
  132. .IP "\fRh\fR" 8
  133. Equivalent to
  134. .BR %b .
  135. .IP "\fRH\fR" 8
  136. The hour (24-hour clock) [00,23]; leading zeros shall be permitted but
  137. shall not be required.
  138. .IP "\fRI\fR" 8
  139. The hour (12-hour clock) [01,12]; leading zeros shall be permitted but
  140. shall not be required.
  141. .IP "\fRj\fR" 8
  142. The day number of the year [001,366]; leading zeros shall be permitted
  143. but shall not be required.
  144. .IP "\fRm\fR" 8
  145. The month number [01,12]; leading zeros shall be permitted but shall
  146. not be required.
  147. .IP "\fRM\fR" 8
  148. The minute [00,59]; leading zeros shall be permitted but shall not
  149. be required.
  150. .IP "\fRn\fR" 8
  151. Any white space.
  152. .IP "\fRp\fR" 8
  153. The locale's equivalent of a.m. or p.m.
  154. .IP "\fRr\fR" 8
  155. 12-hour clock time using the AM/PM notation if
  156. .BR t_fmt_ampm
  157. is not an empty string in the
  158. .IR LC_TIME
  159. portion of the current locale; in the POSIX locale, this shall
  160. be equivalent to
  161. .BR %I :\c
  162. .BR %M :\c
  163. .BR %S
  164. .BR %p .
  165. .IP "\fRR\fR" 8
  166. The time as
  167. .BR %H :\c
  168. .BR %M .
  169. .IP "\fRS\fR" 8
  170. The seconds [00,60]; leading zeros shall be permitted but shall
  171. not be required.
  172. .IP "\fRt\fR" 8
  173. Any white space.
  174. .IP "\fRT\fR" 8
  175. The time as
  176. .BR %H :\c
  177. .BR %M :\c
  178. .BR %S .
  179. .IP "\fRU\fR" 8
  180. The week number of the year (Sunday as the first day of the week) as a
  181. decimal number [00,53]; leading zeros shall be permitted but shall
  182. not be required.
  183. .IP "\fRw\fR" 8
  184. The weekday as a decimal number [0,6], with 0 representing Sunday.
  185. .IP "\fRW\fR" 8
  186. The week number of the year (Monday as the first day of the week) as a
  187. decimal number [00,53]; leading zeros shall be permitted but shall
  188. not be required.
  189. .IP "\fRx\fR" 8
  190. The date, using the locale's date format.
  191. .IP "\fRX\fR" 8
  192. The time, using the locale's time format.
  193. .IP "\fRy\fR" 8
  194. The last two digits of the year. When
  195. .IR format
  196. contains neither a
  197. .BR C
  198. conversion specifier nor a
  199. .BR Y
  200. conversion specifier, values in the range [69,99] shall refer to years
  201. 1969 to 1999 inclusive and values in the range [00,68] shall refer to
  202. years 2000 to 2068 inclusive; leading zeros shall be permitted but shall
  203. not be required. A leading
  204. .BR '+'
  205. or
  206. .BR '\-'
  207. character shall be permitted before any leading zeros but shall not
  208. be required.
  209. .RS 8
  210. .TP 10
  211. .BR Note:
  212. It is expected that in a future version of this standard the default
  213. century inferred from a 2-digit year will change. (This would apply
  214. to all commands accepting a 2-digit year as input.)
  215. .P
  216. .RE
  217. .IP "\fRY\fR" 8
  218. The full year {4}; leading zeros shall be permitted but shall
  219. not be required. A leading
  220. .BR '+'
  221. or
  222. .BR '\-'
  223. character shall be permitted before any leading zeros but shall not
  224. be required.
  225. .IP "\fR%\fP" 8
  226. Replaced by
  227. .BR % .
  228. .SS "Modified Conversion Specifiers"
  229. .P
  230. Some conversion specifiers can be modified by the
  231. .BR E
  232. and
  233. .BR O
  234. modifier characters to indicate that an alternative format or
  235. specification should be used rather than the one normally used by the
  236. unmodified conversion specifier. If the alternative format or
  237. specification does not exist in the current locale, the behavior shall
  238. be as if the unmodified conversion specification were used.
  239. .IP "\fR%Ec\fR" 8
  240. The locale's alternative appropriate date and time representation.
  241. .IP "\fR%EC\fR" 8
  242. The name of the base year (period) in the locale's alternative
  243. representation.
  244. .IP "\fR%Ex\fR" 8
  245. The locale's alternative date representation.
  246. .IP "\fR%EX\fR" 8
  247. The locale's alternative time representation.
  248. .IP "\fR%Ey\fR" 8
  249. The offset from
  250. .BR %EC
  251. (year only) in the locale's alternative representation.
  252. .IP "\fR%EY\fR" 8
  253. The full alternative year representation.
  254. .IP "\fR%Od\fR" 8
  255. The day of the month using the locale's alternative numeric symbols;
  256. leading zeros shall be permitted but shall not be required.
  257. .IP "\fR%Oe\fR" 8
  258. Equivalent to
  259. .BR %Od .
  260. .IP "\fR%OH\fR" 8
  261. The hour (24-hour clock) using the locale's alternative numeric
  262. symbols.
  263. .IP "\fR%OI\fR" 8
  264. The hour (12-hour clock) using the locale's alternative numeric
  265. symbols.
  266. .IP "\fR%Om\fR" 8
  267. The month using the locale's alternative numeric symbols.
  268. .IP "\fR%OM\fR" 8
  269. The minutes using the locale's alternative numeric symbols.
  270. .IP "\fR%OS\fR" 8
  271. The seconds using the locale's alternative numeric symbols.
  272. .IP "\fR%OU\fR" 8
  273. The week number of the year (Sunday as the first day of the week) using
  274. the locale's alternative numeric symbols.
  275. .IP "\fR%Ow\fR" 8
  276. The number of the weekday (Sunday=0) using the locale's alternative
  277. numeric symbols.
  278. .IP "\fR%OW\fR" 8
  279. The week number of the year (Monday as the first day of the week) using
  280. the locale's alternative numeric symbols.
  281. .IP "\fR%Oy\fR" 8
  282. The year (offset from
  283. .BR %C )
  284. using the locale's alternative numeric symbols.
  285. .P
  286. A conversion specification composed of white-space characters is
  287. executed by scanning input up to the first character that is not
  288. white-space (which remains unscanned), or until no more characters can
  289. be scanned.
  290. .P
  291. A conversion specification that is an ordinary character is executed by
  292. scanning the next character from the buffer. If the character scanned
  293. from the buffer differs from the one comprising the directive, the
  294. directive fails, and the differing and subsequent characters remain
  295. unscanned.
  296. .P
  297. A series of conversion specifications composed of
  298. .BR %n ,
  299. .BR %t ,
  300. white-space characters, or any combination is executed by scanning up
  301. to the first character that is not white space (which remains
  302. unscanned), or until no more characters can be scanned.
  303. .P
  304. Any other conversion specification is executed by scanning characters
  305. until a character matching the next directive is scanned, or until no
  306. more characters can be scanned. These characters, except the one
  307. matching the next directive, are then compared to the locale values
  308. associated with the conversion specifier. If a match is found, values
  309. for the appropriate
  310. .BR tm
  311. structure members are set to values corresponding to the locale
  312. information. Case is ignored when matching items in
  313. .IR buf
  314. such as month or weekday names. If no match is found,
  315. \fIstrptime\fR()
  316. fails and no more characters are scanned.
  317. .SH "RETURN VALUE"
  318. Upon successful completion,
  319. \fIstrptime\fR()
  320. shall return a pointer to the character following the last character
  321. parsed. Otherwise, a null pointer shall be returned.
  322. .SH ERRORS
  323. No errors are defined.
  324. .LP
  325. .IR "The following sections are informative."
  326. .SH EXAMPLES
  327. .SS "Convert a Date-Plus-Time String to Broken-Down Time and Then into Seconds"
  328. .P
  329. The following example demonstrates the use of
  330. \fIstrptime\fR()
  331. to convert a string into broken-down time. The broken-down time is then
  332. converted into seconds since the Epoch using
  333. \fImktime\fR().
  334. .sp
  335. .RS 4
  336. .nf
  337. #include <time.h>
  338. \&...
  339. .P
  340. struct tm tm;
  341. time_t t;
  342. .P
  343. if (strptime("6 Dec 2001 12:33:45", "%d %b %Y %H:%M:%S", &tm) == NULL)
  344. /* Handle error */;
  345. .P
  346. printf("year: %d; month: %d; day: %d;\en",
  347. tm.tm_year, tm.tm_mon, tm.tm_mday);
  348. printf("hour: %d; minute: %d; second: %d\en",
  349. tm.tm_hour, tm.tm_min, tm.tm_sec);
  350. printf("week day: %d; year day: %d\en", tm.tm_wday, tm.tm_yday);
  351. .P
  352. tm.tm_isdst = -1; /* Not set by strptime(); tells mktime()
  353. to determine whether daylight saving time
  354. is in effect */
  355. t = mktime(&tm);
  356. if (t == -1)
  357. /* Handle error */;
  358. printf("seconds since the Epoch: %ld\en", (long) t);"
  359. .fi
  360. .P
  361. .RE
  362. .SH "APPLICATION USAGE"
  363. Several ``equivalent to'' formats and the special processing of
  364. white-space characters are provided in order to ease the use of
  365. identical
  366. .IR format
  367. strings for
  368. \fIstrftime\fR()
  369. and
  370. \fIstrptime\fR().
  371. .P
  372. It should be noted that dates constructed by the
  373. \fIstrftime\fR()
  374. function with the
  375. .BR %Y
  376. or
  377. .BR %C%y
  378. conversion specifiers may have values larger than 9\|999. If the
  379. \fIstrptime\fR()
  380. function is used to read such values using
  381. .BR %C%y
  382. or
  383. .BR %Y ,
  384. the year values will be truncated to four digits. Applications should use
  385. .BR %+ \c
  386. .IR w \c
  387. .BR %y
  388. or
  389. .BR %+ \c
  390. .IR x \c
  391. .BR Y
  392. with
  393. .IR w
  394. and
  395. .IR x
  396. set large enough to contain the full value of any years that will be
  397. printed or scanned.
  398. .P
  399. See also the APPLICATION USAGE section in
  400. .IR "\fIstrftime\fR\^(\|)".
  401. .P
  402. It is unspecified whether multiple calls to
  403. \fIstrptime\fR()
  404. using the same
  405. .BR tm
  406. structure will update the current contents of the structure or
  407. overwrite all contents of the structure. Conforming applications
  408. should make a single call to
  409. \fIstrptime\fR()
  410. with a format and all data needed to completely specify the date and
  411. time being converted.
  412. .SH RATIONALE
  413. See the RATIONALE section for
  414. .IR "\fIstrftime\fR\^(\|)".
  415. .SH "FUTURE DIRECTIONS"
  416. None.
  417. .SH "SEE ALSO"
  418. .IR "\fIfprintf\fR\^(\|)",
  419. .IR "\fIfscanf\fR\^(\|)",
  420. .IR "\fIstrftime\fR\^(\|)",
  421. .IR "\fItime\fR\^(\|)"
  422. .P
  423. The Base Definitions volume of POSIX.1\(hy2017,
  424. .IR "\fB<time.h>\fP"
  425. .\"
  426. .SH COPYRIGHT
  427. Portions of this text are reprinted and reproduced in electronic form
  428. from IEEE Std 1003.1-2017, Standard for Information Technology
  429. -- Portable Operating System Interface (POSIX), The Open Group Base
  430. Specifications Issue 7, 2018 Edition,
  431. Copyright (C) 2018 by the Institute of
  432. Electrical and Electronics Engineers, Inc and The Open Group.
  433. In the event of any discrepancy between this version and the original IEEE and
  434. The Open Group Standard, the original IEEE and The Open Group Standard
  435. is the referee document. The original Standard can be obtained online at
  436. http://www.opengroup.org/unix/online.html .
  437. .PP
  438. Any typographical or formatting errors that appear
  439. in this page are most likely
  440. to have been introduced during the conversion of the source files to
  441. man page format. To report such errors, see
  442. https://www.kernel.org/doc/man-pages/reporting_bugs.html .