diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/times.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/times.3p | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/times.3p b/man-pages-posix-2017/man3p/times.3p new file mode 100644 index 0000000..5e7b93e --- /dev/null +++ b/man-pages-posix-2017/man3p/times.3p @@ -0,0 +1,214 @@ +'\" 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 . |