unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

time(1)                          User Commands                         time(1)



NAME
       time - time a simple command

SYNOPSIS
       time [-p] utility [argument...]

DESCRIPTION
       The  time  utility  invokes utility operand with argument, and writes a
       message to standard error that lists timing statistics for utility. The
       message includes the following information:

         o  The elapsed (real) time between invocation of utility and its ter-
            mination.

         o  The User CPU time, equivalent to the  sum  of  the  tms_utime  and
            tms_cutime  fields  returned  by  the  times(2)  function  for the
            process in which utility is executed.

         o  The System CPU time, equivalent to the sum of  the  tms_stime  and
            tms_cstime fields returned by the times() function for the process
            in which utility is executed.


       When time is used as part of a pipeline, the times reported are unspec-
       ified,  except when it is the sole command within a grouping command in
       that pipeline. For example, the commands on the left  are  unspecified;
       those on the right report on utilities a and c, respectively:

       time a | b | c      { time a } | b | c
       a | b | time c      a | b | (time c)


OPTIONS
       The following option is supported:

       -p       Writes  the  timing  output to standard error in the following
                format:


                real %f\nuser %f\nsys %f\n < real seconds>, <user seconds>,
                <system seconds>



OPERANDS
       The following operands are supported:

       utility         The name of the utility that is to be invoked.



       argument        Any string to be supplied as an argument when  invoking
                       utility.



USAGE
       The  time  utility  returns  exit status 127 if an error occurs so that
       applications can distinguish "failure to find a utility" from  "invoked
       utility  exited  with  an  error  indication." The value 127 was chosen
       because it is not commonly used for other meanings. Most utilities  use
       small values for "normal error conditions" and the values above 128 can
       be confused with termination due to receipt of a signal. The value  126
       was  chosen  in  a similar manner to indicate that the utility could be
       found, but not invoked.

EXAMPLES
       Example 1: Using the time command

       It is frequently desirable to apply time to pipelines or lists of  com-
       mands.  This  can  be  done by placing pipelines and command lists in a
       single file. This single file can then be invoked as a utility, and the
       time applies to everything in the file.

       Alternatively,  the  following  command  can be used to apply time to a
       complex command:

       example% time sh -c 'complex-command-line'

       Example 2: Using time in the csh shell

       The following two examples show the differences between the csh version
       of  time  and  the version in /usr/bin/time. These examples assume that
       csh is the shell in use.

       example% time find / -name csh.1 -print
       /usr/share/man/man1/csh.1
       95.0u 692.0s 1:17:52 16% 0+0k 0+0io 0pf+0w

       See csh(1) for an explanation of the format of time output.

       example% /usr/bin/time find / -name csh.1 -print
       /usr/share/man/man1/csh.1
       real  1:23:31.5
       user     1:33.2
       sys     11:28.2

ENVIRONMENT VARIABLES
       See environ(5) for descriptions of the following environment  variables
       that affect the execution of time: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES,
       LC_NUMERIC,  NLSPATH, and PATH.

EXIT STATUS
       If utility is invoked, the exit status of time will be the exit  status
       of  utility. Otherwise, the time utility will exit with one of the fol-
       lowing values:

       1-125           An error occurred in the time utility.



       126             utility was found but could not be invoked.



       127             utility could not be found.



ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).    ATTRIBUTE   TYPEATTRIBUTE  VALUE  AvailabilitySUNWcsu
       Interface StabilityStandard


SEE ALSO
       csh(1), shell_builtins(1), timex(1), times(2), attributes(5),  environ(
       5), standards(5)

NOTES
       When  the time command is run on a multiprocessor machine, the total of
       the values printed for user and sys can exceed real. This  is   because
       on  a  multiprocessor machine it is possible to divide the task between
       the various processors.

       When the command being timed is interrupted,  the  timing  values  dis-
       played may not always be accurate.

BUGS
       Elapsed  time  is  accurate to the second, while the CPU times are mea-
       sured to the 100th second. Thus the sum of the CPU times can be up to a
       second larger than the elapsed time.



SunOS 5.10                        1 Feb 1995                           time(1)