logo

utils-std

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

date.1.in (3581B)

    

  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. %N for nanoseconds and %:z for colon-separated timezone (±ZZ:ZZ).
  111. .br
  112. Otherwise defaults to
  113. .Ql %c
  114. .El
  115. .Sh DATETIME FORMAT
  116. include(libutils/datetime_parse.mdoc)
  117. .Sh ENVIRONMENT
  118. Look at the manual page of
  119. .Xr strftime 3
  120. for the environment variables, typical ones are
  121. .Ev TZ ,
  122. .Ev LC_TIME
  123. and
  124. .Ev LC_ALL
  125. but this depends on your system.
  126. .Sh EXIT STATUS
  127. .Ex -std
  128. .Sh SEE ALSO
  129. .Xr clock_settime 3 ,
  130. .Xr strftime 3
  131. .Sh STANDARDS
  132. .Nm
  133. should be compliant with the
  134. IEEE Std 1003.1-2024 (“POSIX.1”)
  135. specification.
  136. .Pp
  137. The
  138. .Fl d
  139. and
  140. .Fl R
  141. options are present for compatibility with other modern systems such as
  142. NetBSD, BusyBox, and GNU coreutils.
  143. .br
  144. The
  145. .Fl r
  146. option is inspired from BSD and illumos,
  147. .Fl f
  148. and
  149. .Fl j
  150. options are inspired by FreeBSD and NetBSD.
  151. .Pp
  152. The %N and %:z formats are extensions inspired from GNU coreutils.
  153. .Pp
  154. The
  155. .Fl I
  156. option was added for compatibility with GNU coreutils, BusyBox, FreeBSD 12.0+.
  157. .Sh HISTORY
  158. The
  159. .Fl R ,
  160. .Fl d ,
  161. .Fl f ,
  162. .Fl j ,
  163. and
  164. .Fl r
  165. options were present in utils-std 0.0.1.
  166. The
  167. .Fl I
  168. option and %N and %:z formats were added in utils-std 0.0.2.
  169. .Sh AUTHORS
  170. .An Haelwenn (lanodan) Monnier Aq Mt contact+utils@hacktivis.me