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

date.1p (17540B)


  1. '\" et
  2. .TH DATE "1P" 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. date
  12. \(em write the date and time
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. date \fB[\fR-u\fB] [\fR+\fIformat\fB]\fR
  17. .P
  18. date \fB[\fR-u\fB] \fImmddhhmm\fB[[\fIcc\fB]\fIyy\fB]\fR
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. .IR date
  23. utility shall write the date and time to standard output
  24. or attempt to set the system date and time.
  25. By default, the current date and time shall be written. If an operand
  26. beginning with
  27. .BR '\(pl'
  28. is specified, the output format of
  29. .IR date
  30. shall be controlled by the conversion specifications and other text
  31. in the operand.
  32. .SH OPTIONS
  33. The
  34. .IR date
  35. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  36. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  37. .P
  38. The following option shall be supported:
  39. .IP "\fB\-u\fP" 10
  40. Perform operations as if the
  41. .IR TZ
  42. environment variable was set to the string
  43. .BR \(dqUTC0\(dq ,
  44. or its equivalent historical value of
  45. .BR \(dqGMT0\(dq .
  46. Otherwise,
  47. .IR date
  48. shall use the timezone indicated by the
  49. .IR TZ
  50. environment variable or the system default if that variable is
  51. unset or null.
  52. .SH OPERANDS
  53. The following operands shall be supported:
  54. .IP "+\fIformat\fR" 10
  55. When the format is specified, each conversion specifier shall be
  56. replaced in the standard output by its corresponding value. All other
  57. characters shall be copied to the output without change. The output
  58. shall always be terminated with a
  59. <newline>.
  60. .SS "Conversion Specifications"
  61. .RS 10
  62. .IP "\fR%a\fR" 8
  63. Locale's abbreviated weekday name.
  64. .IP "\fR%A\fR" 8
  65. Locale's full weekday name.
  66. .IP "\fR%b\fR" 8
  67. Locale's abbreviated month name.
  68. .IP "\fR%B\fR" 8
  69. Locale's full month name.
  70. .IP "\fR%c\fR" 8
  71. Locale's appropriate date and time representation.
  72. .IP "\fR%C\fR" 8
  73. Century (a year divided by 100 and truncated to an integer) as a
  74. decimal number [00,99].
  75. .IP "\fR%d\fR" 8
  76. Day of the month as a decimal number [01,31].
  77. .IP "\fR%D\fR" 8
  78. Date in the format \fImm\fP/\fIdd\fP/\fIyy\fR.
  79. .IP "\fR%e\fR" 8
  80. Day of the month as a decimal number [1,31] in a two-digit field
  81. with leading
  82. <space>
  83. character fill.
  84. .IP "\fR%h\fR" 8
  85. A synonym for
  86. .BR %b .
  87. .IP "\fR%H\fR" 8
  88. Hour (24-hour clock) as a decimal number [00,23].
  89. .IP "\fR%I\fR" 8
  90. Hour (12-hour clock) as a decimal number [01,12].
  91. .IP "\fR%j\fR" 8
  92. Day of the year as a decimal number [001,366].
  93. .IP "\fR%m\fR" 8
  94. Month as a decimal number [01,12].
  95. .IP "\fR%M\fR" 8
  96. Minute as a decimal number [00,59].
  97. .IP "\fR%n\fR" 8
  98. A
  99. <newline>.
  100. .IP "\fR%p\fR" 8
  101. Locale's equivalent of either AM or PM.
  102. .IP "\fR%r\fR" 8
  103. 12-hour clock time [01,12] using the AM/PM notation; in the POSIX
  104. locale, this shall be equivalent to
  105. .BR %I :\c
  106. .BR %M :\c
  107. .BR %S
  108. .BR %p .
  109. .IP "\fR%S\fR" 8
  110. Seconds as a decimal number [00,60].
  111. .IP "\fR%t\fR" 8
  112. A
  113. <tab>.
  114. .IP "\fR%T\fR" 8
  115. 24-hour clock time [00,23] in the format \fIHH\fP:\fIMM\fP:\fISS\fP.
  116. .IP "\fR%u\fR" 8
  117. Weekday as a decimal number [1,7] (1=Monday).
  118. .IP "\fR%U\fR" 8
  119. Week of the year (Sunday as the first day of the week) as a decimal
  120. number [00,53]. All days in a new year preceding the first Sunday
  121. shall be considered to be in week 0.
  122. .IP "\fR%V\fR" 8
  123. Week of the year (Monday as the first day of the week) as a decimal
  124. number [01,53]. If the week containing January 1 has four or more
  125. days in the new year, then it shall be considered week 1; otherwise, it
  126. shall be the last week of the previous year, and the next week shall be
  127. week 1.
  128. .IP "\fR%w\fR" 8
  129. Weekday as a decimal number [0,6] (0=Sunday).
  130. .IP "\fR%W\fR" 8
  131. Week of the year (Monday as the first day of the week) as a decimal
  132. number [00,53]. All days in a new year preceding the first Monday
  133. shall be considered to be in week 0.
  134. .IP "\fR%x\fR" 8
  135. Locale's appropriate date representation.
  136. .IP "\fR%X\fR" 8
  137. Locale's appropriate time representation.
  138. .IP "\fR%y\fR" 8
  139. Year within century [00,99].
  140. .IP "\fR%Y\fR" 8
  141. Year with century as a decimal number.
  142. .IP "\fR%Z\fR" 8
  143. Timezone name, or no characters if no timezone is determinable.
  144. .IP "\fR%%\fR" 8
  145. A
  146. <percent-sign>
  147. character.
  148. .P
  149. See the Base Definitions volume of POSIX.1\(hy2017,
  150. .IR "Section 7.3.5" ", " "LC_TIME"
  151. for the conversion specifier values in the POSIX locale.
  152. .SS "Modified Conversion Specifications"
  153. .P
  154. Some conversion specifiers can be modified by the
  155. .BR E
  156. and
  157. .BR O
  158. modifier characters to indicate a different format or specification as
  159. specified in the
  160. .IR LC_TIME
  161. locale description (see the Base Definitions volume of POSIX.1\(hy2017,
  162. .IR "Section 7.3.5" ", " "LC_TIME").
  163. If the corresponding keyword (see
  164. .BR era ,
  165. .BR era_year ,
  166. .BR era_d_fmt ,
  167. and
  168. .BR alt_digits
  169. in the Base Definitions volume of POSIX.1\(hy2017,
  170. .IR "Section 7.3.5" ", " "LC_TIME")
  171. is not specified or not supported for the current locale,
  172. the unmodified conversion specifier value shall be used.
  173. .IP "\fR%Ec\fR" 8
  174. Locale's alternative appropriate date and time representation.
  175. .IP "\fR%EC\fR" 8
  176. The name of the base year (period) in the locale's alternative
  177. representation.
  178. .IP "\fR%Ex\fR" 8
  179. Locale's alternative date representation.
  180. .IP "\fR%EX\fR" 8
  181. Locale's alternative time representation.
  182. .IP "\fR%Ey\fR" 8
  183. Offset from
  184. .BR %EC
  185. (year only) in the locale's alternative representation.
  186. .IP "\fR%EY\fR" 8
  187. Full alternative year representation.
  188. .IP "\fR%Od\fR" 8
  189. Day of month using the locale's alternative numeric symbols.
  190. .IP "\fR%Oe\fR" 8
  191. Day of month using the locale's alternative numeric symbols.
  192. .IP "\fR%OH\fR" 8
  193. Hour (24-hour clock) using the locale's alternative numeric symbols.
  194. .IP "\fR%OI\fR" 8
  195. Hour (12-hour clock) using the locale's alternative numeric symbols.
  196. .IP "\fR%Om\fR" 8
  197. Month using the locale's alternative numeric symbols.
  198. .IP "\fR%OM\fR" 8
  199. Minutes using the locale's alternative numeric symbols.
  200. .IP "\fR%OS\fR" 8
  201. Seconds using the locale's alternative numeric symbols.
  202. .IP "\fR%Ou\fR" 8
  203. Weekday as a number in the locale's alternative representation (Monday
  204. = 1).
  205. .IP "\fR%OU\fR" 8
  206. Week number of the year (Sunday as the first day of the week) using the
  207. locale's alternative numeric symbols.
  208. .IP "\fR%OV\fR" 8
  209. Week number of the year (Monday as the first day of the week, rules
  210. corresponding to
  211. .BR %V ),
  212. using the locale's alternative numeric symbols.
  213. .IP "\fR%Ow\fR" 8
  214. Weekday as a number in the locale's alternative representation (Sunday
  215. = 0).
  216. .IP "\fR%OW\fR" 8
  217. Week number of the year (Monday as the first day of the week) using the
  218. locale's alternative numeric symbols.
  219. .IP "\fR%Oy\fR" 8
  220. Year (offset from
  221. .BR %C )
  222. in alternative representation.
  223. .RE
  224. .IP "\fImmddhhmm\fB[[\fIcc\fB]\fIyy\fB]\fR" 10
  225. .br
  226. Attempt to set the system date and time from the value given in the
  227. operand. This is only possible if the user has appropriate privileges
  228. and the system permits the setting of the system date and time. The
  229. first
  230. .IR mm
  231. is the month (number);
  232. .IR dd
  233. is the day (number);
  234. .IR hh
  235. is the hour (number, 24-hour system); the second
  236. .IR mm
  237. is the minute (number);
  238. .IR cc
  239. is the century and is the first two digits of the year (this is
  240. optional);
  241. .IR yy
  242. is the last two digits of the year and is optional. If century is not
  243. specified, then values in the range [69,99] shall refer to years
  244. 1969 to 1999 inclusive, and values in the range [00,68] shall refer
  245. to years 2000 to 2068 inclusive. The current year is the default if
  246. .IR yy
  247. is omitted.
  248. .RS 10
  249. .TP 10
  250. .BR Note:
  251. It is expected that in a future version of this standard the default
  252. century inferred from a 2-digit year will change. (This would apply
  253. to all commands accepting a 2-digit year as input.)
  254. .P
  255. .RE
  256. .SH STDIN
  257. Not used.
  258. .SH "INPUT FILES"
  259. None.
  260. .SH "ENVIRONMENT VARIABLES"
  261. The following environment variables shall affect the execution of
  262. .IR date :
  263. .IP "\fILANG\fP" 10
  264. Provide a default value for the internationalization variables that are
  265. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  266. .IR "Section 8.2" ", " "Internationalization Variables"
  267. for the precedence of internationalization variables used to determine
  268. the values of locale categories.)
  269. .IP "\fILC_ALL\fP" 10
  270. If set to a non-empty string value, override the values of all the
  271. other internationalization variables.
  272. .IP "\fILC_CTYPE\fP" 10
  273. Determine the locale for the interpretation of sequences of bytes of
  274. text data as characters (for example, single-byte as opposed to
  275. multi-byte characters in arguments).
  276. .IP "\fILC_MESSAGES\fP" 10
  277. .br
  278. Determine the locale that should be used to affect the format and
  279. contents of diagnostic messages written to standard error.
  280. .IP "\fILC_TIME\fP" 10
  281. Determine the format and contents of date and time strings written by
  282. .IR date .
  283. .IP "\fINLSPATH\fP" 10
  284. Determine the location of message catalogs for the processing of
  285. .IR LC_MESSAGES .
  286. .IP "\fITZ\fP" 10
  287. Determine the timezone in which the time and date are written, unless
  288. the
  289. .BR \-u
  290. option is specified. If the
  291. .IR TZ
  292. variable is unset or null and
  293. .BR \-u
  294. is not specified, an unspecified system default timezone is used.
  295. .SH "ASYNCHRONOUS EVENTS"
  296. Default.
  297. .SH STDOUT
  298. When no formatting operand is specified, the output in the POSIX locale
  299. shall be equivalent to specifying:
  300. .sp
  301. .RS 4
  302. .nf
  303. date "+%a %b %e %H:%M:%S %Z %Y"
  304. .fi
  305. .P
  306. .RE
  307. .SH STDERR
  308. The standard error shall be used only for diagnostic messages.
  309. .SH "OUTPUT FILES"
  310. None.
  311. .SH "EXTENDED DESCRIPTION"
  312. None.
  313. .SH "EXIT STATUS"
  314. The following exit values shall be returned:
  315. .IP "\00" 6
  316. The date was written successfully.
  317. .IP >0 6
  318. An error occurred.
  319. .SH "CONSEQUENCES OF ERRORS"
  320. Default.
  321. .LP
  322. .IR "The following sections are informative."
  323. .SH "APPLICATION USAGE"
  324. Conversion specifiers are of unspecified format when not in the POSIX
  325. locale. Some of them can contain
  326. <newline>
  327. characters in some locales, so it may be difficult to use the format
  328. shown in standard output for parsing the output of
  329. .IR date
  330. in those locales.
  331. .P
  332. The range of values for
  333. .BR %S
  334. extends from 0 to 60 seconds to accommodate the occasional leap second.
  335. .P
  336. Although certain of the conversion specifiers in the POSIX locale (such
  337. as the name of the month) are shown with initial capital letters, this
  338. need not be the case in other locales. Programs using these fields may
  339. need to adjust the capitalization if the output is going to be used at
  340. the beginning of a sentence.
  341. .P
  342. The date string formatting capabilities are intended for use in
  343. Gregorian-style calendars, possibly with a different starting year (or
  344. years). The
  345. .BR %x
  346. and
  347. .BR %c
  348. conversion specifications, however, are intended for local
  349. representation; these may be based on a different, non-Gregorian
  350. calendar.
  351. .P
  352. The
  353. .BR %C
  354. conversion specification was introduced to allow a fallback for the
  355. .BR %EC
  356. (alternative year format base year); it can be viewed as the base of
  357. the current subdivision in the Gregorian calendar. The century number
  358. is calculated as the year divided by 100 and truncated to an integer;
  359. it should not be confused with the use of ordinal numbers for centuries
  360. (for example, ``twenty-first century''.) Both the
  361. .BR %Ey
  362. and
  363. .BR %y
  364. can then be viewed as the offset from
  365. .BR %EC
  366. and
  367. .BR %C ,
  368. respectively.
  369. .P
  370. The
  371. .BR E
  372. and
  373. .BR O
  374. modifiers modify the traditional conversion specifiers, so that they
  375. can always be used, even if the implementation (or the current locale)
  376. does not support the modifier.
  377. .P
  378. The
  379. .BR E
  380. modifier supports alternative date formats, such as the Japanese
  381. Emperor's Era, as long as these are based on the Gregorian calendar
  382. system. Extending the
  383. .BR E
  384. modifiers to other date elements may provide an implementation-defined
  385. extension capable of supporting other calendar systems, especially in
  386. combination with the
  387. .BR O
  388. modifier.
  389. .P
  390. The
  391. .BR O
  392. modifier supports time and date formats using the locale's alternative
  393. numerical symbols, such as Kanji or Hindi digits or ordinal number
  394. representation.
  395. .P
  396. Non-European locales, whether they use Latin digits in computational
  397. items or not, often have local forms of the digits for use in date
  398. formats. This is not totally unknown even in Europe; a variant of dates
  399. uses Roman numerals for the months: the third day of September 1991
  400. would be written as 3.IX.1991. In Japan, Kanji digits are regularly
  401. used for dates; in Arabic-speaking countries, Hindi digits are used.
  402. The
  403. .BR %d ,
  404. .BR %e ,
  405. .BR %H ,
  406. .BR %I ,
  407. .BR %m ,
  408. .BR %S ,
  409. .BR %U ,
  410. .BR %w ,
  411. .BR %W ,
  412. and
  413. .BR %y
  414. conversion specifications always return the date and time field in
  415. Latin digits (that is, 0 to 9). The
  416. .BR %O
  417. modifier was introduced to support the use for display purposes of
  418. non-Latin digits. In the
  419. .IR LC_TIME
  420. category in
  421. .IR localedef ,
  422. the optional
  423. .BR alt_digits
  424. keyword is intended for this purpose. As an example, assume the
  425. following (partial)
  426. .IR localedef
  427. source:
  428. .sp
  429. .RS 4
  430. .nf
  431. alt_digits "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \e
  432. "IX";"X";"XI";"XII"
  433. d_fmt "%e.%Om.%Y"
  434. .fi
  435. .P
  436. .RE
  437. .P
  438. With the above date, the command:
  439. .sp
  440. .RS 4
  441. .nf
  442. date "+%x"
  443. .fi
  444. .P
  445. .RE
  446. .P
  447. would yield 3.IX.1991. With the same
  448. .BR d_fmt ,
  449. but without the
  450. .BR alt_digits ,
  451. the command would yield 3.9.1991.
  452. .SH EXAMPLES
  453. .IP " 1." 4
  454. The following are input/output examples of
  455. .IR date
  456. used at arbitrary times in the POSIX locale:
  457. .RS 4
  458. .sp
  459. .RS 4
  460. .nf
  461. \fB$ \fRdate
  462. \fBTue Jun 26 09:58:10 PDT 1990
  463. .P
  464. \fB$ \fRdate "+DATE: %m/%d/%y%nTIME: %H:%M:%S"
  465. \fBDATE: 11/02/91
  466. \fBTIME: 13:36:16
  467. .P
  468. \fB$ \fRdate "+TIME: %r"
  469. \fBTIME: 01:36:32 PM\fR
  470. .fi
  471. .P
  472. .RE
  473. .RE
  474. .IP " 2." 4
  475. Examples for Denmark, where the default date and time format is
  476. .BR %a
  477. .BR %d
  478. .BR %b
  479. .BR %Y
  480. .BR %T
  481. .BR %Z :
  482. .RS 4
  483. .sp
  484. .RS 4
  485. .nf
  486. \fB$ \fRLANG=da_DK.iso_8859-1 date
  487. \fBons 02 okt 1991 15:03:32 CET
  488. .P
  489. \fB$ \fRLANG=da_DK.iso_8859-1 \e
  490. date "+DATO: %A den %e. %B %Y%nKLOKKEN: %H:%M:%S"
  491. \fBDATO: onsdag den 2. oktober 1991
  492. \fBKLOKKEN: 15:03:56\fR
  493. .fi
  494. .P
  495. .RE
  496. .RE
  497. .IP " 3." 4
  498. Examples for Germany, where the default date and time format is
  499. .BR %a
  500. .BR %d .\c
  501. .BR %h .\c
  502. .BR %Y ,
  503. .BR %T
  504. .BR %Z :
  505. .RS 4
  506. .sp
  507. .RS 4
  508. .nf
  509. \fB$ \fRLANG=De_DE.88591 date
  510. \fBMi 02.Okt.1991, 15:01:21 MEZ
  511. .P
  512. \fB$ \fRLANG=De_DE.88591 date "+DATUM: %A, %d. %B %Y%nZEIT: %H:%M:%S"
  513. \fBDATUM: Mittwoch, 02. Oktober 1991
  514. \fBZEIT: 15:02:02\fR
  515. .fi
  516. .P
  517. .RE
  518. .RE
  519. .IP " 4." 4
  520. Examples for France, where the default date and time format is
  521. .BR %a
  522. .BR %d
  523. .BR %h
  524. .BR %Y
  525. .BR %Z
  526. .BR %T :
  527. .RS 4
  528. .sp
  529. .RS 4
  530. .nf
  531. \fB$ \fRLANG=Fr_FR.88591 date
  532. \fBMer 02 oct 1991 MET 15:03:32
  533. .P
  534. \fB$ \fRLANG=Fr_FR.88591 date "+JOUR: %A %d %B %Y%nHEURE: %H:%M:%S"
  535. \fBJOUR: Mercredi 02 octobre 1991
  536. \fBHEURE: 15:03:56\fR
  537. .fi
  538. .P
  539. .RE
  540. .RE
  541. .SH RATIONALE
  542. Some of the new options for formatting are from the ISO\ C standard. The
  543. .BR \-u
  544. option was introduced to allow portable access to Coordinated Universal
  545. Time (UTC).
  546. The string
  547. .BR \(dqGMT0\(dq
  548. is allowed as an equivalent
  549. .IR TZ
  550. value to be compatible with all of the systems using the BSD
  551. implementation, where this option originated.
  552. .P
  553. The
  554. .BR %e
  555. format conversion specification (adopted from System V) was added
  556. because the ISO\ C standard conversion specifications did not provide any way to
  557. produce the historical default
  558. .IR date
  559. output during the first nine days of any month.
  560. .P
  561. There are two varieties of day and week numbering supported (in
  562. addition to any others created with the locale-dependent
  563. .BR %E
  564. and
  565. .BR %O
  566. modifier characters):
  567. .IP " *" 4
  568. The historical variety in which Sunday is the first day of the week and
  569. the weekdays preceding the first Sunday of the year are considered week
  570. 0. These are represented by
  571. .BR %w
  572. and
  573. .BR %U .
  574. A variant of this is
  575. .BR %W ,
  576. using Monday as the first day of the week, but still referring to week
  577. 0. This view of the calendar was retained because so many historical
  578. applications depend on it and the ISO\ C standard
  579. \fIstrftime\fR()
  580. function, on which many
  581. .IR date
  582. implementations are based, was defined in this way.
  583. .IP " *" 4
  584. The international standard, based on the ISO\ 8601:\|2004 standard where Monday is the
  585. first weekday and the algorithm for the first week number is more
  586. complex: If the week (Monday to Sunday) containing January 1 has four
  587. or more days in the new year, then it is week 1; otherwise, it is week
  588. 53 of the previous year, and the next week is week 1. These are
  589. represented by the new conversion specifications
  590. .BR %u
  591. and
  592. .BR %V ,
  593. added as a result of international comments.
  594. .SH "FUTURE DIRECTIONS"
  595. None.
  596. .SH "SEE ALSO"
  597. The Base Definitions volume of POSIX.1\(hy2017,
  598. .IR "Section 7.3.5" ", " "LC_TIME",
  599. .IR "Chapter 8" ", " "Environment Variables",
  600. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  601. .P
  602. The System Interfaces volume of POSIX.1\(hy2017,
  603. .IR "\fIfprintf\fR\^(\|)",
  604. .IR "\fIstrftime\fR\^(\|)"
  605. .\"
  606. .SH COPYRIGHT
  607. Portions of this text are reprinted and reproduced in electronic form
  608. from IEEE Std 1003.1-2017, Standard for Information Technology
  609. -- Portable Operating System Interface (POSIX), The Open Group Base
  610. Specifications Issue 7, 2018 Edition,
  611. Copyright (C) 2018 by the Institute of
  612. Electrical and Electronics Engineers, Inc and The Open Group.
  613. In the event of any discrepancy between this version and the original IEEE and
  614. The Open Group Standard, the original IEEE and The Open Group Standard
  615. is the referee document. The original Standard can be obtained online at
  616. http://www.opengroup.org/unix/online.html .
  617. .PP
  618. Any typographical or formatting errors that appear
  619. in this page are most likely
  620. to have been introduced during the conversion of the source files to
  621. man page format. To report such errors, see
  622. https://www.kernel.org/doc/man-pages/reporting_bugs.html .