times(S)

times -- get process and child process times

Syntax

cc ... -lc

#include <sys/types.h>
#include <sys/times.h>

clock_t times (buffer)
struct tms *buffer;

Description

The times system call fills the structure pointed to by buffer with time-accounting information. The following are the contents of this structure:

   struct  tms {
           clock_t  tms_utime;
           clock_t  tms_stime;
           clock_t  tms_cutime;
           clock_t  tms_cstime;
   };

This information comes from the calling process and each of its terminated child processes for which it has executed a wait. All times are reported in clock ticks. The number of clock ticks per second is a system-dependent parameter, which is returned by sysconf(_SC_CLK_TCK).

tms_utime is the CPU time used while executing instructions in the user space of the calling process.

tms_stime is the CPU time used by the system on behalf of the calling process.

tms_cutime is the sum of the tms_utimes and tms_cutimes of the child processes.

tms_cstime is the sum of the tms_stimes and tms_cstimes of the child processes.

Return values

Upon successful completion, times returns the elapsed real time, in clock ticks, from an arbitrary point in the past (for example, system start-up time). This point does not change from one invocation of times to another. If times fails, a -1 is returned and errno is set to indicate the error. The return value may overflow the possible range of type clock_t.

Diagnostics

[EFAULT]: The times system call fails if buffer points to an illegal address.

Examples

times( ) returns the lbolt value (discussed more fully in the Consolidated HDK documentation available at http://uw7doc.sco.com). The lbolt value becomes negative when the system stays up more than LONG_MAX clock ticks (about 248 days on current systems) so the code that calls times( ) must be coded to properly handle error conditions and valid but negative values. For example:

       clock_t l;
       unsigned long ul;
       struct tms buffer;
   
       errno = 0;
       l = times(&buffer);
       if ( l == -1 && errno != 0 )
           /* ... Its an error   ... */
       else        /* otherwise valid value but may be -ve due lbolt overflow */
           ul = (unsigned long) l;
       /* continue using ul */

Standards conformance

times is conformant with:

X/Open Portability Guide, Issue 3, 1989 ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .