share/man/man2/times.2

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH TIMES 2 "May 14, 1997"
   7 .SH NAME
   8 times \- get process and child process times
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/times.h>
  13 #include <limits.h>
  14
  15 \fBclock_t\fR \fBtimes\fR(\fBstruct tms *\fR\fIbuffer\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBtimes()\fR function fills the \fBtms\fR structure pointed to by
  22 \fIbuffer\fR with time-accounting information. The \fBtms\fR structure, defined
  23 in \fB<sys/times.h>\fR, contains the following members:
  24 .sp
  25 .in +2
  26 .nf
  27 clock_t    tms_utime;
  28 clock_t    tms_stime;
  29 clock_t    tms_cutime;
  30 clock_t    tms_cstime;
  31 .fi
  32 .in -2
  33
  34 .sp
  35 .LP
  36 All times are reported in clock ticks. The specific value for a clock tick is
  37 defined by the variable \fBCLK_TCK\fR, found in the header <\fBlimits.h\fR>.
  38 .sp
  39 .LP
  40 The times of a terminated child process are included in the \fBtms_cutime\fR
  41 and \fBtms_cstime\fR members of the parent when \fBwait\fR(3C) or
  42 \fBwaitpid\fR(3C) returns the process \fBID\fR of this terminated child.  If a
  43 child process has not waited for its children, their times will not be included
  44 in its times.
  45 .sp
  46 .LP
  47 The \fBtms_utime\fR member is the \fBCPU\fR time used while executing
  48 instructions in the user space of the calling process.
  49 .sp
  50 .LP
  51 The \fBtms_stime\fR member is the \fBCPU\fR time used by the system on behalf
  52 of the calling process.
  53 .sp
  54 .LP
  55 The \fBtms_cutime\fR member is the sum of the \fBtms_utime\fR and the
  56 \fBtms_cutime\fR of the child processes.
  57 .sp
  58 .LP
  59 The \fBtms_cstime\fR member is the sum of the \fBtms_stime\fR and the
  60 \fBtms_cstime\fR of the child processes.
  61 .SH RETURN VALUES
  62 .sp
  63 .LP
  64 Upon successful completion, \fBtimes()\fR returns the elapsed real time, in
  65 clock ticks, since an arbitrary point in the past (for example, system start-up
  66 time). This point does not change from one invocation of \fBtimes()\fR within
  67 the process to another. The return value may overflow the possible range of
  68 type \fBclock_t\fR. If \fBtimes()\fR fails, \fB(clock_t)\(mi1\fR is returned
  69 and \fBerrno\fR is set to indicate the error.
  70 .SH ERRORS
  71 .sp
  72 .LP
  73 The \fBtimes()\fR function will fail if:
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fBEFAULT\fR\fR
  78 .ad
  79 .RS 10n
  80 The \fIbuffer\fR argument points to an illegal address.
  81 .RE
  82
  83 .SH ATTRIBUTES
  84 .sp
  85 .LP
  86 See \fBattributes\fR(5) for descriptions of the following attributes:
  87 .sp
  88
  89 .sp
  90 .TS
  91 box;
  92 c | c
  93 l | l .
  94 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  95 _
  96 Interface Stability     Standard
  97 _
  98 MT-Level        Async-Signal-Safe
  99 .TE
 100
 101 .SH SEE ALSO
 102 .sp
 103 .LP
 104 \fBtime\fR(1), \fBtimex\fR(1), \fBexec\fR(2), \fBfork\fR(2), \fBtime\fR(2),
 105 \fBwaitid\fR(2), \fBwait\fR(3C), \fBwaitpid\fR(3C), \fBattributes\fR(5),
 106 \fBstandards\fR(5)