Annotation of src/lib/libc/gen/times.3, Revision 1.15
1.15 ! agc 1: .\" $NetBSD: times.3,v 1.14 2003/04/16 13:34:39 wiz Exp $
1.4 cgd 2: .\"
3: .\" Copyright (c) 1990, 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 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.
1.15 ! agc 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 cgd 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: .\"
1.4 cgd 30: .\" @(#)times.3 8.1 (Berkeley) 6/4/93
1.1 cgd 31: .\"
1.4 cgd 32: .Dd June 4, 1993
1.1 cgd 33: .Dt TIMES 3
1.9 garbled 34: .Os
1.1 cgd 35: .Sh NAME
36: .Nm times
37: .Nd process times
1.6 perry 38: .Sh LIBRARY
39: .Lb libc
1.1 cgd 40: .Sh SYNOPSIS
1.14 wiz 41: .In sys/times.h
1.10 wiz 42: .Ft clock_t
1.1 cgd 43: .Fn times "struct tms *tp"
44: .Sh DESCRIPTION
45: .Bf -symbolic
1.7 fair 46: This interface is obsoleted by
47: .Xr getrusage 2
48: and
1.8 fair 49: .Xr gettimeofday 2 .
1.1 cgd 50: .Ef
51: .Pp
52: The
53: .Fn times
1.12 perry 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).
1.1 cgd 56: .Pp
1.12 perry 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
1.13 wiz 61: request.
62: It is generally (but not always) between 60 and 1024.
1.12 perry 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
1.1 cgd 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
1.13 wiz 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.
1.1 cgd 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 ,
1.10 wiz 127: and sets
1.3 jtc 128: .Va errno
129: to indicate the error.
1.1 cgd 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 ,
1.12 perry 145: .Xr wait 2 ,
146: .Xr sysconf 3
1.1 cgd 147: .Sh STANDARDS
148: The
149: .Fn times
1.5 kleink 150: function conforms to
151: .St -p1003.1-90 .
CVSweb <webmaster@jp.NetBSD.org>