`date`

Display or set the date and time (POSIX)

Syntax:

Display date and time:

date [-tuv] [-s seconds] [+format]

Set date and time:

date [-uv] [-S seconds] date

Options:

-S seconds: Set the maximum number of seconds (of real time) over which date is to adjust the time. The date utility doesn't increase the clock speed by more than 100% or decrease it by more than 50%. If date can't do a slow adjustment within those constraints, the time is changed immediately. (The default is 300 seconds; use -S0 to disable the gradual adjustment.)
-s seconds: Display the string equivalent of this date, supplied as seconds since the start of the Epoch (00:00 January 1, 1970). This value is used instead of the system time value for the number of seconds.
-t: Display the current operating system time, in seconds since the start of the Epoch, as a long integer.
-u: Perform operations using Coordinated Universal Time (UTC) instead of local time. UTC is the standard term for Greenwich Mean Time (GMT).
-v: Be verbose.
date: A date specification to set the date to. Only the superuser (root) can change the date. For more information, see "Setting the date," below.
+format: The format in which the date and time are to be displayed.

Description:

The date utility is used to display and set the current system date and time in software. Only the superuser (root) may use date to set the time.

The date utility normally displays the current date and time according to the operating system's internal time, maintained in software as the number of seconds since the Epoch (00:00 January 1, 1970). When the -s seconds option is used, date uses the value specified by the seconds argument instead of the current OS time.

You can specify the format and content of the displayed date and time with the +format option. The format is composed of ASCII characters and field descriptors prefaced with %, in a manner similar to a C-language printf() format specifier (the specific characters used to specify field types are, however, completely different). In the output, each field descriptor is replaced by its corresponding value; all other characters are copied to the output without change.

This utility uses strftime(), a libc library function, to format the time into a string. For a complete list of the field descriptors you can use in the +format option, see strftime() in the Library Reference.

The date utility always terminates its output with a newline character.

Setting the date

If you're a system administrator running as root, you may use date to set the system time. To set the hardware clock to match the current system time set by date, you should use the rtc utility.

Be careful if you set the date during the period that a time zone is switching from daylight saving time to standard time. When a time zone changes to standard time, the local time goes back one hour (for example, 2:00 a.m. becomes 1:00 a.m.). The local time during this hour is ambiguous (e.g. 1:14 a.m. occurs twice in the morning that the time zone switches to DST). To avoid problems, use UTC time to set the date in this period.

By default, if the new time is in the range of:

(-2.5 minutes + old time, 5 minutes + old time)

the date utility makes a "slow adjustment" -- it increases the clock speed by less than 100% or decreases the clock speed by less than 50% over a period of time from 1 second to 5 minutes until the clock catches up with the new time. This slow adjustment doesn't cause major discontinuities in the time flow. You can disable the slow adjustment by using the -S0 option.

The date utility recognizes three formats for setting the time:

[[[CC]YY]MM]DD]hhmm[.SS]
MMDDhhmm[YY]
DD [Month [[CC]YY [hh [mm [SS]]]]] [am|pm]

Where:

CC: Century (e.g. 19 if the year is 1997)
YY: Year modulo 100 (e.g. 97 if the year is 1997)
MM: Numerical month of the year (01 for January, 02 for February, etc.)
Month: Either the numerical month (1, 2,...12) or the standard English abbreviation for the month (jan, feb,...dec)
DD: Day of the month
hh: Hour of the day
mm: Minute of the hour
SS: Seconds of the minute
am|pm: Literally am or pm; you can combine them with hour values less than 13 if you don't want a 24-hour clock

Format 1 is compatible with the touch utility. Since each field is two digits, you must specify a leading 0 for single-digit numbers. You should find this format particularly useful for adjusting the time of day, since its minimal form is just hhmm (hour and minute).

Format 2 follows the UNIX System V date conventions. It's similar to the Format 1, with the month and day specified, but the year is optional at the end of the specification instead of the beginning. If there's a dot (.) in the date, date assumes the date is Format 1 instead of Format 2. The date utility also differentiates between MMDDhhmmYY (Format 2) and YYMMDDhhmm (Format 1) by the value of the first pair of digits. The years 00-12 are before the Epoch. Therefore, if the first pair of digits is in that range, the date is treated as it is in Format 1.

Format 3 follows the date convention used in QNX 4.00 and earlier. This format is assumed if there's more than one operand (the other two formats consist of a single string of digits), or if there's just one number that's two or fewer digits in length.

If you change the date or time, date adds a a line to the /var/log/wtmp if it already exists.

The date utility doesn't create /var/log/wtmp if it doesn't already exist. This file can quickly become very big, which isn't good on an embedded system with limited resources.

Examples:

Display the date and time on separate lines:

$ date "+DATE: %m/%d/%y%nTIME: %H:%M:%S"
DATE: 01/20/99
TIME: 08:51:59

Display the time in 12-hour format:

$ date "+TIME: %r"
TIME: 01:36:32 PM

Set the system date to 22 February 1997:

date 22 2 97

Set the system date and time to 16 May 1997, 4:30 pm:

date 16 may 1997 4 30 pm

Adjust the system time to 4:34 pm; use today's date:

date 1634

The following command, which illustrates the use of date -s, displays the date of the last entry in the /usr/adm/syslog file (in this file, the first column of each record is the time in seconds since the Epoch):

$ date -s `tail -n1 /usr/adm/syslog | cut -f1 -d ' '`
Wed Apr 15 14:25:49 EDT 1997

For more information, see cut, logger, and tail.

Files:

/var/log/wtmp: If you change the data or time, and this file already exists, an entry is added to it to log the change.

Environment variables:

TZ: Specifies the local time zone. The value of TZ affects the conversion between the system clock (UTC) and the local time.

Exit status:

0: The date was displayed or set successfully.
>0: An error occurred.

Caveats:

Some field descriptors are of unspecified format when not in the POSIX locale. As a result, parsing the output of date may be difficult in other locales. QNX Neutrino currently supports only the POSIX (i.e. C) locale.