.TH DATE 1 "GNU Shell Utilities" "FSF" \" -*- nroff -*-
.SH NAME
date \- print or set the system date and time
.SH SYNOPSIS
.B date
[\-u] [\-d datestr] [\-f datefile] [\-R] [\-r file] [\-s datestr] 
[\-\-utc] [\-\-universal] [\-\-date=datestr] [\-\-file=datefile] 
[\-\-rfc-822] [--reference=file] [\-\-set=datestr]
[\-\-help] [\-\-version] [+FORMAT] [MMDDhhmm[[CC]YY][.ss]]

.SH DESCRIPTION
This documentation is no longer being maintained and may be inaccurate
or incomplete.  The Texinfo documentation is now the authoritative source.
.PP
This manual page
documents the GNU version of
.BR date .
.B date
with no arguments prints the current time and date (as if the format
string was `%a %b %e %H:%M:%S %Z %Y'; the `%' directives are described below).
If given an argument that starts with a `+', it prints time and date 
in a format controlled by that argument, which has the
same format as the format string passed to the `strftime' function.
Except for directives that start with `%', characters in that string
are printed unchanged.
.PP
The directives are:
.IP %
a literal %
.IP n
a newline
.IP t
a horizontal tab
.PP
Time fields:
.IP %H
hour (00..23)
.IP %I
hour (01..12)
.IP %k
hour ( 0..23)
.IP %l
hour ( 1..12)
.IP %M
minute (00..59)
.IP %p
locale's AM or PM
.IP %r
time, 12-hour (hh:mm:ss [AP]M)
.IP %s
seconds since 1970-01-01 00:00:00 UTC (a nonstandard extension)
.IP %S
second (00..61)
.IP %T
time, 24-hour (hh:mm:ss)
.IP %X
locale's time representation (%H:%M:%S)
.IP %z
RFC-822 style numeric time zone (e.g., -0600 or +0100), or nothing if
no time zone is determinable. Note that this value reflects the current 
timezone; it isn't changed by the `--date' option.
.IP %Z
time zone (e.g., EDT), or nothing if no time zone is determinable.
Note that this value reflects the current timezone; it isn't changed
by the `--date' option.
.PP
Date fields:
.IP %a
locale's abbreviated weekday name (Sun..Sat)
.IP %A
locale's full weekday name, variable length (Sunday..Saturday)
.IP %b
locale's abbreviated month name (Jan..Dec)
.IP %B
locale's full month name, variable length (January..December)
.IP %c
locale's date and time (Sat Nov 04 12:02:33 EST 1989)
.IP %d
day of month (01..31)
.IP %D
date (mm/dd/yy)
.IP %h
same as %b
.IP %j
day of year (001..366)
.IP %m
month (01..12)
.IP %U
week number of year with Sunday as first day of week (00..53).
Days in a new year preceding the first Sunday are in week zero.
.IP %V
week number of year with Monday as first day of week (01..53).
If the week containing January 1 has four or more days in the new year, 
then it is considered week 1; otherwise, it is week 53 of the previous 
year, and the next week is week 1. (See the ISO 8601: 1988 standard.)
.IP %w
day of week (0..6) with 0 corresponding to Sunday
.IP %W
week number of year with Monday as first day of week (00..53)
Days in a new year preceding the first Monday are in week zero.
.IP %x
locale's date representation (mm/dd/yy)
.IP %y
last two digits of year (00..99)
.IP %Y
year (1970...)
.PP
By default, 
.BR date
pads numeric fields with zeroes.
GNU
.BR date
recognizes the following nonstandard numeric modifiers between
the `%' and the directive:
.IP \-
(hyphen) do not pad the field
.IP _
(underscore) pad the field with spaces
.PP
If given an argument that does not start with `+',
.B date
sets the system clock to the time and date specified by that argument.
The `--date' and `--set' options may not be used with such an argument.
(Note that the `--set' option provides a different way of setting the
system clock.)
The argument must consist entirely of digits, which have the following
meaning:
.IP MM
month
.IP DD
day within month
.IP hh
hour
.IP mm
minute
.IP CC
first two digits of year (optional)
.IP YY
last two digits of year (optional)
.IP ss
second (optional)
.PP
Only the superuser can set the system clock.
.SS OPTIONS
.TP
.I "\-d datestr, \-\-date=datestr"
Display the time and date specified in
.IR datestr ,
which can be in almost any common format.  The display is in
the default output format, or if an argument starting with `+' is
given to
.BR date ,
in the format specified by that argument.
.TP
.I "\-f datefile, \-\-file=datefile"
Parse each line in
.IR datefile
as with `\-d' and display the resulting time and date.  If
.IR datefile
is `\-', use standard input.  This is useful when you have many
dates to process, because the system overhead of starting up the
`date' executable many times can be considerable.
.TP
.I "\-\-help"
Print a usage message on standard output and exit successfully.
.TP
.I "\-r file, \-\-reference=file"
Display the time and date reference according to the last modification
time of file, instead of the current time and date.
.TP
.I "\-R, \-\-rfc-822"
Display the time and date using the RFC-822-specified format, `%a,
%_d %b %Y %H:%M:%S %z'.  If `\-\-utc' is also specified, use `GMT'
in place of `%z'.
.I "\-s datestr, \-\-set datestr"
Set the time and date to
.IR datestr ,
which can be in almost any common format.
It can contain month names, timezones, `am' and `pm', etc.
.TP
.I "\-u, \-\-universal"
Print or set the time and date in Coordinated Universal Time (also
known as Greenwich Mean Time) instead of in local (wall clock) time.
.TP
.I "\-\-version"
Print version information on standard output then exit successfully.
.SH EXAMPLES
.PP
To print the date of the day before yesterday
.IP
date \-\-date \'2 days ago\'
.PP
To print the date of the day three months and one day hence
.IP
date \-\-date \'3 months 1 day\'
.PP
To print the day of year of Christmas in the current year
.IP
date --date \'25 Dec\' +%j
.PP
To print the current date in a format including the full month name and
the day of the month
.IP
date \'+%B %d\'
.PP
But this may not be what you want because for the first nine days
of the month, the \`%d\' expands to a zero-padded two-digit field,
for example \`date \-d 1-may \'+%B %d\'\' will print
\`May 01\'.
.PP
To print the same date but without the leading zero for one-digit
days of month, you can use the nonstandard \`\-\' modifier to suppress
the padding altogether.
.IP
date \-d 1-may \'+%B %-d\'