| .\" Copyright (c) 2002, 2011 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH RT_SIGQUEUEINFO 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| rt_sigqueueinfo, rt_tgsigqueueinfo \- queue a signal and data |
| .SH SYNOPSIS |
| .nf |
| .BI "int rt_sigqueueinfo(pid_t " tgid ", int " sig ", siginfo_t *" uinfo ); |
| .PP |
| .BI "int rt_tgsigqueueinfo(pid_t " tgid ", pid_t " tid ", int " sig , |
| .BI " siginfo_t *" uinfo ); |
| .fi |
| .PP |
| .IR Note : |
| There are no glibc wrappers for these system calls; see NOTES. |
| .SH DESCRIPTION |
| The |
| .BR rt_sigqueueinfo () |
| and |
| .BR rt_tgsigqueueinfo () |
| system calls are the low-level interfaces used to send a signal plus data |
| to a process or thread. |
| The receiver of the signal can obtain the accompanying data |
| by establishing a signal handler with the |
| .BR sigaction (2) |
| .B SA_SIGINFO |
| flag. |
| .PP |
| These system calls are not intended for direct application use; |
| they are provided to allow the implementation of |
| .BR sigqueue (3) |
| and |
| .BR pthread_sigqueue (3). |
| .PP |
| The |
| .BR rt_sigqueueinfo () |
| system call sends the signal |
| .I sig |
| to the thread group with the ID |
| .IR tgid . |
| (The term "thread group" is synonymous with "process", and |
| .I tid |
| corresponds to the traditional UNIX process ID.) |
| The signal will be delivered to an arbitrary member of the thread group |
| (i.e., one of the threads that is not currently blocking the signal). |
| .PP |
| The |
| .I uinfo |
| argument specifies the data to accompany the signal. |
| This argument is a pointer to a structure of type |
| .IR siginfo_t , |
| described in |
| .BR sigaction (2) |
| (and defined by including |
| .IR <sigaction.h> ). |
| The caller should set the following fields in this structure: |
| .TP |
| .I si_code |
| This must be one of the |
| .B SI_* |
| codes in the Linux kernel source file |
| .IR include/asm-generic/siginfo.h , |
| with the restriction that the code must be negative |
| (i.e., cannot be |
| .BR SI_USER , |
| which is used by the kernel to indicate a signal sent by |
| .BR kill (2)) |
| and cannot (since Linux 2.6.39) be |
| .BR SI_TKILL |
| (which is used by the kernel to indicate a signal sent using |
| .\" tkill(2) or |
| .BR tgkill (2)). |
| .TP |
| .I si_pid |
| This should be set to a process ID, |
| typically the process ID of the sender. |
| .TP |
| .I si_uid |
| This should be set to a user ID, |
| typically the real user ID of the sender. |
| .TP |
| .I si_value |
| This field contains the user data to accompany the signal. |
| For more information, see the description of the last |
| .RI ( "union sigval" ) |
| argument of |
| .BR sigqueue (3). |
| .PP |
| Internally, the kernel sets the |
| .I si_signo |
| field to the value specified in |
| .IR sig , |
| so that the receiver of the signal can also obtain |
| the signal number via that field. |
| .PP |
| The |
| .BR rt_tgsigqueueinfo () |
| system call is like |
| .BR rt_sigqueueinfo (), |
| but sends the signal and data to the single thread |
| specified by the combination of |
| .IR tgid , |
| a thread group ID, |
| and |
| .IR tid , |
| a thread in that thread group. |
| .SH RETURN VALUE |
| On success, these system calls return 0. |
| On error, they return \-1 and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EAGAIN |
| The limit of signals which may be queued has been reached. |
| (See |
| .BR signal (7) |
| for further information.) |
| .TP |
| .B EINVAL |
| .IR sig , |
| .IR tgid , |
| or |
| .IR tid |
| was invalid. |
| .TP |
| .B EPERM |
| The caller does not have permission to send the signal to the target. |
| For the required permissions, see |
| .BR kill (2). |
| Or: |
| .I uinfo->si_code |
| is invalid. |
| .TP |
| .B ESRCH |
| .BR rt_sigqueueinfo (): |
| No thread group matching |
| .I tgid |
| was found. |
| .PP |
| .BR rt_tgsigqueinfo (): |
| No thread matching |
| .I tgid |
| and |
| .I tid |
| was found. |
| .SH VERSIONS |
| The |
| .BR rt_sigqueueinfo () |
| system call was added to Linux in version 2.2. |
| The |
| .BR rt_tgsigqueueinfo () |
| system call was added to Linux in version 2.6.31. |
| .SH CONFORMING TO |
| These system calls are Linux-specific. |
| .SH NOTES |
| Since these system calls are not intended for application use, |
| there are no glibc wrapper functions; use |
| .BR syscall (2) |
| in the unlikely case that you want to call them directly. |
| .PP |
| As with |
| .BR kill (2), |
| the null signal (0) can be used to check if the specified process |
| or thread exists. |
| .SH SEE ALSO |
| .BR kill (2), |
| .BR sigaction (2), |
| .BR sigprocmask (2), |
| .BR tgkill (2), |
| .BR pthread_sigqueue (3), |
| .BR sigqueue (3), |
| .BR signal (7) |