lib/libc/sys/sigqueue.2

   1 .\" $NetBSD: sigqueue.2,v 1.3 2013/02/14 09:31:48 wiz Exp $
   2 .\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice(s), this list of conditions and the following disclaimer as
  10 .\"    the first lines of this file unmodified other than the possible
  11 .\"    addition of one or more copyright notices.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice(s), this list of conditions and the following disclaimer in
  14 .\"    the documentation and/or other materials provided with the
  15 .\"    distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  18 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  20 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
  21 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  24 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  25 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  26 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  27 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD: src/lib/libc/sys/sigqueue.2,v 1.8 2006/09/17 21:27:34 ru Exp $
  30 .\"
  31 .Dd January 9, 2011
  32 .Dt SIGQUEUE 2
  33 .Os
  34 .Sh NAME
  35 .Nm sigqueue
  36 .Nd queue a signal to a process (REALTIME)
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In signal.h
  41 .Ft int
  42 .Fn sigqueue "pid_t pid" "int signo" "const union sigval value"
  43 .Ft int
  44 .Fn sigqueueinfo "pid_t pid" "const siginfo_t *info"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn sigqueue
  48 system call causes the signal specified by
  49 .Fa signo
  50 to be sent with the value specified by
  51 .Fa value
  52 to the process specified by
  53 .Fa pid .
  54 If
  55 .Fa signo
  56 is zero (the null signal), error checking is performed but
  57 no signal is actually sent.
  58 The null signal can be used to check the
  59 validity of PID.
  60 .Pp
  61 The conditions required for a process to have permission to queue a
  62 signal to another process are the same as for the
  63 .Xr kill 2
  64 system call.
  65 The
  66 .Fn sigqueue
  67 system call queues a signal to a single process specified by the
  68 .Fa pid
  69 argument.
  70 .Pp
  71 The
  72 .Fn sigqueue
  73 system call is implemented using
  74 .Fn sigqueueinfo
  75 and passing the appropriate information in the
  76 .Fa info
  77 argument.
  78 .Pp
  79 The
  80 .Fn sigqueue
  81 system call returns immediately.
  82 If the resources were
  83 available to queue the signal, the signal will be queued and sent to
  84 the receiving process.
  85 .Pp
  86 If the value of
  87 .Fa pid
  88 causes
  89 .Fa signo
  90 to be generated for the sending process, and if
  91 .Fa signo
  92 is not blocked for the calling thread and if no other thread has
  93 .Fa signo
  94 unblocked or is waiting in a
  95 .Fn sigwait
  96 system call for
  97 .Fa signo ,
  98 either
  99 .Fa signo
 100 or at least the pending, unblocked signal will be delivered to the
 101 calling thread before
 102 .Fn sigqueue
 103 returns.
 104 Should any multiple pending signals in the range
 105 .Dv SIGRTMIN
 106 to
 107 .Dv SIGRTMAX
 108 be selected for delivery, it is the lowest numbered
 109 one.
 110 The selection order between realtime and non-realtime signals, or
 111 between multiple pending non-realtime signals, is unspecified.
 112 .Sh RETURN VALUES
 113 .Rv -std
 114 .Sh ERRORS
 115 The
 116 .Fn sigqueue
 117 system call
 118 will fail if:
 119 .Bl -tag -width Er
 120 .It Bq Er EAGAIN
 121 No resources are available to queue the signal.
 122 The process has already queued
 123 .Brq Dv SIGQUEUE_MAX
 124 signals that are still pending at the receiver(s),
 125 or a system-wide resource limit has been exceeded.
 126 .It Bq Er EINVAL
 127 The value of the
 128 .Fa signo
 129 argument is an invalid or unsupported signal number.
 130 .It Bq Er EPERM
 131 The process does not have the appropriate privilege to send the signal
 132 to the receiving process.
 133 .It Bq Er ESRCH
 134 The process
 135 .Fa pid
 136 does not exist.
 137 .El
 138 .Sh SEE ALSO
 139 .Xr sigaction 2 ,
 140 .Xr siginfo 2 ,
 141 .Xr sigpending 2 ,
 142 .Xr sigsuspend 2 ,
 143 .Xr sigtimedwait 2 ,
 144 .Xr sigwait 2 ,
 145 .Xr sigwaitinfo 2 ,
 146 .Xr pause 3 ,
 147 .Xr pthread_sigmask 3
 148 .Sh STANDARDS
 149 The
 150 .Fn sigqueue
 151 system call conforms to
 152 .St -p1003.1-2004 .
 153 .Sh HISTORY
 154 Support for
 155 .Tn POSIX
 156 realtime signal queue first appeared in
 157 .Nx 6.0 .