Add 'corebinutils/date/' from commit 'ae4c58645a13317bb8540d47f8f7cfa768f17eb2'

git-subtree-dir: corebinutils/date
git-subtree-mainline: d12e80797cf0ae7a0bd3cd0cd7948f532f3181ac
git-subtree-split: ae4c58645a13317bb8540d47f8f7cfa768f17eb2

1 files changed, 660 insertions, 0 deletions

diff --git a/corebinutils/date/date.1 b/corebinutils/date/date.1
new file mode 100644
index 0000000000..21ec516718
--- /dev/null
+++ b/corebinutils/date/date.1
@@ -0,0 +1,660 @@
+.\"-
+.\" Copyright (c) 1980, 1990, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Copyright (c) 2026
+.\"  Project Tick. All rights reserved.
+.\"
+.\" This code is derived from software contributed to Berkeley by
+.\" the Institute of Electrical and Electronics Engineers, Inc.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd November 10, 2025
+.Dt DATE 1
+.Os
+.Sh NAME
+.Nm date
+.Nd display or set date and time
+.Sh SYNOPSIS
+.\" Display time.
+.Nm
+.Op Fl nRu
+.Op Fl z Ar output_zone
+.Op Fl I Ns Op Ar FMT
+.Op Fl r Ar filename
+.Op Fl r Ar seconds
+.Oo
+.Sm off
+.Fl v
+.Op Cm + | -
+.Ar val Op Cm y | m | w | d | H | M | S
+.Sm on
+.Oc
+.Op Cm + Ns Ar output_fmt
+.\" Set time with the default input format.
+.Nm
+.Op Fl jnRu
+.Op Fl z Ar output_zone
+.Op Fl I Ns Op Ar FMT
+.Oo
+.Sm off
+.Fl v
+.Op Cm + | -
+.Ar val Op Cm y | m | w | d | H | M | S
+.Sm on
+.Oc
+.Sm off
+.Oo Oo Oo Oo Oo
+.Ar cc Oc
+.Ar yy Oc
+.Ar mm Oc
+.Ar dd Oc
+.Ar HH
+.Oc Ar MM Op Cm \&. Ar SS
+.Sm on
+.Op Cm + Ns Ar output_fmt
+.\" Set time with the user-provided input format.
+.Nm
+.Op Fl jnRu
+.Op Fl z Ar output_zone
+.Op Fl I Ns Op Ar FMT
+.Oo
+.Sm off
+.Fl v
+.Op Cm + | -
+.Ar val Op Cm y | m | w | d | H | M | S
+.Sm on
+.Oc
+.Fl f Ar input_fmt
+.Ar new_date
+.Op Cm + Ns Ar output_fmt
+.Sh DESCRIPTION
+When invoked without arguments, the
+.Nm
+utility displays the current date and time.
+Otherwise, depending on the options specified,
+.Nm
+will set the date and time or print it in a user-defined way.
+.Pp
+The
+.Nm
+utility displays the date and time read from the kernel clock.
+When used to set the date and time,
+both the kernel clock and the hardware clock are updated.
+.Pp
+Only the superuser may set the date,
+and if the system securelevel (see
+.Xr securelevel 7 )
+is greater than 1,
+the time may not be changed by more than 1 second.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl f Ar input_fmt
+Use
+.Ar input_fmt
+as the format string to parse the
+.Ar new_date
+provided rather than using the default
+.Sm off
+.Oo Oo Oo Oo Oo
+.Ar cc Oc
+.Ar yy Oc
+.Ar mm Oc
+.Ar dd Oc
+.Ar HH
+.Oc Ar MM Op Cm \&. Ar SS
+.Sm on
+format.
+Parsing is done using
+.Xr strptime 3 .
+.It Fl I Ns Op Ar FMT
+Use extended
+.St -iso8601
+output format.
+.Ar FMT
+may be omitted, in which case the default is
+.Cm date .
+Valid
+.Ar FMT
+values are
+.Cm date ,
+.Cm hours ,
+.Cm minutes ,
+.Cm seconds ,
+and
+.Cm ns
+.Pq for nanoseconds .
+The date and time is formatted to the specified precision.
+When
+.Ar FMT
+is
+.Cm hours
+.Po or the more precise
+.Cm minutes ,
+.Cm seconds ,
+or
+.Cm ns Pc ,
+the extended
+.St -iso8601
+format includes the timezone offset.
+.It Fl j
+Do not try to set the date.
+This allows you to use the
+.Fl f
+flag in addition to the
+.Cm +
+option to convert one date format to another.
+Note that any date or time components unspecified by the
+.Fl f
+format string take their values from the current time.
+.It Fl n
+Obsolete flag, accepted and ignored for compatibility.
+.It Fl R
+Use RFC 2822 date and time output format.
+This is equivalent to using
+.Ql %a, %d %b %Y \&%T %z
+as
+.Ar output_fmt
+while
+.Ev LC_TIME
+is set to the
+.Dq C
+locale .
+.It Fl r Ar seconds
+Print the date and time represented by
+.Ar seconds ,
+where
+.Ar seconds
+is the number of seconds since the Unix Epoch
+(00:00:00 UTC, January 1, 1970;
+see
+.Xr time 3 ) ,
+and can be specified in decimal, octal, or hex.
+.It Fl r Ar filename
+Print the date and time of the last modification of
+.Ar filename .
+.It Fl u
+Display or set the date in UTC (Coordinated Universal) time.
+By default
+.Nm
+displays the time in the time zone described by
+.Pa /etc/localtime
+or the
+.Ev TZ
+environment variable.
+.It Fl z Ar output_zone
+Just before printing the time, change to the specified timezone;
+see the description of
+.Ev TZ
+below.
+This can be used with
+.Fl j
+to easily convert time specifications from one zone to another.
+.It Xo
+.Fl v
+.Sm off
+.Op Cm + | -
+.Ar val Op Cm y | m | w | d | H | M | S
+.Sm on
+.Xc
+Adjust (i.e., take the current date and display the result of the
+adjustment; not actually set the date) the second, minute, hour, month
+day, week day, month or year according to
+.Ar val .
+If
+.Ar val
+is preceded by a plus or minus sign,
+the date is adjusted forward or backward according to the remaining string,
+otherwise the relevant part of the date is set.
+The date can be adjusted as many times as required using these flags.
+Flags are processed in the order given.
+.Pp
+When setting values
+(rather than adjusting them),
+seconds are in the range 0-59, minutes are in the range 0-59, hours are
+in the range 0-23, month days are in the range 1-31, week days are in the
+range 0-6 (Sun-Sat),
+months are in the range 1-12 (Jan-Dec)
+and years are in a limited range depending on the platform.
+.Pp
+On i386, years are in the range 69-38 representing 1969-2038.
+On every other platform, years 0-68 are accepted and represent 2000-2068, and
+69-99 are accepted and represent 1969-1999.
+In both cases, years between 100 and 1900 (both included) are accepted and
+interpreted as relative to 1900 of the Gregorian calendar with a limit of 138 on
+i386 and a much higher limit on every other platform.
+Years starting at 1901 are also accepted, and are interpreted as absolute years.
+.Pp
+If
+.Ar val
+is numeric, one of either
+.Cm y ,
+.Cm m ,
+.Cm w ,
+.Cm d ,
+.Cm H ,
+.Cm M
+or
+.Cm S
+must be used to specify which part of the date is to be adjusted.
+.Pp
+The week day or month may be specified using a name rather than a
+number.
+If a name is used with the plus
+(or minus)
+sign, the date will be put forwards
+(or backwards)
+to the next
+(previous)
+date that matches the given week day or month.
+This will not adjust the date,
+if the given week day or month is the same as the current one.
+.Pp
+When a date is adjusted to a specific value or in units greater than hours,
+daylight savings time considerations are ignored.
+Adjustments in units of hours or less honor daylight saving time.
+So, assuming the current date is March 26, 0:30 and that the DST adjustment
+means that the clock goes forward at 01:00 to 02:00, using
+.Fl v No +1H
+will adjust the date to March 26, 2:30.
+Likewise, if the date is October 29, 0:30 and the DST adjustment means that
+the clock goes back at 02:00 to 01:00, using
+.Fl v No +3H
+will be necessary to reach October 29, 2:30.
+.Pp
+When the date is adjusted to a specific value that does not actually exist
+(for example March 26, 1:30 BST 2000 in the Europe/London timezone),
+the date will be silently adjusted forward in units of one hour until it
+reaches a valid time.
+When the date is adjusted to a specific value that occurs twice
+(for example October 29, 1:30 2000),
+the resulting timezone will be set so that the date matches the earlier of
+the two times.
+.Pp
+It is not possible to adjust a date to an invalid absolute day, so using
+the switches
+.Fl v No 31d Fl v No 12m
+will simply fail five months of the year.
+It is therefore usual to set the month before setting the day; using
+.Fl v No 12m Fl v No 31d
+always works.
+.Pp
+Adjusting the date by months is inherently ambiguous because
+a month is a unit of variable length depending on the current date.
+This kind of date adjustment is applied in the most intuitive way.
+First of all,
+.Nm
+tries to preserve the day of the month.
+If it is impossible because the target month is shorter than the present one,
+the last day of the target month will be the result.
+For example, using
+.Fl v No +1m
+on May 31 will adjust the date to June 30, while using the same option
+on January 30 will result in the date adjusted to the last day of February.
+This approach is also believed to make the most sense for shell scripting.
+Nevertheless, be aware that going forth and back by the same number of
+months may take you to a different date.
+.Pp
+Refer to the examples below for further details.
+.El
+.Pp
+An operand with a leading plus
+.Pq Sq +
+sign specifies a user-defined format string
+which specifies the format in which to display the date and time.
+The format string may contain any of the conversion specifications
+described in the
+.Xr strftime 3
+manual page, as well as any arbitrary text.
+.Pp
+The following extensions to the regular
+.Xr strftime 3
+syntax are supported:
+.Bl -tag -width "xxxx"
+.It Cm \&% Ns Ar n Ns Cm N
+Replaced by the
+.Ar n Ns
+-digit fractional part of the number of seconds since the Unix Epoch.
+If
+.Ar n
+is omitted or zero, a default value of 9 is used, resulting in a
+number with nanosecond resolution (hence the choice of the letter
+.Sq N
+for this conversion).
+Note that the underlying clock may not necessarily support nanosecond
+resolution.
+.It Cm \&%-N
+As above, but automatically choose the precision based on the reported
+resolution of the underlying clock.
+If the
+.Fl r
+option was specified, the default precision of 9 digits is used.
+.El
+.Pp
+A newline
+.Pq Ql \en
+character is always output after the characters specified by
+the format string.
+The format string for the default display is
+.Dq %+ .
+.Pp
+If an operand does not have a leading plus sign, it is interpreted as
+a value for setting the system's notion of the current date and time.
+The canonical representation for setting the date and time is:
+.Pp
+.Bl -tag -width Ds -compact -offset indent
+.It Ar cc
+Century
+(either 19 or 20)
+prepended to the abbreviated year.
+.It Ar yy
+Year in abbreviated form
+(e.g., 89 for 1989, 06 for 2006).
+.It Ar mm
+Numeric month, a number from 1 to 12.
+.It Ar dd
+Day, a number from 1 to 31.
+.It Ar HH
+Hour, a number from 0 to 23.
+.It Ar MM
+Minutes, a number from 0 to 59.
+.It Ar SS
+Seconds, a number from 0 to 60
+(59 plus a potential leap second).
+.El
+.Pp
+Everything but the minutes is optional.
+.Pp
+.Nm
+understands the time zone definitions from the IANA Time Zone Database,
+.Sy tzdata ,
+located in
+.Pa /usr/share/zoneinfo .
+Time changes for Daylight Saving Time, standard time, leap seconds
+and leap years are handled automatically.
+.Pp
+There are two ways to specify the time zone:
+.Pp
+If the file or symlink
+.Pa /etc/localtime
+exists, it is interpreted as a time zone definition file, usually in
+the directory hierarchy
+.Pa /usr/share/zoneinfo ,
+which contains the time zone definitions from
+.Sy tzdata .
+.Pp
+If the environment variable
+.Ev TZ
+is set, its value is interpreted as the name of a time zone definition
+file, either an absolute path or a relative path to a time zone
+definition in
+.Pa /usr/share/zoneinfo .
+The
+.Ev TZ
+variable overrides
+.Pa /etc/localtime .
+.Pp
+If the time zone definition file is invalid,
+.Nm
+silently reverts to UTC.
+.Pp
+Previous versions of
+.Nm
+included the
+.Fl d
+(set daylight saving time flag) and
+.Fl t
+(set negative time zone offset) options, but these details are now
+handled automatically by
+.Sy tzdata .
+Modern offsets are positive for time zones ahead of UTC and negative
+for time zones behind UTC, but like the obsolete
+.Fl t
+option, the
+.Sy tzdata
+files in the subdirectory
+.Pa /usr/share/zoneinfo/Etc
+still use an older convention where times ahead of UTC are considered
+negative.
+.Sh ENVIRONMENT
+The following environment variable affects the execution of
+.Nm :
+.Bl -tag -width Ds
+.It Ev TZ
+The timezone to use when displaying dates.
+The normal format is a pathname relative to
+.Pa /usr/share/zoneinfo .
+For example, the command
+.Dq TZ=America/Los_Angeles date
+displays the current time in California.
+The variable can also specify an absolute path.
+See
+.Xr environ 7
+for more information.
+.El
+.Sh FILES
+.Bl -tag -width /var/log/messages -compact
+.It Pa /etc/localtime
+Time zone information file for default system time zone.
+May be omitted, in which case the default time zone is UTC.
+.It Pa /usr/share/zoneinfo
+Directory containing time zone information files.
+.It Pa /var/log/messages
+Record of the user setting the time.
+.It Pa /var/log/utx.log
+Record of date resets and time changes.
+.El
+.Sh EXIT STATUS
+The
+.Nm
+utility exits 0 on success, 1 if unable to set the date, and 2
+if able to set the local date, but unable to set it globally.
+.Sh EXAMPLES
+The command
+.Pp
+.Dl "date +%s.%3N"
+.Pp
+will print the time elapsed since the Unix Epoch with millisecond
+precision.
+.Pp
+The command:
+.Pp
+.Dl "date ""+DATE: %Y-%m-%d%nTIME: %H:%M:%S"""
+.Pp
+will display:
+.Bd -literal -offset indent
+DATE: 1987-11-21
+TIME: 13:36:16
+.Ed
+.Pp
+In the Europe/London timezone, the command:
+.Pp
+.Dl "date -v1m -v+1y"
+.Pp
+will display:
+.Pp
+.Dl "Sun Jan  4 04:15:24 GMT 1998"
+.Pp
+where it is currently
+.Ql "Mon Aug  4 04:15:24 BST 1997" .
+.Pp
+The command:
+.Pp
+.Dl "date -v1d -v3m -v0y -v-1d"
+.Pp
+will display the last day of February in the year 2000:
+.Pp
+.Dl "Tue Feb 29 03:18:00 GMT 2000"
+.Pp
+So will the command:
+.Pp
+.Dl "date -v3m -v30d -v0y -v-1m"
+.Pp
+because there is no such date as the 30th of February.
+.Pp
+The command:
+.Pp
+.Dl "date -v1d -v+1m -v-1d -v-fri"
+.Pp
+will display the last Friday of the month:
+.Pp
+.Dl "Fri Aug 29 04:31:11 BST 1997"
+.Pp
+where it is currently
+.Ql "Mon Aug  4 04:31:11 BST 1997" .
+.Pp
+The command:
+.Pp
+.Dl "date 8506131627"
+.Pp
+sets the date to
+.Ql "June 13, 1985, 4:27 PM" .
+.Pp
+.Dl "date ""+%Y%m%d%H%M.%S"""
+.Pp
+may be used on one machine to print out the date
+suitable for setting on another.
+.Po Use
+.Ql "+%m%d%H%M%Y.%S"
+with GNU date on
+Linux .
+.Pc
+.Pp
+The command:
+.Pp
+.Dl "date 1432"
+.Pp
+sets the time to
+.Ql "2:32 PM" ,
+without modifying the date.
+.Pp
+The command
+.Pp
+.Dl "TZ=America/Los_Angeles date -Iseconds -r 1533415339"
+.Pp
+will display
+.Pp
+.Dl "2018-08-04T13:42:19-07:00"
+.Pp
+The command:
+.Pp
+.Dl "env LC_ALL=C date -j -f ""%a %b %d %T %Z %Y"" ""`env LC_ALL=C date`"" ""+%s"""
+.Pp
+can be used to parse the output from
+.Nm
+and express it in Epoch time.
+.Pp
+Finally the command
+.Pp
+.Dl "TZ=America/Los_Angeles date -z Europe/Paris -j 0900"
+.Pp
+will print the time in the
+.Dq Europe/Paris
+timezone when it is 9:00 in the
+.Dq America/Los_Angeles
+timezone.
+.Sh DIAGNOSTICS
+It is invalid to combine the
+.Fl I
+flag with either
+.Fl R
+or an output format
+.Dq ( + Ns ... )
+operand.
+If this occurs,
+.Nm
+prints:
+.Ql multiple output formats specified
+and exits with status 1.
+.Sh SEE ALSO
+.Xr locale 1 ,
+.Xr clock_gettime 2 ,
+.Xr gettimeofday 2 ,
+.Xr getutxent 3 ,
+.Xr strftime 3 ,
+.Xr strptime 3 ,
+.Xr tzset 3 ,
+.Xr adjkerntz 8 ,
+.Xr ntpd 8 ,
+.Xr tzsetup 8
+.Rs
+.%T "TSP: The Time Synchronization Protocol for UNIX 4.3BSD"
+.%A R. Gusella
+.%A S. Zatti
+.Re
+.Rs
+.%U https://iana.org/time-zones
+.%T Time Zone Database
+.Re
+.Sh STANDARDS
+The
+.Nm
+utility is expected to be compatible with
+.St -p1003.2 .
+With the exception of the
+.Fl u
+option, all options are extensions to the standard.
+.Pp
+The format selected by the
+.Fl I
+flag is compatible with
+.St -iso8601 .
+.Pp
+The
+.Ql \&%N
+conversion specification for nanoseconds is a non-standard extension.
+It is compatible with GNU date's
+.Ql \&%N .
+.Sh HISTORY
+A
+.Nm
+command appeared in
+.At v1 .
+.Pp
+A number of options were added and then removed again, including the
+.Fl d
+(set DST flag) and
+.Fl t
+(set negative time zone offset).
+Time zones are now handled by code bundled with
+.Sy tzdata .
+.Pp
+The
+.Fl I
+flag was added in
+.Fx 12.0 .
+.Pp
+The
+.Ql \&%N
+conversion specification was added in
+.Fx 14.1 .
+Support for the
+.Ql \&% Ns Ar n Ns Cm N
+and
+.Ql \&%-N
+variants was added in
+.Fx 15.1 .