From e84ece6bef13b7dc2b7b2feb217122aed5e9f859 Mon Sep 17 00:00:00 2001 From: David Xu Date: Fri, 11 Nov 2005 03:13:25 +0000 Subject: [PATCH] Add manuals for sigqueue, sigtimedwait, sigwaitinfo. --- lib/libc/sys/Makefile.inc | 5 +- lib/libc/sys/sigqueue.2 | 126 ++++++++++++++++++++++++++++ lib/libc/sys/sigwaitinfo.2 | 167 +++++++++++++++++++++++++++++++++++++ 3 files changed, 296 insertions(+), 2 deletions(-) create mode 100644 lib/libc/sys/sigqueue.2 create mode 100644 lib/libc/sys/sigwaitinfo.2 diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index 53ac26b8d898..93aa9aaed79d 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -77,8 +77,8 @@ MAN+= _exit.2 accept.2 access.2 acct.2 adjtime.2 \ rtprio.2 select.2 semctl.2 semget.2 semop.2 send.2 sendfile.2 \ setgroups.2 setpgid.2 setregid.2 setresuid.2 setreuid.2 setsid.2 \ setuid.2 shmat.2 shmctl.2 shmget.2 shutdown.2 \ - sigaction.2 sigaltstack.2 sigpending.2 sigprocmask.2 sigreturn.2 \ - sigstack.2 sigsuspend.2 sigwait.2 \ + sigaction.2 sigaltstack.2 sigpending.2 sigprocmask.2 sigqueue.2 \ + sigreturn.2 sigstack.2 sigsuspend.2 sigwait.2 sigwaitinfo.2 \ socket.2 socketpair.2 stat.2 statfs.2 \ swapon.2 symlink.2 sync.2 sysarch.2 syscall.2 \ truncate.2 umask.2 undelete.2 \ @@ -134,6 +134,7 @@ MLINKS+=setpgid.2 setpgrp.2 MLINKS+=setresuid.2 setresgid.2 setresuid.2 getresuid.2 setresuid.2 getresgid.2 MLINKS+=setuid.2 setegid.2 setuid.2 seteuid.2 setuid.2 setgid.2 MLINKS+=shmat.2 shmdt.2 +MLINKS+=sigwaitinfo.2 sigtimedwait.2 MLINKS+=stat.2 fstat.2 stat.2 lstat.2 MLINKS+=statfs.2 fstatfs.2 MLINKS+=syscall.2 __syscall.2 diff --git a/lib/libc/sys/sigqueue.2 b/lib/libc/sys/sigqueue.2 new file mode 100644 index 000000000000..f9475a686eaa --- /dev/null +++ b/lib/libc/sys/sigqueue.2 @@ -0,0 +1,126 @@ +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd Nov 11, 2005 +.Dt SIGQUEUE 2 +.Os +.Sh NAME +.Nm sigqueue +.Nd queue a signal to a process (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigqueue "pid_t pid" "int signo" "const union sigval value" +.Sh DESCRIPTION +The +.Fn sigqueue +function causes the signal specified by +.Fa signo +to be sent with the value specified by +.Fa value +to the process specified by +.Fa pid . +If +.Fa signo +is zero (the null signal), error checking is performed but +no signal is actually sent. The null signal can be used to check the +validity of pid. +.Pp +The conditions required for a process to have permission to queue a +signal to another process are the same as for the +.Fn kill +function. +The +.Fn sigqueue +function queues a signal to a single process specified by the pid argument. +.Pp +The sigqueue() function returns immediately. If the resources were +available to queue the signal, the signal will be queued and sent to +the receiving process. +.Pp +If the value of +.Fa pid +causes +.Fa signo +to be generated for the sending process, and if +.Fa signo +is not blocked for the calling thread and if no other thread has +.Fa signo +unblocked or is waiting in a +.Fn sigwait +function for +.Fa signo, either +.Fa signo +or at least the pending, unblocked signal will be delivered to the +calling thread before the +.Fn sigqueue +function returns. Should any multiple pending signals in the range +SIGRTMIN to SIGRTMAX be selected for delivery, it is the lowest numbered +one. The selection order between realtime and non-realtime signals, or +between multiple pending non-realtime signals, is unspecified. +.Sh RETURN VALUES +Upon successful completion, the specified signal has been queued, and +the +.Fn sigqueue +function returns a value of zero. Otherwise, the function returns a value +of -1 and set errno to indicate the error. +.Sh ERRORS +The +.Fn sigqueue +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +No resources are available to queue the signal. The process has already +queued {SIGQUEUE_MAX} signals that are still pending at the receiver(s), +or a system-wide resource limit has been exceeded. +.It Bq Er EINVAL +The value of the +.Fa signo +argument is an invalid or unsupported signal number. +.It Bq Er EEPERM +The process does not have the appropriate privilege to send the signal +to the receiving process. +.It Bq Er ESRCH +The process pid does not exist. +.El +.Sh SEE ALSO +.Xr sigwait 2 , +.Xr sigtimedwait 2 , +.Xr sigwaitinfo 2 , +.Xr sigqueue 2 , +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigsuspend 2 , +.Xr pause 3 , +.Xr pthread_sigmask 3 +.Sh STANDARDS +The +.Fn sigqueue +function conforms to +.St -p1003.1-96 . diff --git a/lib/libc/sys/sigwaitinfo.2 b/lib/libc/sys/sigwaitinfo.2 new file mode 100644 index 000000000000..0a560a7891a3 --- /dev/null +++ b/lib/libc/sys/sigwaitinfo.2 @@ -0,0 +1,167 @@ +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd Nov 11, 2005 +.Dt SIGTIMEDWAIT 2 +.Os +.Sh NAME +.Nm sigtimedwait, +.Nm sigwaitinfo +.Nd wait for queued signals (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Ft int +.Fn sigtimedwait "const sigset_t *restrict set" "siginfo_t *restrict info" "const struct timespec *restrict timeout" +.Ft int +.Fn sigwaitinfo "const sigset_t * restrict set" "siginfo_t * restrict info" +.Sh DESCRIPTION +The +.Fn sigtimedwait +function is equivalent to +.Fn sigwaitinfo +except that if none of the signals specified by +.Fa set +are pending, +.Fn +sigtimedwait +waits for the time interval specified in the +.Sy +timespec +structure referenced by +.Fa timeout . +If the +.Sy +timespec +structure pointed to by +.Fa timeout +is zero-valued and if none of the signals specified by +.Fa set +are pending, then +.Fn sigtimedwait +returns immediately with an error. If +.Fa timeout +is the NULL pointer, the behavior is unspecified. CLOCK_MONOTONIC +clock is used to measure the time interval specified by the +.Fa timeout +argument. +.Pp +The +.Fn sigwaitinfo +function selects the pending signal from the set specified by +.Fa set . +Should any of multiple pending signals in the range SIGRTMIN to +SIGRTMAX be selected, it shall be the lowest numbered one. The +selection order between realtime and non-realtime signals, or +between multiple pending non-realtime signals, is unspecified. +If no signal in +.Fa set +is pending at the time of the call, the calling thread +is suspended until one or more signals in +.Fa set +become pending or until it is interrupted by an unblocked, caught signal. +.Pp +The +.Fn sigwaitinfo +function is equivalent to the +.Fn sigwait +function if the +.Fa info +argument is NULL. If the +.Fa info +argument is non-NULL, the +.Fn sigwaitinfo +function is equivalent to +.Fn sigwait , +except that the selected signal number shall be stored in the +si_signo member, and the cause of the signal shall be stored in the si_code +member. If any value is queued to the selected signal, the first such queued +value is dequeued and, if the info argument is non-NULL, the value is stored +in the si_value member of info. The system resource used to queue the signal +is released and returned to the system for other use. If no value is queued, +the content of the si_value member is zero-valued. If no further signals are +queued for the selected signal, the pending indication for that signal +is reset. +.Sh RETURN VALUES +Upon successful completion (that is, one of the signals specified by +.Fa set +is pending or is generated) +.Fn sigwaitinfo +and +.Fn sigtimedwait +return the selected signal number. Otherwise, the function return a value of -1 +and set errno to indicate the error. +.Sh ERRORS +The +.Fn sigtimedwait +will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +No signal specified by set was generated within the specified timeout period. +.El +.Pp +The +.Fn sigtimedwait +and +.Fn sigwaitinfo +functions fail if: +.Bl -tag -width Er +.It Bq Er EINTR +The wait was interrupted by an unblocked, caught signal. +.It Bq Er EFAULT +Any arguments point outside the allocated address space or there is a +memory protection fault. +.Pp +.El +The +.Fn sigtimedwait +function may also fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa timeout +argument specified a tv_nsec value less than zero or greater than or equal +to 1000 million. +Kernel only checks for this error if no signal is pending in set and it +is necessary to wait. +.El +.Sh SEE ALSO +.Xr sigwait 2 , +.Xr sigqueue 2 , +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigsuspend 2 , +.Xr pause 3 , +.Xr pthread_sigmask 3 +.Sh STANDARDS +The +.Fn sigtimedwait +and +.Fn sigwaitinfo +function conforms to +.St -p1003.1-96 .