21. System context

This section describes commands that print or change system-wide information.

21.1 date: Print or set system date and time

Synopses:

date [option]… [+format]
date [-u|--utc|--universal] [ MMDDhhmm[[CC]YY][.ss] ]

Invoking date with no format argument is equivalent to invoking it with a default format that depends on the LC_TIME locale category. In the default C locale, this format is `'+%a %b %e %H:%M:%S %Z %Y'', so the output looks like `Thu Mar  3 13:47:51 PST 2005'.

Normally, date uses the time zone rules indicated by the TZ environment variable, or the system default rules if TZ is not set. See (libc)TZ Variable section `Specifying the Time Zone with TZ' in The GNU C Library Reference Manual.

If given an argument that starts with a `+', date prints the current date and time (or the date and time specified by the `--date' option, see below) in the format defined by that argument, which is similar to that of the strftime function. Except for conversion specifiers, which start with `%', characters in the format string are printed unchanged. The conversion specifiers are described below.

An exit status of zero indicates success, and a nonzero value indicates failure.

21.1.1 Time conversion specifiers

date conversion specifiers related to times.

`%H'

hour (`00'…`23')

`%I'

hour (`01'…`12')

`%k'

hour (` 0'…`23'). This is a GNU extension.

`%l'

hour (` 1'…`12'). This is a GNU extension.

`%M'

minute (`00'…`59')

`%N'

nanoseconds (`000000000'…`999999999'). This is a GNU extension.

`%p'

locale's equivalent of either `AM' or `PM'; blank in many locales. Noon is treated as `PM' and midnight as `AM'.

`%P'

like `%p', except lower case. This is a GNU extension.

`%r'

locale's 12-hour clock time (e.g., `11:11:04 PM')

`%R'

24-hour hour and minute. Same as `%H:%M'. This is a GNU extension.

`%s'

seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. Leap seconds are not counted unless leap second support is available. See %s-examples, for examples. This is a GNU extension.

`%S'

second (`00'…`60'). This may be `60' if leap seconds are supported.

`%T'

24-hour hour, minute, and second. Same as `%H:%M:%S'.

`%X'

locale's time representation (e.g., `23:13:48')

`%z'

RFC 2822/ISO 8601 style numeric time zone (e.g., `-0600' or `+0530'), or nothing if no time zone is determinable. This value reflects the numeric time zone appropriate for the current time, using the time zone rules specified by the TZ environment variable. The time (and optionally, the time zone rules) can be overridden by the `--date' option. This is a GNU extension.

`%:z'

RFC 3339/ISO 8601 style numeric time zone with `:' (e.g., `-06:00' or `+05:30'), or nothing if no time zone is determinable. This is a GNU extension.

`%::z'

Numeric time zone to the nearest second with `:' (e.g., `-06:00:00' or `+05:30:00'), or nothing if no time zone is determinable. This is a GNU extension.

`%:::z'

Numeric time zone with `:' using the minimum necessary precision (e.g., `-06', `+05:30', or `-04:56:02'), or nothing if no time zone is determinable. This is a GNU extension.

`%Z'

alphabetic time zone abbreviation (e.g., `EDT'), or nothing if no time zone is determinable. See `%z' for how it is determined.

21.1.2 Date conversion specifiers

date conversion specifiers related to dates.

`%a'

locale's abbreviated weekday name (e.g., `Sun')

`%A'

locale's full weekday name, variable length (e.g., `Sunday')

`%b'

locale's abbreviated month name (e.g., `Jan')

`%B'

locale's full month name, variable length (e.g., `January')

`%c'

locale's date and time (e.g., `Thu Mar  3 23:05:25 2005')

`%C'

century. This is like `%Y', except the last two digits are omitted. For example, it is `20' if `%Y' is `2000', and is `-0' if `%Y' is `-001'. It is normally at least two characters, but it may be more.

`%d'

day of month (e.g., `01')

`%D'

date; same as `%m/%d/%y'

`%e'

day of month, space padded; same as `%_d'

`%F'

full date in ISO 8601 format; same as `%Y-%m-%d'. This is a good choice for a date format, as it is standard and is easy to sort in the usual case where years are in the range 0000…9999. This is a GNU extension.

`%g'

year corresponding to the ISO week number, but without the century (range `00' through `99'). This has the same format and value as `%y', except that if the ISO week number (see `%V') belongs to the previous or next year, that year is used instead. This is a GNU extension.

