man3p/sigqueue.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "SIGQUEUE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" sigqueue
   4 .SH NAME
   5 sigqueue \- queue a signal to a process (\fBREALTIME\fP)
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <signal.h>
   9 .br
  10 .sp
  11 int sigqueue(pid_t\fP \fIpid\fP\fB, int\fP \fIsigno\fP\fB, const union
  12 sigval\fP \fIvalue\fP\fB); \fP
  13 \fB
  14 .br
  15 \fP
  16 .SH DESCRIPTION
  17 .LP
  18 The \fIsigqueue\fP() function shall cause the signal specified by
  19 \fIsigno\fP to be sent with the value specified by
  20 \fIvalue\fP to the process specified by \fIpid\fP. If \fIsigno\fP
  21 is zero (the null signal), error checking is performed but no
  22 signal is actually sent. The null signal can be used to check the
  23 validity of \fIpid\fP.
  24 .LP
  25 The conditions required for a process to have permission to queue
  26 a signal to another process are the same as for the \fIkill\fP() function.
  27 .LP
  28 The \fIsigqueue\fP() function shall return immediately. If SA_SIGINFO
  29 is set for \fIsigno\fP and if the resources were
  30 available to queue the signal, the signal shall be queued and sent
  31 to the receiving process. If SA_SIGINFO is not set for
  32 \fIsigno\fP, then \fIsigno\fP shall be sent at least once to the receiving
  33 process; it is unspecified whether \fIvalue\fP shall
  34 be sent to the receiving process as a result of this call.
  35 .LP
  36 If the value of \fIpid\fP causes \fIsigno\fP to be generated for the
  37 sending process, and if \fIsigno\fP is not blocked for
  38 the calling thread and if no other thread has \fIsigno\fP unblocked
  39 or is waiting in a \fIsigwait\fP() function for \fIsigno\fP, either
  40 \fIsigno\fP or at least the pending, unblocked
  41 signal shall be delivered to the calling thread before the \fIsigqueue\fP()
  42 function returns. Should any multiple pending signals
  43 in the range SIGRTMIN to SIGRTMAX be selected for delivery, it shall
  44 be the lowest numbered one. The selection order between
  45 realtime and non-realtime signals, or between multiple pending non-realtime
  46 signals, is unspecified.
  47 .SH RETURN VALUE
  48 .LP
  49 Upon successful completion, the specified signal shall have been queued,
  50 and the \fIsigqueue\fP() function shall return a value
  51 of zero. Otherwise, the function shall return a value of -1 and set
  52 \fIerrno\fP to indicate the error.
  53 .SH ERRORS
  54 .LP
  55 The \fIsigqueue\fP() function shall fail if:
  56 .TP 7
  57 .B EAGAIN
  58 No resources are available to queue the signal. The process has already
  59 queued {SIGQUEUE_MAX} signals that are still pending at
  60 the receiver(s), or a system-wide resource limit has been exceeded.
  61 .TP 7
  62 .B EINVAL
  63 The value of the \fIsigno\fP argument is an invalid or unsupported
  64 signal number.
  65 .TP 7
  66 .B EPERM
  67 The process does not have the appropriate privilege to send the signal
  68 to the receiving process.
  69 .TP 7
  70 .B ESRCH
  71 The process \fIpid\fP does not exist.
  72 .sp
  73 .LP
  74 \fIThe following sections are informative.\fP
  75 .SH EXAMPLES
  76 .LP
  77 None.
  78 .SH APPLICATION USAGE
  79 .LP
  80 None.
  81 .SH RATIONALE
  82 .LP
  83 The \fIsigqueue\fP() function allows an application to queue a realtime
  84 signal to itself or to another process, specifying the
  85 application-defined value. This is common practice in realtime applications
  86 on existing realtime systems. It was felt that
  87 specifying another function in the \fIsig\fP... name space already
  88 carved out for signals was preferable to extending the
  89 interface to \fIkill\fP().
  90 .LP
  91 Such a function became necessary when the put/get event function of
  92 the message queues was removed. It should be noted that the
  93 \fIsigqueue\fP() function implies reduced performance in a security-conscious
  94 implementation as the access permissions between the
  95 sender and receiver have to be checked on each send when the \fIpid\fP
  96 is resolved into a target process. Such access checks were
  97 necessary only at message queue open in the previous interface.
  98 .LP
  99 The standard developers required that \fIsigqueue\fP() have the same
 100 semantics with respect to the null signal as \fIkill\fP(), and that
 101 the same permission checking be used. But because of the difficulty
 102 of
 103 implementing the "broadcast" semantic of \fIkill\fP() (for example,
 104 to process groups) and
 105 the interaction with resource allocation, this semantic was not adopted.
 106 The \fIsigqueue\fP() function queues a signal to a single
 107 process specified by the \fIpid\fP argument.
 108 .LP
 109 The \fIsigqueue\fP() function can fail if the system has insufficient
 110 resources to queue the signal. An explicit limit on the
 111 number of queued signals that a process could send was introduced.
 112 While the limit is "per-sender", this volume of
 113 IEEE\ Std\ 1003.1-2001 does not specify that the resources be part
 114 of the state of the sender. This would require either
 115 that the sender be maintained after exit until all signals that it
 116 had sent to other processes were handled or that all such
 117 signals that had not yet been acted upon be removed from the queue(s)
 118 of the receivers. This volume of
 119 IEEE\ Std\ 1003.1-2001 does not preclude this behavior, but an implementation
 120 that allocated queuing resources from a
 121 system-wide pool (with per-sender limits) and that leaves queued signals
 122 pending after the sender exits is also permitted.
 123 .SH FUTURE DIRECTIONS
 124 .LP
 125 None.
 126 .SH SEE ALSO
 127 .LP
 128 \fIRealtime Signals\fP , the Base Definitions volume of
 129 IEEE\ Std\ 1003.1-2001, \fI<signal.h>\fP
 130 .SH COPYRIGHT
 131 Portions of this text are reprinted and reproduced in electronic form
 132 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 133 -- Portable Operating System Interface (POSIX), The Open Group Base
 134 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 135 Electrical and Electronics Engineers, Inc and The Open Group. In the
 136 event of any discrepancy between this version and the original IEEE and
 137 The Open Group Standard, the original IEEE and The Open Group Standard
 138 is the referee document. The original Standard can be obtained online at
 139 http://www.opengroup.org/unix/online.html .