usr.bin/time/time.1

   1 .\"     $NetBSD: time.1,v 1.18 2003/08/07 11:16:15 agc 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 January 24, 2009
  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 utility
  42 .Op Ar argument ...
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility
  47 executes and
  48 times
  49 .Ar utility .
  50 After the
  51 .Ar utility
  52 finishes,
  53 .Nm
  54 writes the total time elapsed,
  55 the time consumed by system overhead,
  56 and the time used to execute
  57 .Ar utility
  58 to the standard error stream.
  59 Times are reported in seconds.
  60 .Pp
  61 Available options:
  62 .Bl -tag -width Ds
  63 .It Fl c
  64 Displays the default
  65 .Xr csh 1
  66 summary format.
  67 .It Fl l
  68 Lists resource utilization information.
  69 The contents of the
  70 .Ar utility
  71 process'
  72 .Em rusage
  73 structure are printed, see below.
  74 .It Fl p
  75 The output is formatted as specified by
  76 .St -p1003.2-92 .
  77 .El
  78 .Pp
  79 Some shells, such as
  80 .Xr csh 1
  81 and
  82 .Xr ksh 1 ,
  83 have their own and syntactically different builtin version of
  84 .Nm .
  85 The utility described here
  86 is available as
  87 .Pa /usr/bin/time
  88 to users of these shells.
  89 .Ss Resource Utilization
  90 If the
  91 .Fl l
  92 option is given, the following resource usage
  93 informations are displayed
  94 in addition to the timing information:
  95 .Bl -item -offset indent -compact
  96 .It
  97 maximum resident set size
  98 .It
  99 average shared memory size
 100 .It
 101 average unshared data size
 102 .It
 103 average unshared stack size
 104 .It
 105 page reclaims
 106 .It
 107 page faults
 108 .It
 109 swaps
 110 .It
 111 block input operations
 112 .It
 113 block output operations
 114 .It
 115 messages sent
 116 .It
 117 messages received
 118 .It
 119 signals received
 120 .It
 121 voluntary context switches
 122 .It
 123 involuntary context switches
 124 .El
 125 .Sh EXIT STATUS
 126 The
 127 .Nm
 128 utility exits with one of the following values:
 129 .Bl -tag -width indent
 130 .It 1-125
 131 An error occurred in the
 132 .Nm
 133 utility.
 134 .It 126
 135 The
 136 .Ar utility
 137 was found but could not be invoked.
 138 .It 127
 139 The
 140 .Ar utility
 141 could not be found.
 142 .El
 143 .Pp
 144 Otherwise, the exit status of
 145 .Nm
 146 will be that of
 147 .Ar utility .
 148 .Sh FILES
 149 .Bl -tag -width \*[Lt]sys/resource.h\*[Gt] -compact
 150 .It \*[Lt]sys/resource.h\*[Gt]
 151 .El
 152 .Sh SEE ALSO
 153 .Xr csh 1 ,
 154 .Xr ksh 1 ,
 155 .Xr getrusage 2
 156 .Sh STANDARDS
 157 The
 158 .Nm
 159 utility conforms to
 160 .St -p1003.2-92 .
 161 .Sh BUGS
 162 The granularity of seconds on microprocessors is crude and
 163 can result in times being reported for CPU usage which are too large by
 164 a second.