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

getdate.3p (10807B)


  1. '\" et
  2. .TH GETDATE "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. getdate
  12. \(em convert user format date and time
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <time.h>
  17. .P
  18. struct tm *getdate(const char *\fIstring\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIgetdate\fR()
  23. function shall convert a string representation of a date or time
  24. into a broken-down time.
  25. .P
  26. The external variable or macro
  27. .IR getdate_err ,
  28. which has type
  29. .BR int ,
  30. is used by
  31. \fIgetdate\fR()
  32. to return error values. It is unspecified whether
  33. .IR getdate_err
  34. is a macro or an identifier declared with external linkage, and whether
  35. or not it is a modifiable lvalue. If a macro definition is suppressed
  36. in order to access an actual object, or a program defines an identifier
  37. with the name
  38. .IR getdate_err ,
  39. the behavior is undefined.
  40. .P
  41. Templates are used to parse and interpret the input string. The
  42. templates are contained in a text file identified by the environment
  43. variable
  44. .IR DATEMSK .
  45. The
  46. .IR DATEMSK
  47. variable should be set to indicate the full pathname of the file that
  48. contains the templates. The first line in the template that matches
  49. the input specification is used for interpretation and conversion into
  50. the internal time format.
  51. .P
  52. The following conversion specifications shall be supported:
  53. .IP "\fR%%\fR" 8
  54. Equivalent to
  55. .BR % .
  56. .IP "\fR%a\fR" 8
  57. Abbreviated weekday name.
  58. .IP "\fR%A\fR" 8
  59. Full weekday name.
  60. .IP "\fR%b\fR" 8
  61. Abbreviated month name.
  62. .IP "\fR%B\fR" 8
  63. Full month name.
  64. .IP "\fR%c\fR" 8
  65. Locale's appropriate date and time representation.
  66. .IP "\fR%C\fR" 8
  67. Century number [00,99]; leading zeros are permitted but not required.
  68. .IP "\fR%d\fR" 8
  69. Day of month [01,31]; the leading 0 is optional.
  70. .IP "\fR%D\fR" 8
  71. Date as
  72. .BR %m /\c
  73. .BR %d /\c
  74. .BR %y .
  75. .IP "\fR%e\fR" 8
  76. Equivalent to
  77. .BR %d .
  78. .IP "\fR%h\fR" 8
  79. Abbreviated month name.
  80. .IP "\fR%H\fR" 8
  81. Hour [00,23].
  82. .IP "\fR%I\fR" 8
  83. Hour [01,12].
  84. .IP "\fR%m\fR" 8
  85. Month number [01,12].
  86. .IP "\fR%M\fR" 8
  87. Minute [00,59].
  88. .IP "\fR%n\fR" 8
  89. Equivalent to
  90. <newline>.
  91. .IP "\fR%p\fR" 8
  92. Locale's equivalent of either AM or PM.
  93. .IP "\fR%r\fR" 8
  94. The locale's appropriate representation of time in AM and PM notation.
  95. In the POSIX locale, this shall be equivalent to
  96. .BR %I :\c
  97. .BR %M :\c
  98. .BR %S
  99. .BR %p .
  100. .IP "\fR%R\fR" 8
  101. Time as
  102. .BR %H :\c
  103. .BR %M .
  104. .IP "\fR%S\fR" 8
  105. Seconds [00,60]. The range goes to 60 (rather than stopping at 59)
  106. to allow positive leap seconds to be expressed. Since leap seconds
  107. cannot be predicted by any algorithm, leap second data must come from
  108. some external source.
  109. .IP "\fR%t\fR" 8
  110. Equivalent to
  111. <tab>.
  112. .IP "\fR%T\fR" 8
  113. Time as
  114. .BR %H :\c
  115. .BR %M :\c
  116. .BR %S .
  117. .IP "\fR%w\fR" 8
  118. Weekday number (Sunday = [0,6]).
  119. .IP "\fR%x\fR" 8
  120. Locale's appropriate date representation.
  121. .IP "\fR%X\fR" 8
  122. Locale's appropriate time representation.
  123. .IP "\fR%y\fR" 8
  124. Year within century. When a century is not otherwise specified, values
  125. in the range [69,99] shall refer to years 1969 to 1999 inclusive,
  126. and values in the range [00,68] shall refer to years 2000 to 2068
  127. inclusive.
  128. .RS 8
  129. .TP 10
  130. .BR Note:
  131. It is expected that in a future version of this standard the default
  132. century inferred from a 2-digit year will change. (This would apply
  133. to all commands accepting a 2-digit year as input.)
  134. .P
  135. .RE
  136. .IP "\fR%Y\fR" 8
  137. Year as
  138. .BR \(dqccyy\(dq
  139. (for example, 2001).
  140. .IP "\fR%Z\fR" 8
  141. Timezone name or no characters if no timezone exists. If the
  142. timezone supplied by
  143. .BR %Z
  144. is not the timezone that
  145. \fIgetdate\fR()
  146. expects, an invalid input specification error shall result. The
  147. \fIgetdate\fR()
  148. function calculates an expected timezone based on information supplied
  149. to the function (such as the hour, day, and month).
  150. .P
  151. The match between the template and input specification performed by
  152. \fIgetdate\fR()
  153. shall be case-insensitive.
  154. .P
  155. The month and weekday names can consist of any combination of upper and
  156. lowercase letters. The process can request that the input date or time
  157. specification be in a specific language by setting the
  158. .IR LC_TIME
  159. category
  160. (see
  161. .IR "\fIsetlocale\fR\^(\|)").
  162. .P
  163. Leading zeros are not necessary for the descriptors that allow leading
  164. zeros. However, at most two digits are allowed for those descriptors,
  165. including leading zeros. Extra white space in either the template file
  166. or in
  167. .IR string
  168. shall be ignored.
  169. .P
  170. The results are undefined if the conversion specifications
  171. .BR %c ,
  172. .BR %x ,
  173. and
  174. .BR %X
  175. include unsupported conversion specifications.
  176. .P
  177. The following rules apply for converting the input specification into
  178. the internal format:
  179. .IP " *" 4
  180. If
  181. .BR %Z
  182. is being scanned, then
  183. \fIgetdate\fR()
  184. shall initialize the broken-down time to be the current time in the
  185. scanned timezone. Otherwise, it shall initialize the broken-down time
  186. based on the current local time as if
  187. \fIlocaltime\fR()
  188. had been called.
  189. .IP " *" 4
  190. If only the weekday is given, the day chosen shall be the day, starting
  191. with today and moving into the future, which first matches the named
  192. day.
  193. .IP " *" 4
  194. If only the month (and no year) is given, the month chosen shall be the
  195. month, starting with the current month and moving into the future,
  196. which first matches the named month. The first day of the month shall
  197. be assumed if no day is given.
  198. .IP " *" 4
  199. If no hour, minute, and second are given, the current hour, minute, and
  200. second shall be assumed.
  201. .IP " *" 4
  202. If no date is given, the hour chosen shall be the hour, starting with
  203. the current hour and moving into the future, which first matches the
  204. named hour.
  205. .P
  206. If a conversion specification in the DATEMSK file does not correspond
  207. to one of the conversion specifications above, the behavior is
  208. unspecified.
  209. .P
  210. The
  211. \fIgetdate\fR()
  212. function need not be thread-safe.
  213. .SH "RETURN VALUE"
  214. Upon successful completion,
  215. \fIgetdate\fR()
  216. shall return a pointer to a
  217. .BR "struct tm" .
  218. Otherwise, it shall return a null pointer and set
  219. .IR getdate_err
  220. to indicate the error.
  221. .SH ERRORS
  222. The
  223. \fIgetdate\fR()
  224. function shall fail in the following cases, setting
  225. .IR getdate_err
  226. to the value shown in the list below. Any changes to
  227. .IR errno
  228. are unspecified.
  229. .IP " 1." 4
  230. The
  231. .IR DATEMSK
  232. environment variable is null or undefined.
  233. .IP " 2." 4
  234. The template file cannot be opened for reading.
  235. .IP " 3." 4
  236. Failed to get file status information.
  237. .IP " 4." 4
  238. The template file is not a regular file.
  239. .IP " 5." 4
  240. An I/O error is encountered while reading the template file.
  241. .IP " 6." 4
  242. Memory allocation failed (not enough memory available).
  243. .IP " 7." 4
  244. There is no line in the template that matches the input.
  245. .IP " 8." 4
  246. Invalid input specification. For example, February 31; or a time is
  247. specified that cannot be represented in a
  248. .BR time_t
  249. (representing the time in seconds since the Epoch).
  250. .LP
  251. .IR "The following sections are informative."
  252. .SH EXAMPLES
  253. .IP " 1." 4
  254. The following example shows the possible contents of a template:
  255. .RS 4
  256. .sp
  257. .RS 4
  258. .nf
  259. %m
  260. %A %B %d, %Y, %H:%M:%S
  261. %A
  262. %B
  263. %m/%d/%y %I %p
  264. %d,%m,%Y %H:%M
  265. at %A the %dst of %B in %Y
  266. run job at %I %p,%B %dnd
  267. %A den %d. %B %Y %H.%M Uhr
  268. .fi
  269. .P
  270. .RE
  271. .RE
  272. .IP " 2." 4
  273. The following are examples of valid input specifications for the
  274. template in Example 1:
  275. .RS 4
  276. .sp
  277. .RS 4
  278. .nf
  279. getdate("10/1/87 4 PM");
  280. getdate("Friday");
  281. getdate("Friday September 18, 1987, 10:30:30");
  282. getdate("24,9,1986 10:30");
  283. getdate("at monday the 1st of december in 1986");
  284. getdate("run job at 3 PM, december 2nd");
  285. .fi
  286. .P
  287. .RE
  288. .P
  289. If the
  290. .IR LC_TIME
  291. category is set to a German locale that includes
  292. .IR freitag
  293. as a weekday name and
  294. .IR oktober
  295. as a month name, the following would be valid:
  296. .sp
  297. .RS 4
  298. .nf
  299. getdate("freitag den 10. oktober 1986 10.30 Uhr");
  300. .fi
  301. .P
  302. .RE
  303. .RE
  304. .IP " 3." 4
  305. The following example shows how local date and time specification can
  306. be defined in the template:
  307. .TS
  308. box tab(!) center;
  309. cB | cB
  310. lf5 | lf5.
  311. Invocation!Line in Template
  312. _
  313. getdate("11/27/86")!%m/%d/%y
  314. getdate("27.11.86")!%d.%m.%y
  315. getdate("86-11-27")!%y-%m-%d
  316. getdate("Friday 12:00:00")!%A %H:%M:%S
  317. .TE
  318. .IP " 4." 4
  319. The following examples help to illustrate the above rules assuming that
  320. the current date is Mon Sep 22 12:19:47 EDT 1986 and the
  321. .IR LC_TIME
  322. category is set to the default C or POSIX locale:
  323. .TS
  324. box tab(!) center;
  325. cB | cB | cB
  326. lf5 | lf5 | l.
  327. Input!Line in Template!Date
  328. _
  329. Mon!%a!Mon Sep 22 12:19:47 EDT 1986
  330. Sun!%a!Sun Sep 28 12:19:47 EDT 1986
  331. Fri!%a!Fri Sep 26 12:19:47 EDT 1986
  332. September!%B!Mon Sep 1 12:19:47 EDT 1986
  333. January!%B!Thu Jan 1 12:19:47 EST 1987
  334. December!%B!Mon Dec 1 12:19:47 EST 1986
  335. Sep Mon!%b %a!Mon Sep 1 12:19:47 EDT 1986
  336. Jan Fri!%b %a!Fri Jan 2 12:19:47 EST 1987
  337. Dec Mon!%b %a!Mon Dec 1 12:19:47 EST 1986
  338. Jan Wed 1989!%b %a %Y!Wed Jan 4 12:19:47 EST 1989
  339. Fri 9!%a %H!Fri Sep 26 09:00:00 EDT 1986
  340. Feb 10:30!%b %H:%S!Sun Feb 1 10:00:30 EST 1987
  341. 10:30!%H:%M!Tue Sep 23 10:30:00 EDT 1986
  342. 13:30!%H:%M!Mon Sep 22 13:30:00 EDT 1986
  343. .TE
  344. .SH "APPLICATION USAGE"
  345. Although historical versions of
  346. \fIgetdate\fR()
  347. did not require that
  348. .IR <time.h>
  349. declare the external variable
  350. .IR getdate_err ,
  351. this volume of POSIX.1\(hy2017 does require it. The standard developers encourage applications
  352. to remove declarations of
  353. .IR getdate_err
  354. and instead incorporate the declaration by including
  355. .IR <time.h> .
  356. .P
  357. Applications should use
  358. .BR %Y
  359. (4-digit years) in preference to
  360. .BR %y
  361. (2-digit years).
  362. .SH RATIONALE
  363. In standard locales, the conversion specifications
  364. .BR %c ,
  365. .BR %x ,
  366. and
  367. .BR %X
  368. do not include unsupported conversion specifiers and so the text
  369. regarding results being undefined is not a problem in that case.
  370. .SH "FUTURE DIRECTIONS"
  371. None.
  372. .SH "SEE ALSO"
  373. .IR "\fIctime\fR\^(\|)",
  374. .IR "\fIlocaltime\fR\^(\|)",
  375. .IR "\fIsetlocale\fR\^(\|)",
  376. .IR "\fIstrftime\fR\^(\|)",
  377. .IR "\fItimes\fR\^(\|)"
  378. .P
  379. The Base Definitions volume of POSIX.1\(hy2017,
  380. .IR "\fB<time.h>\fP"
  381. .\"
  382. .SH COPYRIGHT
  383. Portions of this text are reprinted and reproduced in electronic form
  384. from IEEE Std 1003.1-2017, Standard for Information Technology
  385. -- Portable Operating System Interface (POSIX), The Open Group Base
  386. Specifications Issue 7, 2018 Edition,
  387. Copyright (C) 2018 by the Institute of
  388. Electrical and Electronics Engineers, Inc and The Open Group.
  389. In the event of any discrepancy between this version and the original IEEE and
  390. The Open Group Standard, the original IEEE and The Open Group Standard
  391. is the referee document. The original Standard can be obtained online at
  392. http://www.opengroup.org/unix/online.html .
  393. .PP
  394. Any typographical or formatting errors that appear
  395. in this page are most likely
  396. to have been introduced during the conversion of the source files to
  397. man page format. To report such errors, see
  398. https://www.kernel.org/doc/man-pages/reporting_bugs.html .