👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for time (linux section 1posix)

TIME(P) 			    POSIX Programmer's Manual				  TIME(P)

NAME
       time - time a simple command

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

DESCRIPTION
       The time utility shall invoke the utility named by the utility operand with arguments sup-
       plied as the argument operands and write a message to standard  error  that  lists  timing
       statistics for the utility. The message shall include the following information:

	* The elapsed (real) time between invocation of utility and its termination.

	* The  User  CPU  time,  equivalent  to  the  sum  of the tms_utime and tms_cutime fields
	  returned  by	the  times()  function	defined  in  the  System  Interfaces  volume   of
	  IEEE Std 1003.1-2001 for the process in which utility is executed.

	* 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.

       The precision of the timing shall be no less than the granularity defined for the size  of
       the  clock tick unit on the system, but the results shall be reported in terms of standard
       time units (for example, 0.02 seconds, 00:00:00.02, 1m33.75s, 365.21 seconds), not numbers
       of clock ticks.

       When  time  is used as part of a pipeline, the times reported are unspecified, except when
       it is the sole command within a grouping command (see Grouping Commands )  in  that  pipe-
       line.  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 time utility shall conform to the Base  Definitions	volume	of  IEEE Std 1003.1-2001,
       Section 12.2, Utility Syntax Guidelines.

       The following option shall be supported:

       -p     Write  the  timing  output to standard error in the format shown in the STDERR sec-
	      tion.

OPERANDS
       The following operands shall be supported:

       utility
	      The name of a utility that is to be invoked. If the utility operand  names  any  of
	      the  special  built-in  utilities  in  Special Built-In Utilities , the results are
	      undefined.

       argument
	      Any string to be supplied as an argument when invoking the  utility  named  by  the
	      utility operand.

STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of time:

       LANG   Provide  a  default  value for the internationalization variables that are unset or
	      null. (See the Base Definitions volume of IEEE Std 1003.1-2001, Section 8.2, Inter-
	      nationalization Variables for the precedence of internationalization variables used
	      to determine the values of locale categories.)

       LC_ALL If set to a non-empty string value, override the values of all the  other  interna-
	      tionalization variables.

       LC_CTYPE
	      Determine  the  locale for the interpretation of sequences of bytes of text data as
	      characters (for example, single-byte as opposed to multi-byte characters	in  argu-
	      ments).

       LC_MESSAGES
	      Determine the locale that should be used to affect the format and contents of diag-
	      nostic and informative messages written to standard error.

       LC_NUMERIC

	      Determine the locale for numeric formatting.

       NLSPATH
	      Determine the location of message catalogs for the processing of LC_MESSAGES .

       PATH   Determine the search path that shall be used to locate the utility to  be  invoked;
	      see  the	Base  Definitions  volume of IEEE Std 1003.1-2001, Chapter 8, Environment
	      Variables.

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       Not used.

STDERR
       The standard error shall be used to write the timing statistics. If -p is  specified,  the
       following format shall be used in the POSIX locale:

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

       where  each floating-point number shall be expressed in seconds. The precision used may be
       less than the default six digits of %f , but shall be sufficiently precise to  accommodate
       the  size  of  the clock tick on the system (for example, if there were 60 clock ticks per
       second, at least two digits shall follow the radix character). The number of  digits  fol-
       lowing  the  radix  character  shall be no less than one, even if this always results in a
       trailing zero. The implementation may append white space and additional	information  fol-
       lowing the format shown here.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       If  the	utility  utility  is invoked, the exit status of time shall be the exit status of
       utility; otherwise, the time utility shall exit with one of the following values:

       1-125  An error occurred in the time utility.

	 126  The utility specified by utility was found but could not be invoked.

	 127  The utility specified by utility could not be found.

CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       The command, env, nice, nohup, time, and xargs utilities have been specified to	use  exit
       code  127 if an error occurs so that applications can distinguish "failure to find a util-
       ity" 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. Some scripts produce  meaningful  error  messages
       differentiating	the  126 and 127 cases. The distinction between exit codes 126 and 127 is
       based on KornShell practice that uses 127 when all attempts to exec the utility fail  with
       [ENOENT], and uses 126 when any attempt to exec the utility fails for any other reason.

EXAMPLES
       It  is  frequently  desirable to apply time to pipelines or lists of commands. This can be
       done by placing pipelines and command lists in a  single  file;	this  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:

	      time sh -c 'complex-command-line'

RATIONALE
       When the time utility was originally proposed to be included in the ISO POSIX-2:1993 stan-
       dard, questions were raised about its suitability for inclusion on the grounds that it was
       not useful for conforming applications, specifically:

	* The	 underlying    CPU   definitions   from   the	System	 Interfaces   volume   of
	  IEEE Std 1003.1-2001 are vague, so the numeric output could not be compared  accurately
	  between systems or even between invocations.

	* The  creation  of  portable  benchmark  programs  was  outside the scope this volume of
	  IEEE Std 1003.1-2001.

       However, time does fit in the scope of user portability. Human judgement can be applied to
       the  analysis of the output, and it could be very useful in hands-on debugging of applica-
       tions or in providing subjective  measures  of  system  performance.  Hence  it	has  been
       included in this volume of IEEE Std 1003.1-2001.

       The  default  output  format  has been left unspecified because historical implementations
       differ greatly in their style of depicting this numeric output. The -p option was invented
       to provide scripts with a common means of obtaining this information.

       In  the	KornShell, time is a shell reserved word that can be used to time an entire pipe-
       line, rather than just a simple command. The POSIX definition has  been	worded	to  allow
       this implementation.  Consideration was given to invalidating this approach because of the
       historical model from the C shell and System V shell.  However, since the  System  V  time
       utility	historically  has  not	produced accurate results in pipeline timing (because the
       constituent processes are not all owned by the same parent process, as allowed by  POSIX),
       it did not seem worthwhile to break historical KornShell usage.

       The  term  utility is used, rather than command, to highlight the fact that shell compound
       commands, pipelines, special built-ins, and so on, cannot be used directly. However, util-
       ity includes user application programs and shell scripts, not just the standard utilities.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Shell  Command  Language  ,  sh	,  the	System Interfaces volume of IEEE Std 1003.1-2001,
       times()

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					  TIME(P)


All times are GMT -4. The time now is 05:16 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password