xref: /netbsd/lib/libc/gen/times.3 (revision bf9ec67e)
1.\"	$NetBSD: times.3,v 1.11 2002/02/07 07:00:18 ross 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. All advertising materials mentioning features or use of this software
15.\"    must display the following acknowledgement:
16.\"	This product includes software developed by the University of
17.\"	California, Berkeley and its contributors.
18.\" 4. Neither the name of the University nor the names of its contributors
19.\"    may be used to endorse or promote products derived from this software
20.\"    without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\"     @(#)times.3	8.1 (Berkeley) 6/4/93
35.\"
36.Dd June 4, 1993
37.Dt TIMES 3
38.Os
39.Sh NAME
40.Nm times
41.Nd process times
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.Fd #include \*[Lt]sys/times.h\*[Gt]
46.Ft clock_t
47.Fn times "struct tms *tp"
48.Sh DESCRIPTION
49.Bf -symbolic
50This interface is obsoleted by
51.Xr getrusage 2
52and
53.Xr gettimeofday 2 .
54.Ef
55.Pp
56The
57.Fn times
58function returns the value of time in
59.Dv CLK_TCK Ns 's
60of a second since
610 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal
62Time (UTC).
63.Pp
64It also fills in the structure pointed to by
65.Fa tp
66with time-accounting information.
67.Pp
68The
69.Fa tms
70structure is defined as follows:
71.Bd -literal -offset indent
72typedef struct {
73	clock_t tms_utime;
74	clock_t tms_stime;
75	clock_t tms_cutime;
76	clock_t tms_cstime;
77}
78.Ed
79.Pp
80The elements of this structure are defined as follows:
81.Bl -tag -width tms_cutime
82.It Fa tms_utime
83The
84.Tn CPU
85time charged for the execution of user instructions.
86.It Fa tms_stime
87The
88.Tn CPU
89time charged for execution by the system on behalf of
90the process.
91.It Fa tms_cutime
92The sum of the
93.Fa tms_utime  s
94and
95.Fa tms_cutime  s
96of the child processes.
97.It Fa tms_cstime
98The sum of the
99.Fa tms_stime Ns s
100and
101.Fa tms_cstime Ns s
102of the child processes.
103.El
104.Pp
105All times are in
106.Dv CLK_TCK Ns 's
107of a second.
108.Pp
109The times of a terminated child process are included in the
110.Fa tms_cutime
111and
112.Fa tms_cstime
113elements of the parent when one of the
114.Xr wait 2
115functions returns the process ID of the terminated child to the parent.
116If an error occurs,
117.Fn times
118returns the value
119.Pq (clock_t)\-1 ,
120and sets
121.Va errno
122to indicate the error.
123.Sh ERRORS
124The
125.Fn times
126function
127may fail and set the global variable
128.Va errno
129for any of the errors specified for the library
130routines
131.Xr getrusage 2
132and
133.Xr gettimeofday 2 .
134.Sh SEE ALSO
135.Xr time 1 ,
136.Xr getrusage 2 ,
137.Xr gettimeofday 2 ,
138.Xr wait 2
139.Sh STANDARDS
140The
141.Fn times
142function conforms to
143.St -p1003.1-90 .
144