1.\" $NetBSD: times.3,v 1.13 2002/10/01 16:48:35 wiz 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 clock ticks since 0 hours, 0 59minutes, 0 seconds, January 1, 1970, Coordinated Universal Time (UTC). 60.Pp 61The number of clock ticks per second may be determined by calling 62.Xr sysconf 3 63with the 64.Dv _SC_CLK_TCK 65request. 66It is generally (but not always) between 60 and 1024. 67.Pp 68Note that at the common rate of 100 ticks per second on many 69.Nx 70ports, and with a 32-bit unsigned clock_t, this value first wrapped in 1971. 71.Pp 72The 73.Fn times 74call also fills in the structure pointed to by 75.Fa tp 76with time-accounting information. 77.Pp 78The 79.Fa tms 80structure is defined as follows: 81.Bd -literal -offset indent 82typedef struct { 83 clock_t tms_utime; 84 clock_t tms_stime; 85 clock_t tms_cutime; 86 clock_t tms_cstime; 87} 88.Ed 89.Pp 90The elements of this structure are defined as follows: 91.Bl -tag -width tms_cutime 92.It Fa tms_utime 93The 94.Tn CPU 95time charged for the execution of user instructions. 96.It Fa tms_stime 97The 98.Tn CPU 99time charged for execution by the system on behalf of 100the process. 101.It Fa tms_cutime 102The sum of the 103.Fa tms_utime s 104and 105.Fa tms_cutime s 106of the child processes. 107.It Fa tms_cstime 108The sum of the 109.Fa tms_stime Ns s 110and 111.Fa tms_cstime Ns s 112of the child processes. 113.El 114.Pp 115All times are measured in clock ticks, as defined above. 116Note that at 100 ticks per second, 117and with a 32-bit unsigned clock_t, 118the values wrap after 497 days. 119.Pp 120The times of a terminated child process are included in the 121.Fa tms_cutime 122and 123.Fa tms_cstime 124elements of the parent when one of the 125.Xr wait 2 126functions returns the process ID of the terminated child to the parent. 127If an error occurs, 128.Fn times 129returns the value 130.Pq (clock_t)\-1 , 131and sets 132.Va errno 133to indicate the error. 134.Sh ERRORS 135The 136.Fn times 137function 138may fail and set the global variable 139.Va errno 140for any of the errors specified for the library 141routines 142.Xr getrusage 2 143and 144.Xr gettimeofday 2 . 145.Sh SEE ALSO 146.Xr time 1 , 147.Xr getrusage 2 , 148.Xr gettimeofday 2 , 149.Xr wait 2 , 150.Xr sysconf 3 151.Sh STANDARDS 152The 153.Fn times 154function conforms to 155.St -p1003.1-90 . 156