logo

utils-std

Collection of commonly available Unix tools git clone https://anongit.hacktivis.me/git/utils-std.git/

date.1.in (3708B)

    

  1. .\" utils-std: Collection of commonly available Unix tools
  2. .\" Copyright 2017 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
  3. .\" SPDX-License-Identifier: MPL-2.0
  4. .Dd April 6, 2025
  5. .Dt DATE 1
  6. .Os
  7. .Sh NAME
  8. .Nm date
  9. .Nd display date and time
  10. .Sh SYNOPSIS
  11. .Nm
  12. .Op Fl jRu
  13. .Op Fl I Ar iso_fmt
  14. .Op Fl d Ar datetime | Fl r Ar epoch
  15. .Op Cm + Ns Ar format
  16. .Nm
  17. .Op Fl jRu
  18. .Op Fl I Ar iso_fmt
  19. .Ar mmddHHMM Ns Oo Oo Ar CC Oc Ns Ar yy Oc
  20. .Op Cm + Ns Ar format
  21. .Nm
  22. .Op Fl jRu
  23. .Op Fl I Ar iso_fmt
  24. .Fl f Ar now_format
  25. .Ar now
  26. .Op Cm + Ns Ar format
  27. .Sh DESCRIPTION
  28. When
  29. .Nm
  30. is invoked without arguments it displays the current time
  31. Otherwise, depending on the options specified,
  32. will print the datetime in a user-defined way.
  33. .Sh OPTIONS
  34. .Bl -tag -width Ds
  35. .It Fl d Ar datetime
  36. Use
  37. .Ar datetime
  38. instead of current time, see
  39. .Sx DATETIME FORMAT
  40. section for more details.
  41. .It Fl f Ar now_format
  42. Use
  43. .Ar now_format
  44. as the
  45. .Xr strptime 3
  46. format string for
  47. .Ar now ,
  48. which will be used instead of the current time.
  49. .It Fl I Ar iso_fmt
  50. Set the ISO-8601 resolution to format at with setting
  51. .Ar iso_fmt
  52. to one of the following values:
  53. .Bl -tag -width m_inutes_
  54. .It Ar d Ns Op Ar ate
  55. date, equivalent to +%Y-%m-%d
  56. .It Ar h Ns Op Ar ours
  57. hours, equivalent to +%Y-%m-%dT%H%:z
  58. .It Ar m Ns Op Ar inutes
  59. minutes, equivalent to +%Y-%m-%dT%H:%M%:z
  60. .It Ar s Ns Op Ar econds
  61. seconds, equivalent to +%Y-%m-%dT%H:%M:%S%:z
  62. .It Ar n Ns Op Ar s
  63. nano-seconds, equivalent to +%Y-%m-%dT%H:%M:%S,%N%:z
  64. .El
  65. .It Fl j
  66. Do no set the system date.
  67. This allows to use the
  68. .Fl f
  69. flag to convert one datetime to another.
  70. .It Fl u
  71. Use UTC (coordinated universal time) instead of the local time.
  72. .It Fl r Ar epoch
  73. Use
  74. .Ar epoch
  75. (seconds relative to 1970-01-01 00:00:00 UTC)
  76. instead of current time.
  77. .It Fl R
  78. Set the default value of
  79. .Ar format
  80. to match RFC5322 (Email / Internet Message Format).
  81. .It Ar mmddHHMM Ns Oo Oo Ar CC Oc Ns Ar yy Oc
  82. Sets custom datetime, if
  83. .Fl j
  84. isn't set, the system time is also set.
  85. .Pp
  86. Each letters corresponds to:
  87. .Bl -tag -width mm -compact
  88. .It mm
  89. months aka %m
  90. .It dd
  91. days aka %d
  92. .It HH
  93. hours aka %H
  94. .It MM
  95. minutes aka %M
  96. .It CC
  97. centuries aka %C
  98. .It yy
  99. century-less years aka %y
  100. .El
  101. .Pp
  102. For example 072505542024 corresponds to 2024-07-25T05:54,
  103. as you can verify with the following command:
  104. .Dl date -j 072505542024 +%Y-%m-%dT%H:%M
  105. .It Cm + Ns Ar format
  106. Set the displayed datetime in
  107. .Xr strftime 3
  108. format,
  109. with additionally:
  110. .Bl -tag -width _::z -compact
  111. .It %N
  112. for nanoseconds,
  113. .It %:z
  114. for hour:minutes timezone offset (±ZZ:ZZ)
  115. .It %::z
  116. for hour:minutes:seconds timezone offset (±ZZ:ZZ:ZZ)
  117. .El
  118. .Pp
  119. Otherwise defaults to
  120. .Ql %c
  121. when unspecified.
  122. .El
  123. .Sh DATETIME FORMAT
  124. include(libutils/datetime_parse.mdoc)
  125. .Sh ENVIRONMENT
  126. Look at the manual page of
  127. .Xr strftime 3
  128. for the environment variables, typical ones are
  129. .Ev TZ ,
  130. .Ev LC_TIME
  131. and
  132. .Ev LC_ALL
  133. but this depends on your system.
  134. .Sh EXIT STATUS
  135. .Ex -std
  136. .Sh SEE ALSO
  137. .Xr clock_settime 3 ,
  138. .Xr strftime 3
  139. .Sh STANDARDS
  140. .Nm
  141. should be compliant with the
  142. IEEE Std 1003.1-2024 (“POSIX.1”)
  143. specification.
  144. .Pp
  145. The
  146. .Fl d
  147. and
  148. .Fl R
  149. options are present for compatibility with other modern systems such as
  150. NetBSD, BusyBox, and GNU coreutils.
  151. .br
  152. The
  153. .Fl r
  154. option is inspired from BSD and illumos,
  155. .Fl f
  156. and
  157. .Fl j
  158. options are inspired by FreeBSD and NetBSD.
  159. .Pp
  160. The %N, %:z, %::z formats are extensions inspired from GNU coreutils.
  161. .Pp
  162. The
  163. .Fl I
  164. option was added for compatibility with GNU coreutils, BusyBox, FreeBSD 12.0+.
  165. .Sh HISTORY
  166. The
  167. .Fl R ,
  168. .Fl d ,
  169. .Fl f ,
  170. .Fl j ,
  171. and
  172. .Fl r
  173. options were present in utils-std 0.0.1.
  174. The
  175. .Fl I
  176. option and %N and %:z formats were added in utils-std 0.0.2.
  177. .Sh AUTHORS
  178. .An Haelwenn (lanodan) Monnier Aq Mt contact+utils@hacktivis.me