`%G'

year corresponding to the ISO week number. This has the same format and value as `%Y', except that if the ISO week number (see `%V') belongs to the previous or next year, that year is used instead. It is normally useful only if `%V' is also used; for example, the format `%G-%m-%d' is probably a mistake, since it combines the ISO week number year with the conventional month and day. This is a GNU extension.

`%h'

same as `%b'

`%j'

day of year (`001'…`366')

`%m'

month (`01'…`12')

`%u'

day of week (`1'…`7') with `1' corresponding to Monday

`%U'

week number of year, with Sunday as the first day of the week (`00'…`53'). Days in a new year preceding the first Sunday are in week zero.

`%V'

ISO week number, that is, the week number of year, with Monday as the first day of the 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 standard.)

`%w'

day of week (`0'…`6') with 0 corresponding to Sunday

`%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.

`%x'

locale's date representation (e.g., `12/31/99')

`%y'

last two digits of year (`00'…`99')

`%Y'

year. This is normally at least four characters, but it may be more. Year `0000' precedes year `0001', and year `-001' precedes year `0000'.

21.1.3 Literal conversion specifiers

date conversion specifiers that produce literal strings.

`%%'

a literal %

`%n'

a newline

`%t'

a horizontal tab

21.1.4 Padding and other flags

Unless otherwise specified, date normally pads numeric fields with zeros, so that, for example, numeric months are always output as two digits. Seconds since the epoch are not padded, though, since there is no natural width for them.

As a GNU extension, date recognizes any of the following optional flags after the `%':

`-'

(hyphen) Do not pad the field; useful if the output is intended for human consumption.

`_'

(underscore) Pad with spaces; useful if you need a fixed number of characters in the output, but zeros are too distracting.

`0'

(zero) Pad with zeros even if the conversion specifier would normally pad with spaces.

`^'

Use upper case characters if possible.

`#'

Use opposite case characters if possible. A field that is normally upper case becomes lower case, and vice versa.

Here are some examples of padding:

date +%d/%m -d "Feb 1"
⇒ 01/02
date +%-d/%-m -d "Feb 1"
⇒ 1/2
date +%_d/%_m -d "Feb 1"
⇒  1/ 2

As a GNU extension, you can specify the field width (after any flag, if present) as a decimal number. If the natural size of the output of the field has less than the specified number of characters, the result is written right adjusted and padded to the given size. For example, `%9B' prints the right adjusted month name in a field of width 9.

An optional modifier can follow the optional flag and width specification. The modifiers are:

`E'

Use the locale's alternate representation for date and time. This modifier applies to the `%c', `%C', `%x', `%X', `%y' and `%Y' conversion specifiers. In a Japanese locale, for example, `%Ex' might yield a date format based on the Japanese Emperors' reigns.

`O'

Use the locale's alternate numeric symbols for numbers. This modifier applies only to numeric conversion specifiers.

If the format supports the modifier but no alternate representation is available, it is ignored.

21.1.5 Setting the time

If given an argument that does not start with `+', date sets the system clock to the date and time specified by that argument (as described below). You must have appropriate privileges to set the system clock. The `--date' and `--set' options may not be used with such an argument. The `--universal' option may be used with such an argument to indicate that the specified date and time are relative to Coordinated Universal Time rather than to the local time zone.

The argument must consist entirely of digits, which have the following meaning:

`MM'

month

`DD'

day within month

`hh'

hour

`mm'

minute

`CC'

first two digits of year (optional)

`YY'

last two digits of year (optional)

`ss'

second (optional)

The `--set' option also sets the system clock; see the next section.

21.1.6 Options for date

The program accepts the following options. Also see Common options.

`-d datestr'

`--date=datestr'

Display the date and time specified in datestr instead of the current date and time. datestr can be in almost any common format. It can contain month names, time zones, `am' and `pm', `yesterday', etc. For example, `--date="2004-02-27 14:19:13.489392193 +0530"' specifies the instant of time that is 489,392,193 nanoseconds after February 27, 2004 at 2:19:13 PM in a time zone that is 5 hours and 30 minutes east of UTC.
Note: input currently must be in locale independent format. E.g., the LC_TIME=C below is needed to print back the correct date in many locales:

date -d "$(LC_TIME=C date)"

See section Date input formats.

`-f datefile'

`--file=datefile'

Parse each line in datefile as with `-d' and display the resulting date and time. If 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.

`-r file'

`--reference=file'

Display the date and time of the last modification of file, instead of the current date and time.

`-R'

`--rfc-822'

