Provided by: time_1.7-23.1_amd64 bug

NAME

       time - run programs and summarize system resource usage

SYNOPSIS

       time   [ -apqvV ] [ -f FORMAT ] [ -o FILE ]
              [ --append ] [ --verbose ] [ --quiet ] [ --portability ]
              [ --format=FORMAT ] [ --output=FILE ] [ --version ]
              [ --help ] COMMAND [ ARGS ]

DESCRIPTION

       time run the program COMMAND with any given arguments ARG....  When COMMAND finishes, time
       displays information about resources used by COMMAND (on the  standard  error  output,  by
       default).   If COMMAND exits with non-zero status, time displays a warning message and the
       exit status.

       time determines which information to display about the resources used by the COMMAND  from
       the  string  FORMAT.   If  no  format  is  specified  on  the  command  line, but the TIME
       environment variable is set, its value is used as the format.  Otherwise, a default format
       built into time is used.

       Options  to  time must appear on the command line before COMMAND.  Anything on the command
       line after COMMAND is passed as arguments to COMMAND.

OPTIONS

       -o FILE, --output=FILE
              Write the resource use statistics to FILE instead of to the standard error  stream.
              By  default,  this  overwrites  the  file, destroying the file's previous contents.
              This option is useful  for  collecting  information  on  interactive  programs  and
              programs that produce output on the standard error stream.
       -a, --append
              Append the resource use information to the output file instead of overwriting
               it.  This option is only useful with the `-o' or `--output' option.
       -f FORMAT, --format FORMAT
              Use  FORMAT  as  the format string that controls the output of time.  See the below
              more information.
       --help Print a summary of the command line options and exit.
       -p, --portability
              Use the following format string, for conformance with POSIX standard 1003.2:
                        real %e
                        user %U
                        sys %S
       -v, --verbose
              Use the built-in verbose format, which displays each available piece of information
              on  the  program's resource use on its own line, with an English description of its
              meaning.
       --quiet
              Do not report the status of the program even if it is different from zero.
       -V, --version
              Print the version number of time and exit.

