oasis-root

date.1 (4915B)

.\" utils-std: Collection of commonly available Unix tools
.\" Copyright 2017 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
.\" SPDX-License-Identifier: MPL-2.0
.Dd April 6, 2025
.Dt DATE 1
.Os
.Sh NAME
.Nm date
.Nd display date and time
.Sh SYNOPSIS
.Nm
.Op Fl jRu
.Op Fl I Ar iso_fmt
.Op Fl d Ar datetime | Fl r Ar epoch
.Op Cm + Ns Ar format
.Nm
.Op Fl jRu
.Op Fl I Ar iso_fmt
.Ar mmddHHMM Ns Oo Oo Ar CC Oc Ns Ar yy Oc
.Op Cm + Ns Ar format
.Nm
.Op Fl jRu
.Op Fl I Ar iso_fmt
.Fl f Ar now_format
.Ar now
.Op Cm + Ns Ar format
.Sh DESCRIPTION
When
.Nm
is invoked without arguments it displays the current time
Otherwise, depending on the options specified,
will print the datetime in a user-defined way.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl d Ar datetime
Use
.Ar datetime
instead of current time, see
.Sx DATETIME FORMAT
section for more details.
.It Fl f Ar now_format
Use
.Ar now_format
as the
.Xr strptime 3
format string for
.Ar now ,
which will be used instead of the current time.
.It Fl I Ar iso_fmt
Set the ISO-8601 resolution to format at with setting
.Ar iso_fmt
to one of the following values:
.Bl -tag -width m_inutes_
.It Ar d Ns Op Ar ate
date, equivalent to +%Y-%m-%d
.It Ar h Ns Op Ar ours
hours, equivalent to +%Y-%m-%dT%H%:z
.It Ar m Ns Op Ar inutes
minutes, equivalent to +%Y-%m-%dT%H:%M%:z
.It Ar s Ns Op Ar econds
seconds, equivalent to +%Y-%m-%dT%H:%M:%S%:z
.It Ar n Ns Op Ar s
nano-seconds, equivalent to +%Y-%m-%dT%H:%M:%S,%N%:z
.El
.It Fl j
Do no set the system date.
This allows to use the
.Fl f
flag to convert one datetime to another.
.It Fl u
Use UTC (coordinated universal time) instead of the local time.
.It Fl r Ar epoch
Use
.Ar epoch
(seconds relative to 1970-01-01 00:00:00 UTC)
instead of current time.
.It Fl R
Set the default value of
.Ar format
to match RFC5322 (Email / Internet Message Format).
.It Ar mmddHHMM Ns Oo Oo Ar CC Oc Ns Ar yy Oc
Sets custom datetime, if
.Fl j
isn't set, the system time is also set.
.Pp
Each letters corresponds to:
.Bl -tag -width mm -compact
.It mm
months aka %m
.It dd
days aka %d
.It HH
hours aka %H
.It MM
minutes aka %M
.It CC
centuries aka %C
.It yy
century-less years aka %y
.El
.Pp
For example 072505542024 corresponds to 2024-07-25T05:54,
as you can verify with the following command:
.Dl date -j 072505542024 +%Y-%m-%dT%H:%M
.It Cm + Ns Ar format
Set the displayed datetime in
.Xr strftime 3
format,
with additionally
%N for nanoseconds and %:z for colon-separated timezone (±ZZ:ZZ).
.br
Otherwise defaults to
.Ql %c
.El
.Sh DATETIME FORMAT
.\" utils-std: Collection of commonly available Unix tools
.\" Copyright 2017 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
.\" SPDX-License-Identifier: MPL-2.0
.\"
Multiple different but unambiguous formats are supported:
@epoch, Email, asctime, RFC3339.
.Ss @epoch
Leading @ (at) symbol followed by
the Unix timestamp (number of seconds before and after 1970-01-01 00:00:00Z),
for example
.Ql @1698791420
corresponds to 2023-10-31 23:30:20 UTC
.Ss Email
Also known as "Internet Message Format" (RFC5322, RFC2822, RFC822), for example:
.Bl -bullet -compact
.It
.Ql Fri, 21 Nov 1997 09:55:06 -0600
.It
.Ql 21 Nov 97 09:55:06 GMT
.El
.Ss asctime
Output format of
.Xr asctime 3 ,
for example:
.Ql Sun Sep 16 01:03:52 1973
.Ss RFC3339
Profile of ISO\ 8601:1988, found in modern protocols and file formats.
Formatted as
.Ql YYYY-MM-DDThh:mm:SS[frac][tz] ,
where:
.Bl -tag -width Ds
.It Ql YYYY-MM-DD
Corresponds to %Y-%m-%d of
.Xr strptime 3 .
.It Ql T
Is either
.Ql T
or a space.
.It Ql [frac]
Is either empty, or fractional seconds starting with either a comma
.Pq \&,
or a period
.Pq \&. .
.It Ql [tz]
When empty it corresponds to local time.
Otherwise it can be an UTC offset in the format
.Ql [+-]HH:?MM
or the letter
.Qq Z ,
signifying UTC.
.El
.Pp
Some examples:
.Bl -bullet -compact
.It
.Ql 2003-06-02T13:37:42.713Z
.It
.Ql 1971-01-02T03:04:05.678+0900
.El
.Sh ENVIRONMENT
Look at the manual page of
.Xr strftime 3
for the environment variables, typical ones are
.Ev TZ ,
.Ev LC_TIME
and
.Ev LC_ALL
but this depends on your system.
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr clock_settime 3 ,
.Xr strftime 3
.Sh STANDARDS
.Nm
should be compliant with the
IEEE Std 1003.1-2024 (“POSIX.1”)
specification.
.Pp
The
.Fl d
and
.Fl R
options are present for compatibility with other modern systems such as
NetBSD, BusyBox, and GNU coreutils.
.br
The
.Fl r
option is inspired from BSD and illumos,
.Fl f
and
.Fl j
options are inspired by FreeBSD and NetBSD.
.Pp
The %N and %:z formats are extensions inspired from GNU coreutils.
.Pp
The
.Fl I
option was added for compatibility with GNU coreutils, BusyBox, FreeBSD 12.0+.
.Sh HISTORY
The
.Fl R ,
.Fl d ,
.Fl f ,
.Fl j ,
and
.Fl r
options were present in utils-std 0.0.1.
The
.Fl I
option and %N and %:z formats were added in utils-std 0.0.2.
.Sh AUTHORS
.An Haelwenn (lanodan) Monnier Aq Mt contact+utils@hacktivis.me