Editing Time (Unix)

{{short description|Command in Unix and Unix-like operating systems}}
{{about|the Unix command|Unix's means of representing points in time|Unix time|the Unix function call|time.h}}
{{lowercase title}}
{{Infobox software
| name                   = time
| logo                   = 
| screenshot             = Time-example-command.gif
| screenshot size        = 
| caption                = Example of <code>time</code> command
| developer              = Various [[open-source software|open-source]] and [[commercial software|commercial]] developers
| released               = 
| latest release version = 
| latest release date    = 
| operating system       = [[Unix]], [[Unix-like]], [[Inferno (operating system)|Inferno]]
| platform               = [[Cross-platform]]
| genre                  = [[Command (computing)|Command]]
| license                = 
| website                = 
}}
In [[computing]], <code>'''time'''</code> is a command in [[Unix]] and [[Unix-like]] operating systems. It is used to determine the duration of execution of a particular [[command (computing)|command]].

==Overview==
<code>time(1)</code> can exist as a standalone program (such as [[GNU]] time) or as a [[Unix shell|shell]] builtin in most cases (e.g. in [[Unix shell|sh]], [[Bash (Unix shell)|bash]], [[tcsh]] or in [[zsh]]).

===User time vs system time===
The total CPU time is the combination of the amount of time the CPU or CPUs spent performing some action for a program and the amount of time they spent performing [[system call]]s for the [[kernel (operating system)|kernel]] on the program's behalf. When a program loops through an array, it is accumulating user CPU time. Conversely, when a program executes a [[system call]] such as <code>exec</code> or <code>fork</code>, it is accumulating system CPU time.

===Real time vs CPU time===
The term "real time" in this context refers to elapsed [[wall-clock time]], like using a stop watch. The total CPU time (user time + sys time) may be more or less than that value. Because a program may spend some time waiting and not executing at all (whether in user mode or system mode) the real time may be greater than the total CPU time. Because a program may fork children whose CPU times (both user and sys) are added to the values reported by the <code>time</code> command, but on a multicore system these tasks are run in parallel, the total CPU time may be greater than the real time.

==Usage==
To use the command, one simply precedes any command by the word <code>time</code>, such as:
<syntaxhighlight lang="bash">$ time ls</syntaxhighlight>

When the command completes, <code>time</code> will report how long it took to execute the <code>[[ls]]</code> command in terms of user [[CPU time]], system CPU time, and real time. The output format varies between different versions of the command, and some give additional statistics, as in this example:
<syntaxhighlight lang="console">
$ time host wikipedia.org
wikipedia.org has address 103.102.166.224
wikipedia.org mail is handled by 50 mx2001.wikimedia.org.
wikipedia.org mail is handled by 10 mx1001.wikimedia.org.
host wikipedia.org  0.04s user 0.02s system 7% cpu 0.780 total
$
</syntaxhighlight>

{{mono|time}} (either a standalone program, or when Bash shell is running in POSIX mode AND {{mono|time}} is invoked as <code>time -p</code>) reports to standard error output.

===time -p===
Portable scripts should use <code>time -p</code> mode, which uses a different output format, but which is consistent with various implementations:
<syntaxhighlight lang="console">
$ time -p sha256sum /bin/ls
12477deb0e25209768cbd79328f943a7ea8533ece70256cdea96fae0ae34d1cc  /bin/ls
real 0.00
user 0.00
sys 0.00
$
</syntaxhighlight>

==Implementations==

===GNU time===
Current versions of GNU time, report more than just a time by default:
<syntaxhighlight lang="console">
$ /usr/bin/time sha256sum /bin/ls
12477deb0e25209768cbd79328f943a7ea8533ece70256cdea96fae0ae34d1cc  /bin/ls
0.00user 0.00system 0:00.00elapsed 100%CPU (0avgtext+0avgdata 2156maxresident)k
0inputs+0outputs (0major+96minor)pagefaults 0swaps
$
</syntaxhighlight>

Format of the output for [[GNU]] time, can be adjusted using <code>'''TIME'''</code> environment variable, and it can include information other than the execution time (i.e. memory usage). This behavior is not available in general [[POSIX]]-compliant time, or when executing as <code>time -p</code>.

Documentation of this {{mono|time}} can be usually accessed using <code>man 1 time</code>.

====Method of operation====
According to the source code of the GNU implementation of <code>time</code>, most information shown by <code>time</code> is derived from the <code>wait3</code> system call. On systems that do not have a <code>wait3</code> call that returns status information, the <code>times</code> system call is used instead.

===Bash===
In a popular Unix shell [[Bash (Unix shell)|Bash]], <code>'''time'''</code> is a special keyword, that can be put before a [[Pipeline (Unix)|pipeline]] (or single command), that measures time of entire pipeline, not just a singular (first) command, and uses a different default format, and puts empty line before reporting times:
<syntaxhighlight lang="console">
$ time seq 10000000 | wc -l
10000000

real	0m0.078s
user	0m0.116s
sys	0m0.029s
$
</syntaxhighlight>

The reported time is a time used by both <code>'''seq'''</code> and <code>'''wc -l'''</code> added up. Format of the output can be adjusted using <code>'''TIMEFORMAT'''</code> variable.

The {{mono|time}} is not a builtin, but a special keyword, and can't be treated as a function or command. It also ignores pipeline redirections (even when executed as <code>time -p</code>, unless entire Bash is run in "POSIX mode").

Documentation of this {{mono|time}} can be accessed using <code>man 1 bash</code>, or within bash itself using <code>help time</code>.

==See also==
{{Wikibooks|Guide to Unix|Commands}}
* [[System time]]
* [[Cron]] process for scheduling jobs to run at a particular time
* [[TIME (command)]]

==References==
* {{man|cu|time|SUS|time a simple command}}
* {{man|1|time|Inferno}}
* {{man|1|time|Linux|time a simple command or give resource usage}}

{{Unix commands}}

[[Category:Unix SUS2008 utilities]]
[[Category:Unix process- and task-management-related software]]
[[Category:Inferno (operating system) commands]]