`--rfc-2822'

Display the date and time using the format `%a, %d %b %Y %H:%M:%S %z', evaluated in the C locale so abbreviations are always in English. For example:

Fri, 09 Sep 2005 13:51:39 -0700

This format conforms to Internet RFCs 2822 and 822, the current and previous standards for Internet email.

`--rfc-3339=timespec'

Display the date using a format specified by Internet RFC 3339. This is a subset of the ISO 8601 format, except that it also permits applications to use a space rather than a `T' to separate dates from times. Unlike the other standard formats, RFC 3339 format is always suitable as input for the `--date' (`-d') and `--file' (`-f') options, regardless of the current locale.

The argument timespec specifies how much of the time to include. It can be one of the following:

`date'

Print just the full-date, e.g., `2005-09-14'. This is equivalent to the format `%Y-%m-%d'.

`seconds'

Print the full-date and full-time separated by a space, e.g., `2005-09-14 00:56:06+05:30'. The output ends with a numeric time-offset; here the `+05:30' means that local time is five hours and thirty minutes east of UTC. This is equivalent to the format `%Y-%m-%d %H:%M:%S%:z'.

`ns'

Like `seconds', but also print nanoseconds, e.g., `2005-09-14 00:56:06.998458565+05:30'. This is equivalent to the format `%Y-%m-%d %H:%M:%S.%N%:z'.

`-s datestr'

`--set=datestr'

Set the date and time to datestr. See `-d' above.

`-u'

`--utc'

`--universal'

Use Coordinated Universal Time (UTC) by operating as if the TZ environment variable were set to the string `UTC0'. Coordinated Universal Time is often called "Greenwich Mean Time" (GMT) for historical reasons.

21.1.7 Examples of date

Here are a few examples. Also see the documentation for the `-d' option in the previous section.

• To print the date of the day before yesterday:

  date --date='2 days ago'

• To print the date of the day three months and one day hence:

  date --date='3 months 1 day'

• To print the day of year of Christmas in the current year:

  date --date='25 Dec' +%j

• To print the current full month name and the day of the month:

  date '+%B %d'

  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 1may '+%B %d'' will print `May 01'.

• To print a date without the leading zero for one-digit days of the month, you can use the (GNU extension) `-' flag to suppress the padding altogether:

  date -d 1may '+%B %-d

• To print the current date and time in the format required by many non-GNU versions of date when setting the system clock:

  date +%m%d%H%M%Y.%S

• To set the system clock forward by two minutes:

  date --set='+2 minutes'

• To print the date in RFC 2822 format, use `date --rfc-2822'. Here is some example output:

  Fri, 09 Sep 2005 13:51:39 -0700

• To convert a date string to the number of seconds since the epoch (which is 1970-01-01 00:00:00 UTC), use the `--date' option with the `%s' format. That can be useful in sorting and/or graphing and/or comparing data by date. The following command outputs the number of the seconds since the epoch for the time two minutes after the epoch:

  date --date='1970-01-01 00:02:00 +0000' +%s 120

  If you do not specify time zone information in the date string, date uses your computer's idea of the time zone when interpreting the string. For example, if your computer's time zone is that of Cambridge, Massachusetts, which was then 5 hours (i.e., 18,000 seconds) behind UTC:

  # local time zone used date --date='1970-01-01 00:02:00' +%s 18120

• If you're sorting or graphing dated data, your raw date values may be represented as seconds since the epoch. But few people can look at the date `946684800' and casually note "Oh, that's the first second of the year 2000 in Greenwich, England."

  date --date='2000-01-01 UTC' +%s 946684800

  An alternative is to use the `--utc' (`-u') option. Then you may omit `UTC' from the date string. Although this produces the same result for `%s' and many other format sequences, with a time zone offset different from zero, it would give a different result for zone-dependent formats like `%z'.

  date -u --date=2000-01-01 +%s 946684800

  To convert such an unwieldy number of seconds back to a more readable form, use a command like this:

  # local time zone used date -d '1970-01-01 UTC 946684800 seconds' +"%Y-%m-%d %T %z" 1999-12-31 19:00:00 -0500

  Or if you do not mind depending on the `@' feature present since coreutils 5.3.0, you could shorten this to:

  date -d @946684800 +"%F %T %z" 1999-12-31 19:00:00 -0500

  Often it is better to output UTC-relative date and time:

  date -u -d '1970-01-01 946684800 seconds' +"%Y-%m-%d %T %z" 2000-01-01 00:00:00 +0000

21.2 arch: Print machine hardware name

arch prints the machine hardware name, and is equivalent to `uname -m'. Synopsis:

