times.3p (6049B)
- '\" et
- .TH TIMES "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- times
- \(em get process and waited-for child process times
- .SH SYNOPSIS
- .LP
- .nf
- #include <sys/times.h>
- .P
- clock_t times(struct tms *\fIbuffer\fP);
- .fi
- .SH DESCRIPTION
- The
- \fItimes\fR()
- function shall fill the
- .BR tms
- structure pointed to by
- .IR buffer
- with time-accounting information. The
- .BR tms
- structure is defined in
- .IR <sys/times.h> .
- .P
- All times are measured in terms of the number of clock ticks used.
- .P
- The times of a terminated child process shall be included in the
- .IR tms_cutime
- and
- .IR tms_cstime
- elements of the parent when
- \fIwait\fR(),
- \fIwaitid\fR(),
- or
- \fIwaitpid\fR()
- returns the process ID of this terminated child. If a child process
- has not waited for its children, their times shall not be included in
- its times.
- .IP " *" 4
- The
- .IR tms_utime
- structure member is the CPU time charged for the execution of user
- instructions of the calling process.
- .IP " *" 4
- The
- .IR tms_stime
- structure member is the CPU time charged for execution by the system on
- behalf of the calling process.
- .IP " *" 4
- The
- .IR tms_cutime
- structure member is the sum of the
- .IR tms_utime
- and
- .IR tms_cutime
- times of the child processes.
- .IP " *" 4
- The
- .IR tms_cstime
- structure member is the sum of the
- .IR tms_stime
- and
- .IR tms_cstime
- times of the child processes.
- .SH "RETURN VALUE"
- Upon successful completion,
- \fItimes\fR()
- shall return the elapsed real time, in clock ticks, since an arbitrary
- point in the past (for example, system start-up time). This point does
- not change from one invocation of
- \fItimes\fR()
- within the process to another. The return value may overflow the
- possible range of type
- .BR clock_t .
- If
- \fItimes\fR()
- fails, (\fBclock_t\fR)\-1 shall be returned and
- .IR errno
- set to indicate the error.
- .SH ERRORS
- The
- \fItimes\fR()
- function shall fail if:
- .TP
- .BR EOVERFLOW
- The return value would overflow the range of
- .BR clock_t .
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .SS "Timing a Database Lookup"
- .P
- The following example defines two functions,
- \fIstart_clock\fR()
- and
- \fIend_clock\fR(),
- that are used to time a lookup. It also defines variables of type
- .BR clock_t
- and
- .BR tms
- to measure the duration of transactions. The
- \fIstart_clock\fR()
- function saves the beginning times given by the
- \fItimes\fR()
- function. The
- \fIend_clock\fR()
- function gets the ending times and prints the difference between the
- two times.
- .sp
- .RS 4
- .nf
- #include <sys/times.h>
- #include <stdio.h>
- \&...
- void start_clock(void);
- void end_clock(char *msg);
- \&...
- static clock_t st_time;
- static clock_t en_time;
- static struct tms st_cpu;
- static struct tms en_cpu;
- \&...
- void
- start_clock()
- {
- st_time = times(&st_cpu);
- }
- .P
- /* This example assumes that the result of each subtraction
- is within the range of values that can be represented in
- an integer type. */
- void
- end_clock(char *msg)
- {
- en_time = times(&en_cpu);
- .P
- fputs(msg,stdout);
- printf("Real Time: %jd, User Time %jd, System Time %jd\en",
- (intmax_t)(en_time - st_time),
- (intmax_t)(en_cpu.tms_utime - st_cpu.tms_utime),
- (intmax_t)(en_cpu.tms_stime - st_cpu.tms_stime));
- }
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- Applications should use \fIsysconf\fP(_SC_CLK_TCK)
- to determine the number of clock ticks per second as it may vary from
- system to system.
- .SH RATIONALE
- The accuracy of the times reported is intentionally left unspecified to
- allow implementations flexibility in design, from uniprocessor to
- multi-processor networks.
- .P
- The inclusion of times of child processes is recursive, so that a
- parent process may collect the total times of all of its descendants.
- But the times of a child are only added to those of its parent when its
- parent successfully waits on the child. Thus, it is not guaranteed
- that a parent process can always see the total times of all its
- descendants; see also the discussion of the term ``realtime'' in
- .IR "\fIalarm\fR\^(\|)".
- .P
- If the type
- .BR clock_t
- is defined to be a signed 32-bit integer, it overflows in somewhat more
- than a year if there are 60 clock ticks per second,
- or less than a year if there are 100. There are individual systems
- that run continuously for longer than that. This volume of POSIX.1\(hy2017 permits an
- implementation to make the reference point for the returned value be
- the start-up time of the process, rather than system start-up time.
- .P
- The term ``charge'' in this context has nothing to do with billing
- for services. The operating system accounts for time used in this
- way. That information must be correct, regardless of how that
- information is used.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIalarm\fR\^(\|)",
- .IR "\fIexec\fR\^",
- .IR "\fIfork\fR\^(\|)",
- .IR "\fIsysconf\fR\^(\|)",
- .IR "\fItime\fR\^(\|)",
- .IR "\fIwait\fR\^(\|)",
- .IR "\fIwaitid\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<sys_times.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .