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

sigqueue.3p (6161B)


  1. '\" et
  2. .TH SIGQUEUE "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. sigqueue
  12. \(em queue a signal to a process
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <signal.h>
  17. .P
  18. int sigqueue(pid_t \fIpid\fP, int \fIsigno\fP, union sigval \fIvalue\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIsigqueue\fR()
  23. function shall cause the signal specified by
  24. .IR signo
  25. to be sent with the value specified by
  26. .IR value
  27. to the process specified by
  28. .IR pid .
  29. If
  30. .IR signo
  31. is zero (the null signal), error checking is performed but no signal is
  32. actually sent. The null signal can be used to check the validity of
  33. .IR pid .
  34. .P
  35. The conditions required for a process to have permission to queue a
  36. signal to another process are the same as for the
  37. \fIkill\fR()
  38. function.
  39. .P
  40. The
  41. \fIsigqueue\fR()
  42. function shall return immediately. If SA_SIGINFO is set for
  43. .IR signo
  44. and if the resources were available to queue the signal, the signal
  45. shall be queued and sent to the receiving process. If SA_SIGINFO is not
  46. set for
  47. .IR signo ,
  48. then
  49. .IR signo
  50. shall be sent at least once to the receiving process; it is unspecified
  51. whether
  52. .IR value
  53. shall be sent to the receiving process as a result of this call.
  54. .P
  55. If the value of
  56. .IR pid
  57. causes
  58. .IR signo
  59. to be generated for the sending process, and if
  60. .IR signo
  61. is not blocked for the calling thread and if no other thread has
  62. .IR signo
  63. unblocked or is waiting in a
  64. \fIsigwait\fR()
  65. function for
  66. .IR signo ,
  67. either
  68. .IR signo
  69. or at least the pending, unblocked signal shall be delivered to the
  70. calling thread before the
  71. \fIsigqueue\fR()
  72. function returns. Should any multiple pending signals in the range
  73. SIGRTMIN to
  74. SIGRTMAX be selected for delivery, it shall be the lowest numbered one.
  75. The selection order between realtime and non-realtime signals, or
  76. between multiple pending non-realtime signals, is unspecified.
  77. .SH "RETURN VALUE"
  78. Upon successful completion, the specified signal shall have been
  79. queued, and the
  80. \fIsigqueue\fR()
  81. function shall return a value of zero. Otherwise, the function shall
  82. return a value of \-1 and set
  83. .IR errno
  84. to indicate the error.
  85. .SH ERRORS
  86. The
  87. \fIsigqueue\fR()
  88. function shall fail if:
  89. .TP
  90. .BR EAGAIN
  91. No resources are available to queue the signal. The process has already
  92. queued
  93. {SIGQUEUE_MAX}
  94. signals that are still pending at the receiver(s), or a system-wide
  95. resource limit has been exceeded.
  96. .TP
  97. .BR EINVAL
  98. The value of the
  99. .IR signo
  100. argument is an invalid or unsupported signal number.
  101. .TP
  102. .BR EPERM
  103. The process does not have appropriate privileges to send the signal
  104. to the receiving process.
  105. .TP
  106. .BR ESRCH
  107. The process
  108. .IR pid
  109. does not exist.
  110. .LP
  111. .IR "The following sections are informative."
  112. .SH EXAMPLES
  113. None.
  114. .SH "APPLICATION USAGE"
  115. None.
  116. .SH RATIONALE
  117. The
  118. \fIsigqueue\fR()
  119. function allows an application to queue a realtime signal to itself or
  120. to another process, specifying the application-defined value. This is
  121. common practice in realtime applications on existing realtime systems.
  122. It was felt that specifying another function in the
  123. .IR sig .\|.\|.
  124. name space already carved out for signals was preferable to extending
  125. the interface to
  126. \fIkill\fR().
  127. .P
  128. Such a function became necessary when the put/get event function of
  129. the message queues was removed. It should be noted that the
  130. \fIsigqueue\fR()
  131. function implies reduced performance in a security-conscious
  132. implementation as the access permissions between the sender and
  133. receiver have to be checked on each send when the
  134. .IR pid
  135. is resolved into a target process. Such access checks were necessary
  136. only at message queue open in the previous interface.
  137. .P
  138. The standard developers required that
  139. \fIsigqueue\fR()
  140. have the same semantics with respect to the null signal as
  141. \fIkill\fR(),
  142. and that the same permission checking be used. But because of the
  143. difficulty of implementing the ``broadcast'' semantic of
  144. \fIkill\fR()
  145. (for example, to process groups) and the interaction with resource
  146. allocation, this semantic was not adopted. The
  147. \fIsigqueue\fR()
  148. function queues a signal to a single process specified by the
  149. .IR pid
  150. argument.
  151. .P
  152. The
  153. \fIsigqueue\fR()
  154. function can fail if the system has insufficient resources to queue the
  155. signal. An explicit limit on the number of queued signals that a
  156. process could send was introduced. While the limit is ``per-sender'',
  157. \&this volume of POSIX.1\(hy2017 does not specify that the resources be part of the state
  158. of the sender. This would require either that the sender be maintained
  159. after exit until all signals that it had sent to other processes were
  160. handled or that all such signals that had not yet been acted upon be
  161. removed from the queue(s) of the receivers. This volume of POSIX.1\(hy2017 does not
  162. preclude this behavior, but an implementation that allocated queuing
  163. resources from a system-wide pool (with per-sender limits) and that
  164. leaves queued signals pending after the sender exits is also
  165. permitted.
  166. .SH "FUTURE DIRECTIONS"
  167. None.
  168. .SH "SEE ALSO"
  169. .IR "Section 2.8.1" ", " "Realtime Signals"
  170. .P
  171. The Base Definitions volume of POSIX.1\(hy2017,
  172. .IR "\fB<signal.h>\fP"
  173. .\"
  174. .SH COPYRIGHT
  175. Portions of this text are reprinted and reproduced in electronic form
  176. from IEEE Std 1003.1-2017, Standard for Information Technology
  177. -- Portable Operating System Interface (POSIX), The Open Group Base
  178. Specifications Issue 7, 2018 Edition,
  179. Copyright (C) 2018 by the Institute of
  180. Electrical and Electronics Engineers, Inc and The Open Group.
  181. In the event of any discrepancy between this version and the original IEEE and
  182. The Open Group Standard, the original IEEE and The Open Group Standard
  183. is the referee document. The original Standard can be obtained online at
  184. http://www.opengroup.org/unix/online.html .
  185. .PP
  186. Any typographical or formatting errors that appear
  187. in this page are most likely
  188. to have been introduced during the conversion of the source files to
  189. man page format. To report such errors, see
  190. https://www.kernel.org/doc/man-pages/reporting_bugs.html .