# times

## 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.
    


## NAME



           times — get process and waited-for child process times
    


## SYNOPSIS



           #include <sys/times.h>
    
           clock_t times(struct tms *_buffer_);
    


## DESCRIPTION



           The _times_() function shall fill the **tms** structure pointed to by
           _buffer_ with time-accounting information. The **tms** structure is
           defined in _< sys/times.h>_.
    
           All times are measured in terms of the number of clock ticks used.
    
           The times of a terminated child process shall be included in the
           _tms_cutime_ and _tms_cstime_ elements of the parent when _wait_(),
           _waitid_(), or _waitpid_() 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.
    
            *  The _tms_utime_ structure member is the CPU time charged for the
               execution of user instructions of the calling process.
    
            *  The _tms_stime_ structure member is the CPU time charged for
               execution by the system on behalf of the calling process.
    
            *  The _tms_cutime_ structure member is the sum of the _tms_utime_
               and _tms_cutime_ times of the child processes.
    
            *  The _tms_cstime_ structure member is the sum of the _tms_stime_
               and _tms_cstime_ times of the child processes.
    


## RETURN VALUE



           Upon successful completion, _times_() 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 _times_() within the process to another. The
           return value may overflow the possible range of type **clock_t**.  If
           _times_() fails, (**clock_t**)-1 shall be returned and _errno_ set to
           indicate the error.
    


## ERRORS



           The _times_() function shall fail if:
    
           **EOVERFLOW**
                  The return value would overflow the range of **clock_t**.
    
           _The following sections are informative._
    


## EXAMPLES



       **Timing a Database Lookup**
           The following example defines two functions, _start_clock_() and
           _end_clock_(), that are used to time a lookup. It also defines
           variables of type **clock_t** and **tms** to measure the duration of
           transactions. The _start_clock_() function saves the beginning times
           given by the _times_() function. The _end_clock_() function gets the
           ending times and prints the difference between the two times.
    
               #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);
               }
    
               /* 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);
    
                   fputs(msg,stdout);
                   printf("Real Time: %jd, User Time %jd, System Time %jd\n",
                       (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));
               }
    


## APPLICATION USAGE



           Applications should use _sysconf_(_SC_CLK_TCK) to determine the
           number of clock ticks per second as it may vary from system to
           system.
    


## RATIONALE



           The accuracy of the times reported is intentionally left
           unspecified to allow implementations flexibility in design, from
           uniprocessor to multi-processor networks.
    
           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 alarm(3p).
    
           If the type **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‐2017 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.
    
           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.
    


## FUTURE DIRECTIONS



           None.
    


* * *