logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

times.3p (6049B)


  1. '\" et
  2. .TH TIMES "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. times
  12. \(em get process and waited-for child process times
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/times.h>
  17. .P
  18. clock_t times(struct tms *\fIbuffer\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fItimes\fR()
  23. function shall fill the
  24. .BR tms
  25. structure pointed to by
  26. .IR buffer
  27. with time-accounting information. The
  28. .BR tms
  29. structure is defined in
  30. .IR <sys/times.h> .
  31. .P
  32. All times are measured in terms of the number of clock ticks used.
  33. .P
  34. The times of a terminated child process shall be included in the
  35. .IR tms_cutime
  36. and
  37. .IR tms_cstime
  38. elements of the parent when
  39. \fIwait\fR(),
  40. \fIwaitid\fR(),
  41. or
  42. \fIwaitpid\fR()
  43. returns the process ID of this terminated child. If a child process
  44. has not waited for its children, their times shall not be included in
  45. its times.
  46. .IP " *" 4
  47. The
  48. .IR tms_utime
  49. structure member is the CPU time charged for the execution of user
  50. instructions of the calling process.
  51. .IP " *" 4
  52. The
  53. .IR tms_stime
  54. structure member is the CPU time charged for execution by the system on
  55. behalf of the calling process.
  56. .IP " *" 4
  57. The
  58. .IR tms_cutime
  59. structure member is the sum of the
  60. .IR tms_utime
  61. and
  62. .IR tms_cutime
  63. times of the child processes.
  64. .IP " *" 4
  65. The
  66. .IR tms_cstime
  67. structure member is the sum of the
  68. .IR tms_stime
  69. and
  70. .IR tms_cstime
  71. times of the child processes.
  72. .SH "RETURN VALUE"
  73. Upon successful completion,
  74. \fItimes\fR()
  75. shall return the elapsed real time, in clock ticks, since an arbitrary
  76. point in the past (for example, system start-up time). This point does
  77. not change from one invocation of
  78. \fItimes\fR()
  79. within the process to another. The return value may overflow the
  80. possible range of type
  81. .BR clock_t .
  82. If
  83. \fItimes\fR()
  84. fails, (\fBclock_t\fR)\-1 shall be returned and
  85. .IR errno
  86. set to indicate the error.
  87. .SH ERRORS
  88. The
  89. \fItimes\fR()
  90. function shall fail if:
  91. .TP
  92. .BR EOVERFLOW
  93. The return value would overflow the range of
  94. .BR clock_t .
  95. .LP
  96. .IR "The following sections are informative."
  97. .SH EXAMPLES
  98. .SS "Timing a Database Lookup"
  99. .P
  100. The following example defines two functions,
  101. \fIstart_clock\fR()
  102. and
  103. \fIend_clock\fR(),
  104. that are used to time a lookup. It also defines variables of type
  105. .BR clock_t
  106. and
  107. .BR tms
  108. to measure the duration of transactions. The
  109. \fIstart_clock\fR()
  110. function saves the beginning times given by the
  111. \fItimes\fR()
  112. function. The
  113. \fIend_clock\fR()
  114. function gets the ending times and prints the difference between the
  115. two times.
  116. .sp
  117. .RS 4
  118. .nf
  119. #include <sys/times.h>
  120. #include <stdio.h>
  121. \&...
  122. void start_clock(void);
  123. void end_clock(char *msg);
  124. \&...
  125. static clock_t st_time;
  126. static clock_t en_time;
  127. static struct tms st_cpu;
  128. static struct tms en_cpu;
  129. \&...
  130. void
  131. start_clock()
  132. {
  133. st_time = times(&st_cpu);
  134. }
  135. .P
  136. /* This example assumes that the result of each subtraction
  137. is within the range of values that can be represented in
  138. an integer type. */
  139. void
  140. end_clock(char *msg)
  141. {
  142. en_time = times(&en_cpu);
  143. .P
  144. fputs(msg,stdout);
  145. printf("Real Time: %jd, User Time %jd, System Time %jd\en",
  146. (intmax_t)(en_time - st_time),
  147. (intmax_t)(en_cpu.tms_utime - st_cpu.tms_utime),
  148. (intmax_t)(en_cpu.tms_stime - st_cpu.tms_stime));
  149. }
  150. .fi
  151. .P
  152. .RE
  153. .SH "APPLICATION USAGE"
  154. Applications should use \fIsysconf\fP(_SC_CLK_TCK)
  155. to determine the number of clock ticks per second as it may vary from
  156. system to system.
  157. .SH RATIONALE
  158. The accuracy of the times reported is intentionally left unspecified to
  159. allow implementations flexibility in design, from uniprocessor to
  160. multi-processor networks.
  161. .P
  162. The inclusion of times of child processes is recursive, so that a
  163. parent process may collect the total times of all of its descendants.
  164. But the times of a child are only added to those of its parent when its
  165. parent successfully waits on the child. Thus, it is not guaranteed
  166. that a parent process can always see the total times of all its
  167. descendants; see also the discussion of the term ``realtime'' in
  168. .IR "\fIalarm\fR\^(\|)".
  169. .P
  170. If the type
  171. .BR clock_t
  172. is defined to be a signed 32-bit integer, it overflows in somewhat more
  173. than a year if there are 60 clock ticks per second,
  174. or less than a year if there are 100. There are individual systems
  175. that run continuously for longer than that. This volume of POSIX.1\(hy2017 permits an
  176. implementation to make the reference point for the returned value be
  177. the start-up time of the process, rather than system start-up time.
  178. .P
  179. The term ``charge'' in this context has nothing to do with billing
  180. for services. The operating system accounts for time used in this
  181. way. That information must be correct, regardless of how that
  182. information is used.
  183. .SH "FUTURE DIRECTIONS"
  184. None.
  185. .SH "SEE ALSO"
  186. .IR "\fIalarm\fR\^(\|)",
  187. .IR "\fIexec\fR\^",
  188. .IR "\fIfork\fR\^(\|)",
  189. .IR "\fIsysconf\fR\^(\|)",
  190. .IR "\fItime\fR\^(\|)",
  191. .IR "\fIwait\fR\^(\|)",
  192. .IR "\fIwaitid\fR\^(\|)"
  193. .P
  194. The Base Definitions volume of POSIX.1\(hy2017,
  195. .IR "\fB<sys_times.h>\fP"
  196. .\"
  197. .SH COPYRIGHT
  198. Portions of this text are reprinted and reproduced in electronic form
  199. from IEEE Std 1003.1-2017, Standard for Information Technology
  200. -- Portable Operating System Interface (POSIX), The Open Group Base
  201. Specifications Issue 7, 2018 Edition,
  202. Copyright (C) 2018 by the Institute of
  203. Electrical and Electronics Engineers, Inc and The Open Group.
  204. In the event of any discrepancy between this version and the original IEEE and
  205. The Open Group Standard, the original IEEE and The Open Group Standard
  206. is the referee document. The original Standard can be obtained online at
  207. http://www.opengroup.org/unix/online.html .
  208. .PP
  209. Any typographical or formatting errors that appear
  210. in this page are most likely
  211. to have been introduced during the conversion of the source files to
  212. man page format. To report such errors, see
  213. https://www.kernel.org/doc/man-pages/reporting_bugs.html .