lib/libc/gen/times.3

   1 .\"     $NetBSD: times.3,v 1.15 2003/08/07 16:42:58 agc Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 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 .\"     @(#)times.3     8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd June 4, 1993
  33 .Dt TIMES 3
  34 .Os
  35 .Sh NAME
  36 .Nm times
  37 .Nd process times
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/times.h
  42 .Ft clock_t
  43 .Fn times "struct tms *tp"
  44 .Sh DESCRIPTION
  45 .Bf -symbolic
  46 This interface is obsoleted by
  47 .Xr getrusage 2
  48 and
  49 .Xr gettimeofday 2 .
  50 .Ef
  51 .Pp
  52 The
  53 .Fn times
  54 function returns the value of time in clock ticks since 0 hours, 0
  55 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time (UTC).
  56 .Pp
  57 The number of clock ticks per second may be determined by calling
  58 .Xr sysconf 3
  59 with the
  60 .Dv _SC_CLK_TCK
  61 request.
  62 It is generally (but not always) between 60 and 1024.
  63 .Pp
  64 Note that at the common rate of 100 ticks per second on many
  65 .Nx
  66 ports, and with a 32-bit unsigned clock_t, this value first wrapped in 1971.
  67 .Pp
  68 The
  69 .Fn times
  70 call also fills in the structure pointed to by
  71 .Fa tp
  72 with time-accounting information.
  73 .Pp
  74 The
  75 .Fa tms
  76 structure is defined as follows:
  77 .Bd -literal -offset indent
  78 typedef struct {
  79         clock_t tms_utime;
  80         clock_t tms_stime;
  81         clock_t tms_cutime;
  82         clock_t tms_cstime;
  83 }
  84 .Ed
  85 .Pp
  86 The elements of this structure are defined as follows:
  87 .Bl -tag -width tms_cutime
  88 .It Fa tms_utime
  89 The
  90 .Tn CPU
  91 time charged for the execution of user instructions.
  92 .It Fa tms_stime
  93 The
  94 .Tn CPU
  95 time charged for execution by the system on behalf of
  96 the process.
  97 .It Fa tms_cutime
  98 The sum of the
  99 .Fa tms_utime  s
 100 and
 101 .Fa tms_cutime  s
 102 of the child processes.
 103 .It Fa tms_cstime
 104 The sum of the
 105 .Fa tms_stime Ns s
 106 and
 107 .Fa tms_cstime Ns s
 108 of the child processes.
 109 .El
 110 .Pp
 111 All times are measured in clock ticks, as defined above.
 112 Note that at 100 ticks per second,
 113 and with a 32-bit unsigned clock_t,
 114 the values wrap after 497 days.
 115 .Pp
 116 The times of a terminated child process are included in the
 117 .Fa tms_cutime
 118 and
 119 .Fa tms_cstime
 120 elements of the parent when one of the
 121 .Xr wait 2
 122 functions returns the process ID of the terminated child to the parent.
 123 If an error occurs,
 124 .Fn times
 125 returns the value
 126 .Pq (clock_t)\-1 ,
 127 and sets
 128 .Va errno
 129 to indicate the error.
 130 .Sh ERRORS
 131 The
 132 .Fn times
 133 function
 134 may fail and set the global variable
 135 .Va errno
 136 for any of the errors specified for the library
 137 routines
 138 .Xr getrusage 2
 139 and
 140 .Xr gettimeofday 2 .
 141 .Sh SEE ALSO
 142 .Xr time 1 ,
 143 .Xr getrusage 2 ,
 144 .Xr gettimeofday 2 ,
 145 .Xr wait 2 ,
 146 .Xr sysconf 3
 147 .Sh STANDARDS
 148 The
 149 .Fn times
 150 function conforms to
 151 .St -p1003.1-90 .