arch [option]

The program accepts the Common options only.

An exit status of zero indicates success, and a nonzero value indicates failure.

21.3 nproc: Print the number of available processors

Print the number of processing units available to the current process, which may be less than the number of online processors. If this information is not accessible, then print the number of processors installed. If the OMP_NUM_THREADS environment variable is set, then it will determine the returned value. The result is guaranteed to be greater than zero. Synopsis:

nproc [option]

The program accepts the following options. Also see Common options.

`--all'

Print the number of installed processors on the system, which may be greater than the number online or available to the current process. The OMP_NUM_THREADS environment variable is not honored in this case.

`--ignore=number'

If possible, exclude this number of processing units.

An exit status of zero indicates success, and a nonzero value indicates failure.

21.4 uname: Print system information

uname prints information about the machine and operating system it is run on. If no options are given, uname acts as if the `-s' option were given. Synopsis:

uname [option]…

If multiple options or `-a' are given, the selected information is printed in this order:

kernel-name nodename kernel-release kernel-version
machine processor hardware-platform operating-system

The information may contain internal spaces, so such output cannot be parsed reliably. In the following example, release is `2.2.18ss.e820-bda652a #4 SMP Tue Jun 5 11:24:08 PDT 2001':

uname -a
⇒ Linux dum 2.2.18 #4 SMP Tue Jun 5 11:24:08 PDT 2001 i686 unknown unknown GNU/Linux

The program accepts the following options. Also see Common options.

`-a'

`--all'

Print all of the below information, except omit the processor type and the hardware platform name if they are unknown.

`-i'

`--hardware-platform'

Print the hardware platform name (sometimes called the hardware implementation). Print `unknown' if the kernel does not make this information easily available, as is the case with Linux kernels.

`-m'

`--machine'

Print the machine hardware name (sometimes called the hardware class or hardware type).

`-n'

`--nodename'

Print the network node hostname.

`-p'

`--processor'

Print the processor type (sometimes called the instruction set architecture or ISA). Print `unknown' if the kernel does not make this information easily available, as is the case with Linux kernels.

`-o'

`--operating-system'

Print the name of the operating system.

`-r'

`--kernel-release'

Print the kernel release.

`-s'

`--kernel-name'

Print the kernel name. POSIX 1003.1-2001 (see section Standards conformance) calls this "the implementation of the operating system", because the POSIX specification itself has no notion of "kernel". The kernel name might be the same as the operating system name printed by the `-o' or `--operating-system' option, but it might differ. Some operating systems (e.g., FreeBSD, HP-UX) have the same name as their underlying kernels; others (e.g., GNU/Linux, Solaris) do not.

`-v'

`--kernel-version'

Print the kernel version.

An exit status of zero indicates success, and a nonzero value indicates failure.

21.5 hostname: Print or set system name

With no arguments, hostname prints the name of the current host system. With one argument, it sets the current host name to the specified string. You must have appropriate privileges to set the host name. Synopsis:

hostname [name]

The only options are `--help' and `--version'. See section Common options.

An exit status of zero indicates success, and a nonzero value indicates failure.

21.6 hostid: Print numeric host identifier

hostid prints the numeric identifier of the current host in hexadecimal. This command accepts no arguments. The only options are `--help' and `--version'. See section Common options.

For example, here's what it prints on one system I use:

$ hostid
1bac013d

On that system, the 32-bit quantity happens to be closely related to the system's Internet address, but that isn't always the case.

An exit status of zero indicates success, and a nonzero value indicates failure.

21.7 uptime: Print system uptime and load

uptime prints the current time, the system's uptime, the number of logged-in users and the current load average.

If an argument is specified, it is used as the file to be read to discover how many users are logged in. If no argument is specified, a system default is used (uptime --help indicates the default setting).

The only options are `--help' and `--version'. See section Common options.

For example, here's what it prints right now on one system I use:

$ uptime
 14:07  up   3:35,  3 users,  load average: 1.39, 1.15, 1.04

The precise method of calculation of load average varies somewhat between systems. Some systems calculate it as the average number of runnable processes over the last 1, 5 and 15 minutes, but some systems also include processes in the uninterruptible sleep state (that is, those processes which are waiting for disk I/O). The Linux kernel includes uninterruptible processes.

This document was generated on January, 20 2010 using texi2html 1.76.