FORMATTING THE OUTPUT

       The format string FORMAT controls the contents of the time output.  The format string  can
       be  set  using  the  `-f'  or  `--format', `-v' or `--verbose', or `-p' or `--portability'
       options.  If they are not given, but the TIME environment variable is set,  its  value  is
       used  as  the  format  string.  Otherwise, a built-in default format is used.  The default
       format is:
         %Uuser %Ssystem %Eelapsed %PCPU (%Xtext+%Ddata %Mmax)k
         %Iinputs+%Ooutputs (%Fmajor+%Rminor)pagefaults %Wswaps

       The format string usually consists of `resource specifiers' interspersed with plain  text.
       A percent sign (`%') in the format string causes the following character to be interpreted
       as a resource specifier, which is similar to the formatting characters  in  the  printf(3)
       function.

       A  backslash  (`\')  introduces  a  `backslash  escape', which is translated into a single
       printing character upon output.  `\t' outputs a tab character, `\n' outputs a newline, and
       `\\'  outputs a backslash.  A backslash followed by any other character outputs a question
       mark (`?') followed by a backslash, to indicate  that  an  invalid  backslash  escape  was
       given.

       Other  text  in  the format string is copied verbatim to the output.  time always prints a
       newline after printing the resource use information, so normally format strings do not end
       with a newline character (or `0).

       There are many resource specifications.  Not all resources are measured by all versions of
       Unix, so some of the values might be reported as zero.  Any character following a  percent
       sign  that  is  not  listed  in the table below causes a question mark (`?') to be output,
       followed by that character, to indicate that an invalid resource specifier was given.

       The resource specifiers, which are a superset of those recognized by the  tcsh(1)  builtin
       `time' command, are:
              %      A literal `%'.
              C      Name and command line arguments of the command being timed.
              D      Average size of the process's unshared data area, in Kilobytes.
              E      Elapsed    real    (wall    clock)    time   used   by   the   process,   in
                     [hours:]minutes:seconds.
              F      Number of major, or I/O-requiring,  page  faults  that  occurred  while  the
                     process  was running.  These are faults where the page has actually migrated
                     out of primary memory.
              I      Number of file system inputs by the process.
              K      Average total (data+stack+text) memory use of the process, in Kilobytes.
              M      Maximum resident set size of the process during its lifetime, in Kilobytes.
              O      Number of file system outputs by the process.
              P      Percentage of the CPU that this job got.  This is just user +  system  times
                     divided by the total running time. It also prints a percentage sign.
              R      Number  of minor, or recoverable, page faults.  These are pages that are not
                     valid (so they fault) but which have not yet been claimed by  other  virtual
                     pages.   Thus the data in the page is still valid but the system tables must
                     be updated.
              S      Total number of CPU-seconds used by the system on behalf of the process  (in
                     kernel mode), in seconds.
              U      Total  number  of CPU-seconds that the process used directly (in user mode),
                     in seconds.
              W      Number of times the process was swapped out of main memory.
              X      Average amount of shared text in the process, in Kilobytes.
              Z      System's page size, in bytes.  This is a  per-system  constant,  but  varies
                     between systems.
              c      Number  of times the process was context-switched involuntarily (because the
                     time slice expired).
              e      Elapsed real (wall clock) time used by the process, in seconds.
              k      Number of signals delivered to the process.
              p      Average unshared stack size of the process, in Kilobytes.
              r      Number of socket messages received by the process.
              s      Number of socket messages sent by the process.
              t      Average resident set size of the process, in Kilobytes.
              w      Number of times that  the  program  was  context-switched  voluntarily,  for
                     instance while waiting for an I/O operation to complete.
              x      Exit status of the command.

EXAMPLES

       To run the command `wc /etc/hosts' and show the default information:
            time wc /etc/hosts

       To run the command `ls -Fs' and show just the user, system, and total time:
            time -f "%E real,%U user,%S sys" ls -Fs

       To edit the file BORK and have `time' append the elapsed time and number of signals to the
       file `log', reading the format string from the environment variable `TIME':
            export TIME="%E,%k" # If using bash or ksh
            setenv TIME "%E,%k" # If using csh or tcsh
            time -a -o log emacs bork

       Users of the bash shell need to use an explicit path in order to  run  the  external  time
       command  and not the shell builtin variant. On system where time is installed in /usr/bin,
       the first example would become
            /usr/bin/time wc /etc/hosts

ACCURACY

       The elapsed time is not collected atomically with the  execution  of  the  program;  as  a
       result,  in  bizarre  circumstances  (if  the  time command gets stopped or swapped out in
       between when the program being timed exits and when time calculates how long  it  took  to
       run), it could be much larger than the actual execution time.

       When  the running time of a command is very nearly zero, some values (e.g., the percentage
       of CPU used) may be reported as either zero (which is wrong) or a question mark.

       Most information shown by time is derived from the wait3(2) system call.  The numbers  are
       only  as  good as those returned by wait3(2).  On systems that do not have a wait3(2) call
       that returns status information, the times(2) system call is used  instead.   However,  it
       provides  much  less  information  than  wait3(2),  so  on  those systems time reports the
       majority of the resources as zero.

       The `%I' and `%O' values are allegedly only `real' input and output  and  do  not  include
       those  supplied  by  caching devices.  The meaning of `real' I/O reported by `%I' and `%O'
       may be muddled for workstations, especially diskless ones.

DIAGNOSTICS

       The time command returns when the program exits, stops, or is terminated by a signal.   If
       the  program  exited normally, the return value of time is the return value of the program
       it executed and measured. Otherwise, the return value is 128 plus the number of the signal
       which caused the program to stop or terminate.

AUTHOR

       time  was  written  by  David  MacKenzie.  This  man  page  was added by Dirk Eddelbuettel
       <edd@debian.org>, the Debian  GNU/Linux  maintainer,  for  use  by  the  Debian  GNU/Linux
       distribution but may of course be used by others.

SEE ALSO

       tcsh(1), printf(3)

                                         Debian GNU/Linux                                 TIME(1)