usr.bin/time/time.1

   1 .\"     $NetBSD: time.1,v 1.25 2011/11/09 19:42:27 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)time.1      8.1 (Berkeley) 6/6/93
  31 .\"
  32 .Dd November 9, 2011
  33 .Dt TIME 1
  34 .Os
  35 .Sh NAME
  36 .Nm time
  37 .Nd time command execution
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Op Fl clp
  41 .Ar command
  42 .Op Ar argument ...
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility
  47 executes and
  48 times
  49 .Ar command .
  50 After the command finishes,
  51 .Nm
  52 writes the total elapsed time (wall clock time),
  53 .Pq Dq real ,
  54 the CPU time spent executing
  55 .Ar command
  56 at user level
  57 .Pq Dq user ,
  58 and the CPU time spent executing in the operating system kernel
  59 .Pq Dq sys ,
  60 to the standard error stream.
  61 Times are reported in seconds.
  62 .Pp
  63 Available options:
  64 .Bl -tag -width Ds
  65 .It Fl c
  66 Displays information in the format used by the
  67 .Nm
  68 builtin of
  69 .Xr csh 1 .
  70 .It Fl l
  71 Lists resource utilization information.
  72 The contents of the
  73 .Ar command
  74 process's
  75 .Em rusage
  76 structure are printed; see below.
  77 .It Fl p
  78 The output is formatted as specified by
  79 .St -p1003.2-92 .
  80 .El
  81 .Pp
  82 Some shells, such as
  83 .Xr csh 1
  84 and
  85 .Xr ksh 1 ,
  86 have their own and syntactically different built-in version of
  87 .Nm .
  88 The utility described here
  89 is available as
  90 .Pa /usr/bin/time
  91 to users of these shells.
  92 .Ss Resource Utilization
  93 If the
  94 .Fl l
  95 option is given, the following resource usage
  96 information is displayed
  97 in addition to the timing information:
  98 .Bl -item -offset indent -compact
  99 .It
 100 maximum resident set size
 101 .It
 102 average shared memory size
 103 .It
 104 average unshared data size
 105 .It
 106 average unshared stack size
 107 .It
 108 page reclaims
 109 .It
 110 page faults
 111 .It
 112 swaps
 113 .It
 114 block input operations
 115 .It
 116 block output operations
 117 .It
 118 messages sent
 119 .It
 120 messages received
 121 .It
 122 signals received
 123 .It
 124 voluntary context switches
 125 .It
 126 involuntary context switches
 127 .El
 128 Resource usage is the total for the execution of
 129 .Ar command
 130 and any child processes it spawns, as per
 131 .Xr wait4 2 .
 132 .Sh FILES
 133 .Bl -tag -width Xsys/resource.hX -compact
 134 .It Aq sys/resource.h
 135 .El
 136 .Sh EXIT STATUS
 137 The
 138 .Nm
 139 utility exits with one of the following values:
 140 .Bl -tag -width indent
 141 .It 1-125
 142 An error occurred in the
 143 .Nm
 144 utility.
 145 .It 126
 146 The
 147 .Ar command
 148 was found but could not be invoked.
 149 .It 127
 150 The
 151 .Ar command
 152 could not be found.
 153 .El
 154 .Pp
 155 Otherwise, the exit status of
 156 .Nm
 157 will be that of
 158 .Ar command .
 159 .Sh SEE ALSO
 160 .Xr csh 1 ,
 161 .Xr ksh 1 ,
 162 .Xr clock_gettime 2 ,
 163 .Xr getrusage 2
 164 .Sh STANDARDS
 165 The
 166 .Nm
 167 utility conforms to
 168 .St -p1003.2-92 .
 169 .Sh BUGS
 170 The granularity of seconds on microprocessors is crude and
 171 can result in times being reported for CPU usage which are too large by
 172 a second.