`date`

Display or set the date and time (POSIX)

Syntax:

Display date and time:

   date [-u] [-s seconds] [+format]
   date -t

Set date and time:

   date [-u] date

Options:

-s seconds: Display the string equivalent of this date, supplied as seconds since the Epoch. This value is used instead of the system time value for the number of seconds.
-t: Display the current system time as the number of seconds elapsed since the Epoch (0 hours, 0 minutes, 0 seconds, January 1, 1970 Coordinated Universal Time).
-u: Perform operations using Coordinated Universal Time (UTC) instead of local time. UTC is the standard term for Greenwich Mean Time (GMT).
date: A date specification to set the date to. Only the superuser (root) can change the date.
+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 QNX'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 QNX time. When the -t option is used, date will print the current number of seconds since the Epoch.

You can specify the format and content of the displayed date and time with the +format option. The format is composed of ASCII character and field descriptors, 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 (see the following table). All other characters are copied to the output without change. To display a "%" character, encode it as %%. The date utility always terminates its output with a newline character.

Descriptor:	Will be replaced by:
`%a`	Locale's abbreviated weekday name.
`%A`	Locale's full weekday name.
`%b`	Locale's abbreviated month name.
`%B`	Locale's full month name.
`%c`	Locale's appropriate date and time representation.
`%d`	Day of the month as a decimal number (01-31).
`%D`	Date in the format mm/dd/yy.
`%h`	A synonym for `%b`.
`%H`	Hour (24-hour clock) as a decimal number (00-23).
`%I`	Hour (12-hour clock) as a decimal number (01-12).
`%j`	Day of the year as a decimal number (001-366).
`%m`	Month as a decimal number (01-12).
`%M`	Minute as a decimal number (00-59).
`%n`	Insert a `newline` character.
`%p`	Locale's equivalent of either am or pm.
`%r`	12-Hour clock time (01-12) using the AM/PM notation in the format HH:MM:SS `AM` or HH:MM:SS `PM`
`%S`	Seconds as a decimal number (00-61). The range of values for `%S` extends from 0 to 61 seconds to accommodate the occasional leap second or double leap second.
`%t`	Insert a `tab` character.
`%T`	24-Hour clock time (00-23) in the format HH:MM:SS.
`%U`	Week number of the year (Sunday as the first day of the week) as a decimal number (00-53).
`%w`	Weekday as a decimal number (0 (Sunday)-6).
`%W`	Week number of the year (Monday as the first day of the week) as a decimal number (00-53).
`%x`	Locale's appropriate date representation.
`%X`	Locale's appropriate time representation.
`%y`	Year without century as a decimal number (00-99).
`%Y`	Year with century as a decimal number.
`%Z`	Time zone name, or no characters if no time zone can be determined.

Setting the date

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

If an adjustment needs to be made, you usually first set the date to the correct setting using date, then run rtc -shw to copy the QNX system time to the battery backed-up hardware clock (on an IBM AT or PS/2).

The date utility recognizes three formats for setting the time:

Format 1:: [[[CC]YY]MM]DD]hhmm[.SS]
Format 2:: DD [Month [[CC]YY [hh [mm [SS]]]]] [am|pm]
Format 3: (valid for years 70 to 99 only): MMDDhhmmYY

Where:

CC: the century (e.g. 19 if the year is 1997)
YY: the year modulo 100 (e.g. 97 if the year is 1997, 00 if the year is 2000)
MM: the 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: the day of the month (e.g. 02 for the 2nd day)
hh: the hour of the day (e.g. 06 for 6 AM, 14 for 2 PM)
mm: the minute of the hour (e.g. 05 for five minutes past the hour)
SS: the seconds of the minute (e.g. 00 for 0 seconds)
am|pm: literally am or pm; can be combined with hour values less than 13 if you don't want a 24-hour clock. Used only with format 2.

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). If the optional CC (century) is not specified, years 00-37 will be taken to mean 2000-2038, and years 70-99 will be taken to mean 1970 to 1999. Years past 2038 cannot be expressed by the signed 32-bit number used to store date and time internally, and are not supported.

Format 2 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 less digits in length.

Format 3 follows the UNIX System V date conventions. It's similar to the Format 1, with the month and day specified, but the year is specified at the end of the specification instead of the beginning. Format 3 (with the year trailing the date/time) cannot be used to set the date if the year is 2000 or above, because of the ambiguity differentiating between format 3 and format 1 if the year is 00 through 12.

If only one operand is supplied and it is greater than two characters in length, date will interpret the date as being format 1 or format 3. If multiple operands are supplied or a single operand of 2 characters or less is given, then the date will be interpreted as being in format 2. Only in the case of a 10-character date with the last two digits being greater than 59 (an invalid minute, if format 1 is used) will the date be interpreted as format 3. In all other cases format 1 (POSIX touch-style) will be used.

Examples:

The following are input/output examples of date used at arbitrary times in the POSIX locale:

Input:: date "+DATE: %m/%d/%Y%nTIME: %H:%M:%S"
Output:: DATE: 11/21/1997
TIME: 13:36:16
Input:: date "+TIME: %r"
Output:: TIME: 01:36:32 PM

The following are examples of date used to set the date and time:

Set the system date/time to 9:00 AM local time, March 10 2002:

    date 200203100900.00

or, you can specify just the last two digits of the year:

    date 0203100900.00

Set the system date to March 10, 2002, without changing the time:

    date 10 3 2002

Adjust the system time to 4:34 pm local time without changing the date:

    date 1634

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

Input:

date -s `tail -n1 /usr/adm/syslog | \
cut -f1 -d ' '`

Output:

Wed Apr 15 14:25:49 EDT 1997

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

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.

The system date cannot be set beyond January of 2038 which is when the signed 32-bit value used to store the seconds since the Epoch will reach its maximum value. If you need to embed QNX in a product which must operate past 2038 without maintenance or modification, contact QNX Software Systems for advice.

Different versions of the date utility shipped with various releases of QNX have differing behavior with two-digit years representing years past 2000. To be sure of correct operation with all versions, avoid format 3 (Sys V format, with the year trailing the date/time), and use four digits when specifying years.

A product bulletin on QNX and year 2000 issues is maintained on the QNX Software Systems homepage. (Search for year 2000.)