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

getitimer.3p (4703B)

    

  1. '\" et
  2. .TH GETITIMER "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. getitimer,
  12. setitimer
  13. \(em get and set value of interval timer
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <sys/time.h>
  18. .P
  19. int getitimer(int \fIwhich\fP, struct itimerval *\fIvalue\fP);
  20. int setitimer(int \fIwhich\fP, const struct itimerval *restrict \fIvalue\fP,
  21.     struct itimerval *restrict \fIovalue\fP);
  22. .fi
  23. .SH DESCRIPTION
  24. The
  25. \fIgetitimer\fR()
  26. function shall store the current value of the timer specified by
  27. .IR which
  28. into the structure pointed to by
  29. .IR value .
  30. The
  31. \fIsetitimer\fR()
  32. function shall set the timer specified by
  33. .IR which
  34. to the value specified in the structure pointed to by
  35. .IR value ,
  36. and if
  37. .IR ovalue
  38. is not a null pointer, store the previous value of the timer in the
  39. structure pointed to by
  40. .IR ovalue .
  41. .P
  42. A timer value is defined by the
  43. .BR itimerval
  44. structure, specified in
  45. .IR <sys/time.h> .
  46. If
  47. .IR it_value
  48. is non-zero, it shall indicate the time to the next timer expiration.
  49. If
  50. .IR it_interval
  51. is non-zero, it shall specify a value to be used in reloading
  52. .IR it_value
  53. when the timer expires. Setting
  54. .IR it_value
  55. to 0 shall disable a timer, regardless of the value of
  56. .IR it_interval .
  57. Setting
  58. .IR it_interval
  59. to 0 shall disable a timer after its next expiration (assuming
  60. .IR it_value
  61. is non-zero).
  62. .P
  63. Implementations may place limitations on the granularity of timer
  64. values. For each interval timer, if the requested timer value requires
  65. a finer granularity than the implementation supports, the actual timer
  66. value shall be rounded up to the next supported value.
  67. .P
  68. An XSI-conforming implementation provides each process with at least
  69. three interval timers, which are indicated by the
  70. .IR which
  71. argument:
  72. .IP ITIMER_PROF 14
  73. Decrements both in process virtual time and when the system is running
  74. on behalf of the process. It is designed to be used by interpreters in
  75. statistically profiling the execution of interpreted programs. Each
  76. time the ITIMER_PROF timer expires, the SIGPROF signal is delivered.
  77. .IP ITIMER_REAL 14
  78. Decrements in real time. A SIGALRM signal is delivered when this timer
  79. expires.
  80. .IP ITIMER_VIRTUAL 14
  81. Decrements in process virtual time. It runs only when the process is
  82. executing. A SIGVTALRM signal is delivered when it expires.
  83. .P
  84. The interaction between
  85. \fIsetitimer\fR()
  86. and
  87. \fIalarm\fR()
  88. or
  89. \fIsleep\fR()
  90. is unspecified.
  91. .SH "RETURN VALUE"
  92. Upon successful completion,
  93. \fIgetitimer\fR()
  94. or
  95. \fIsetitimer\fR()
  96. shall return 0; otherwise, \-1 shall be returned and
  97. .IR errno
  98. set to indicate the error.
  99. .SH ERRORS
  100. The
  101. \fIsetitimer\fR()
  102. function shall fail if:
  103. .TP
  104. .BR EINVAL
  105. The
  106. .IR value
  107. argument is not in canonical form. (In canonical form, the number of
  108. microseconds is a non-negative integer less than 1\|000\|000 and the
  109. number of seconds is a non-negative integer.)
  110. .P
  111. The
  112. \fIgetitimer\fR()
  113. and
  114. \fIsetitimer\fR()
  115. functions may fail if:
  116. .TP
  117. .BR EINVAL
  118. The
  119. .IR which
  120. argument is not recognized.
  121. .LP
  122. .IR "The following sections are informative."
  123. .SH EXAMPLES
  124. None.
  125. .SH "APPLICATION USAGE"
  126. Applications should use the
  127. \fItimer_gettime\fR()
  128. and
  129. \fItimer_settime\fR()
  130. functions instead of the obsolescent
  131. \fIgetitimer\fR()
  132. and
  133. \fIsetitimer\fR()
  134. functions, respectively.
  135. .SH RATIONALE
  136. None.
  137. .SH "FUTURE DIRECTIONS"
  138. The
  139. \fIgetitimer\fR()
  140. and
  141. \fIsetitimer\fR()
  142. functions may be removed in a future version.
  143. .SH "SEE ALSO"
  144. .IR "\fIalarm\fR\^(\|)",
  145. .IR "\fIexec\fR\^",
  146. .IR "\fIsleep\fR\^(\|)",
  147. .IR "\fItimer_getoverrun\fR\^(\|)"
  148. .P
  149. The Base Definitions volume of POSIX.1\(hy2017,
  150. .IR "\fB<signal.h>\fP",
  151. .IR "\fB<sys_time.h>\fP"
  152. .\"
  153. .SH COPYRIGHT
  154. Portions of this text are reprinted and reproduced in electronic form
  155. from IEEE Std 1003.1-2017, Standard for Information Technology
  156. -- Portable Operating System Interface (POSIX), The Open Group Base
  157. Specifications Issue 7, 2018 Edition,
  158. Copyright (C) 2018 by the Institute of
  159. Electrical and Electronics Engineers, Inc and The Open Group.
  160. In the event of any discrepancy between this version and the original IEEE and
  161. The Open Group Standard, the original IEEE and The Open Group Standard
  162. is the referee document. The original Standard can be obtained online at
  163. http://www.opengroup.org/unix/online.html .
  164. .PP
  165. Any typographical or formatting errors that appear
  166. in this page are most likely
  167. to have been introduced during the conversion of the source files to
  168. man page format. To report such errors, see
  169. https://www.kernel.org/doc/man-pages/reporting_bugs.html .