diff options
Diffstat (limited to 'man2/signalfd.2')
| -rw-r--r-- | man2/signalfd.2 | 130 |
1 files changed, 65 insertions, 65 deletions
diff --git a/man2/signalfd.2 b/man2/signalfd.2 index 831fa944c..f41e1a7d5 100644 --- a/man2/signalfd.2 +++ b/man2/signalfd.2 @@ -20,12 +20,12 @@ Standard C library creates a file descriptor that can be used to accept signals targeted at the caller. This provides an alternative to the use of a signal handler or -.BR sigwaitinfo (2), +.MR sigwaitinfo 2 , and has the advantage that the file descriptor may be monitored by -.BR select (2), -.BR poll (2), +.MR select 2 , +.MR poll 2 , and -.BR epoll (7). +.MR epoll 7 . .P The .I mask @@ -33,10 +33,10 @@ argument specifies the set of signals that the caller wishes to accept via the file descriptor. This argument is a signal set whose contents can be initialized using the macros described in -.BR sigsetops (3). +.MR sigsetops 3 . Normally, the set of signals to be received via the file descriptor should be blocked using -.BR sigprocmask (2), +.MR sigprocmask 2 , to prevent the signals being handled according to their default dispositions. It is not possible to receive @@ -70,10 +70,10 @@ to change the behavior of Set the .B O_NONBLOCK file status flag on the open file description (see -.BR open (2)) +.MR open 2 ) referred to by the new file descriptor. Using this flag saves extra calls to -.BR fcntl (2) +.MR fcntl 2 to achieve the same result. .TP .B SFD_CLOEXEC @@ -83,7 +83,7 @@ flag on the new file descriptor. See the description of the .B O_CLOEXEC flag in -.BR open (2) +.MR open 2 for reasons why this may be useful. .P Up to Linux 2.6.26, the @@ -93,37 +93,37 @@ argument is unused, and must be specified as zero. .BR signalfd () returns a file descriptor that supports the following operations: .TP -.BR read (2) +.MR read 2 If one or more of the signals specified in .I mask is pending for the process, then the buffer supplied to -.BR read (2) +.MR read 2 is used to return one or more .I signalfd_siginfo structures (see below) that describe the signals. The -.BR read (2) +.MR read 2 returns information for as many signals as are pending and will fit in the supplied buffer. The buffer must be at least .I "sizeof(struct signalfd_siginfo)" bytes. The return value of the -.BR read (2) +.MR read 2 is the total number of bytes read. .IP As a consequence of the -.BR read (2), +.MR read 2 , the signals are consumed, so that they are no longer pending for the process (i.e., will not be caught by signal handlers, and cannot be accepted using -.BR sigwaitinfo (2)). +.MR sigwaitinfo 2 ). .IP If none of the signals in .I mask is pending for the process, then the -.BR read (2) +.MR read 2 either blocks until one of the signals in .I mask is generated for the process, @@ -131,17 +131,17 @@ or fails with the error .B EAGAIN if the file descriptor has been made nonblocking. .TP -.BR poll (2) +.MR poll 2 .TQ -.BR select (2) +.MR select 2 .TQ (and similar) The file descriptor is readable (the -.BR select (2) +.MR select 2 .I readfds argument; the -.BR poll (2) +.MR poll 2 .B POLLIN flag) if one or more of the signals in @@ -150,12 +150,12 @@ is pending for the process. .IP The signalfd file descriptor also supports the other file-descriptor multiplexing APIs: -.BR pselect (2), -.BR ppoll (2), +.MR pselect 2 , +.MR ppoll 2 , and -.BR epoll (7). +.MR epoll 7 . .TP -.BR close (2) +.MR close 2 When the file descriptor is no longer required it should be closed. When all file descriptors associated with the same signalfd object have been closed, the resources for object are freed by the kernel. @@ -163,7 +163,7 @@ have been closed, the resources for object are freed by the kernel. The format of the .I signalfd_siginfo structure(s) returned by -.BR read (2)s +.MR read 2 s from a signalfd file descriptor is as follows: .P .in +4n @@ -204,7 +204,7 @@ structure. The .I siginfo_t structure is described in -.BR sigaction (2). +.MR sigaction 2 . Not all fields in the returned .I signalfd_siginfo structure will be valid for a specific signal; @@ -215,37 +215,37 @@ This field is the analog of the .I siginfo_t .I si_code field; see -.BR sigaction (2) +.MR sigaction 2 for details. .SS fork(2) semantics After a -.BR fork (2), +.MR fork 2 , the child inherits a copy of the signalfd file descriptor. A -.BR read (2) +.MR read 2 from the file descriptor in the child will return information about signals queued to the child. .SS Semantics of file descriptor passing As with other file descriptors, signalfd file descriptors can be passed to another process via a UNIX domain socket (see -.BR unix (7)). +.MR unix 7 ). In the receiving process, a -.BR read (2) +.MR read 2 from the received file descriptor will return information about signals queued to that process. .SS execve(2) semantics Just like any other file descriptor, a signalfd file descriptor remains open across an -.BR execve (2), +.MR execve 2 , unless it has been marked for close-on-exec (see -.BR fcntl (2)). +.MR fcntl 2 ). Any signals that were available for reading before the -.BR execve (2) +.MR execve 2 remain available to the newly loaded program. (This is analogous to traditional signal semantics, where a blocked signal that is pending remains pending across an -.BR execve (2).) +.MR execve 2 .) .SS Thread semantics The semantics of signalfd file descriptors in a multithreaded program mirror the standard semantics for signals. @@ -259,30 +259,30 @@ to other threads in the process.) .\" .SS epoll(7) semantics If a process adds (via -.BR epoll_ctl (2)) +.MR epoll_ctl 2 ) a signalfd file descriptor to an -.BR epoll (7) +.MR epoll 7 instance, then -.BR epoll_wait (2) +.MR epoll_wait 2 returns events only for signals sent to that process. In particular, if the process then uses -.BR fork (2) +.MR fork 2 to create a child process, then the child will be able to -.BR read (2) +.MR read 2 signals that are sent to it using the signalfd file descriptor, but -.BR epoll_wait (2) +.MR epoll_wait 2 will .B not indicate that the signalfd file descriptor is ready. In this scenario, a possible workaround is that after the -.BR fork (2), +.MR fork 2 , the child process can close the signalfd file descriptor that it inherited from the parent process and then create another signalfd file descriptor and add it to the epoll instance. Alternatively, the parent and the child could delay creating their (separate) signalfd file descriptors and adding them to the epoll instance until after the call to -.BR fork (2). +.MR fork 2 . .SH RETURN VALUE On success, .BR signalfd () @@ -374,10 +374,10 @@ A process can create multiple signalfd file descriptors. This makes it possible to accept different signals on different file descriptors. (This may be useful if monitoring the file descriptors using -.BR select (2), -.BR poll (2), +.MR select 2 , +.MR poll 2 , or -.BR epoll (7): +.MR epoll 7 : the arrival of different signals will make different file descriptors ready.) If a signal appears in the .I mask @@ -397,7 +397,7 @@ via the entry for the corresponding file descriptor in the process's .IR /proc/ pid /fdinfo directory. See -.BR proc (5) +.MR proc 5 for further details. .\" .SS Limitations @@ -416,26 +416,26 @@ in normal usage one blocks the signals that will be accepted via If spawning a child process to execute a helper program (that does not need the signalfd file descriptor), then, after the call to -.BR fork (2), +.MR fork 2 , you will normally want to unblock those signals before calling -.BR execve (2), +.MR execve 2 , so that the helper program can see any signals that it expects to see. Be aware, however, that this won't be possible in the case of a helper program spawned behind the scenes by any library function that the program may call. In such cases, one must fall back to using a traditional signal handler that writes to a file descriptor monitored by -.BR select (2), -.BR poll (2), +.MR select 2 , +.MR poll 2 , or -.BR epoll (7). +.MR epoll 7 . .SH BUGS Before Linux 2.6.25, the .I ssi_ptr and .I ssi_int fields are not filled in with the data accompanying a signal sent by -.BR sigqueue (3). +.MR sigqueue 3 . .\" The fix also was put into Linux 2.6.24.5 .SH EXAMPLES The program below accepts the signals @@ -511,15 +511,15 @@ main(void) .EE .\" SRC END .SH SEE ALSO -.BR eventfd (2), -.BR poll (2), -.BR read (2), -.BR select (2), -.BR sigaction (2), -.BR sigprocmask (2), -.BR sigwaitinfo (2), -.BR timerfd_create (2), -.BR sigsetops (3), -.BR sigwait (3), -.BR epoll (7), -.BR signal (7) +.MR eventfd 2 , +.MR poll 2 , +.MR read 2 , +.MR select 2 , +.MR sigaction 2 , +.MR sigprocmask 2 , +.MR sigwaitinfo 2 , +.MR timerfd_create 2 , +.MR sigsetops 3 , +.MR sigwait 3 , +.MR epoll 7 , +.MR signal 7 |