1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" Copyright 2016, Joyent, Inc. 12.\" 13.Dd "May 05, 2016" 14.Dt SIGNALFD 3C 15.Os 16.Sh NAME 17.Nm signalfd 18.Nd create or modify a file descriptor for signal handling 19.Sh SYNOPSIS 20.In sys/signalfd.h 21. 22.Ft int 23.Fo signalfd 24.Fa "int fd" 25.Fa "const sigset_t *mask" 26.Fa "int flags" 27.Fc 28. 29.Sh DESCRIPTION 30The 31.Fn signalfd 32function returns a file descriptor that can be used 33for synchronous consumption of signals. The file descriptor can be operated 34upon via 35.Xr read 2 36and the facilities that notify of file descriptor activity (e.g. 37.Xr poll 2 , 38.Xr port_get 3C , 39.Xr epoll_wait 3C 40). To dispose of the instance 41.Xr close 2 42should be called on the file descriptor. 43.Pp 44If the 45.Va fd 46argument is -1, a new signalfd file descriptor will be 47returned, otherwise the 48.Va fd 49argument should be an existing signalfd file descriptor whose signal mask will 50be updated. 51.Pp 52The 53.Va mask 54argument specifies the set of signals that are relevant to the file descriptor. 55It may be manipulated with the standard signal set manipulation functions 56documented in 57.Xr sigsetops 3C . 58Signals in the mask which cannot be caught (e.g. 59.Fa SIGKILL ) 60are ignored. 61.Pp 62The 63.Va flags 64argument specifies additional parameters for the instance, and can have any of 65the following values: 66.Bl -tag -width Dv 67.It Sy SFD_CLOEXEC 68Instance will be closed upon an 69.Xr exec 2 ; 70see description for 71.Fa O_CLOEXEC 72in 73.Xr open 2 . 74.It Sy SFD_NONBLOCK 75Instance will be set to be non-blocking. A 76.Xr read 2 77on a signalfd instance that has been initialized with 78.Fa SFD_NONBLOCK , 79or made non-blocking in other ways, will return 80.Er EAGAIN 81in lieu of blocking if there are no signals from the 82.Va mask 83that are pending. 84.El 85.Pp 86As with 87.Xr sigwait 2 , 88reading a signal from the file descriptor will consume the signal. The signals 89used with signalfd file descriptors are normally first blocked so that their 90handler does not run when a signal arrives. If the signal is not blocked the 91behavior matches that of 92.Xr sigwait 2 ; 93if a 94.Xr read 2 95is pending then the signal is consumed by the read, otherwise the signal is 96consumed by the handler. 97.Pp 98The following operations can be performed upon a signalfd file descriptor: 99.Bl -tag -width Dv 100.It Sy read(2) 101Reads and consumes one or more of the pending signals that match the file 102descriptor's 103.Va mask . 104The read buffer must be large enough to hold one or more 105.Vt signalfd_siginfo 106structures, which is described below. 107.Xr read 2 108will block if there are no matching signals pending, or return 109.Er EAGAIN 110if the instance was created with 111.Fa SFD_NONBLOCK . 112After a 113.Xr fork 2 , 114if the child reads from the descriptor it will only consume signals from itself. 115.It Sy poll(2) 116Provide notification when one of the signals from the 117.Va mask 118arrives. 119.Fa POLLIN 120and 121.Fa POLLRDNORM 122will be set. 123.It Sy close(2) 124Closes the desriptor. 125.El 126.Pp 127The 128.Vt signalfd_siginfo 129structure returned from 130.Xr read 2 131is a fixed size 128 byte structure defined as follows: 132.Bd -literal 133typedef struct signalfd_siginfo { 134 uint32_t ssi_signo; /* signal from signal.h */ 135 int32_t ssi_errno; /* error from errno.h */ 136 int32_t ssi_code; /* signal code */ 137 uint32_t ssi_pid; /* PID of sender */ 138 uint32_t ssi_uid; /* real UID of sender */ 139 int32_t ssi_fd; /* file descriptor (SIGIO) */ 140 uint32_t ssi_tid; /* unused */ 141 uint32_t ssi_band; /* band event (SIGIO) */ 142 uint32_t ssi_overrun; /* unused */ 143 uint32_t ssi_trapno; /* trap number that caused signal */ 144 int32_t ssi_status; /* exit status or signal (SIGCHLD) */ 145 int32_t ssi_int; /* unused */ 146 uint64_t ssi_ptr; /* unused */ 147 uint64_t ssi_utime; /* user CPU time consumed (SIGCHLD) */ 148 uint64_t ssi_stime; /* system CPU time consumed (SIGCHLD) */ 149 uint64_t ssi_addr; /* address that generated signal */ 150 uint8_t ssi_pad[48]; /* pad size to 128 bytes */ 151} signalfd_siginfo_t; 152.Ed 153.Sh NOTES 154File descriptor duplication during fork presents a challenge to the 155.Sy signalfd 156facility since signal data and events are dependent on the process from which 157they are queried. Its use with caching event systems such as 158.Xr epoll 5 , 159.Sy /dev/poll , 160or 161.Xr port_create 3C 162can result in undefined behavior if signalfd and polling descriptors are used 163together after being shared across a fork. Such restrictions do not apply if 164the child only calls 165.Xr close 2 166on the descriptors. 167.Sh RETURN VALUES 168Upon successful completion, a file descriptor associated with the instance 169is returned. Otherwise, -1 is returned and errno is set to indicate the error. 170When 171.Va fd 172is not -1 and there is no error, the value of 173.Va fd 174is returned. 175.Sh ERRORS 176The 177.Fn signalfd function 178will fail if: 179.Bl -tag -width Er 180.It Er EBADF 181The 182.Va fd 183descriptor is invalid. 184.It Er EFAULT 185The 186.Va mask 187address is invalid. 188.It Er EINVAL 189The 190.Va fd 191descriptor is not a signalfd descriptor or the 192.Va flags 193are invalid. 194.It Er EMFILE 195There are currently 196.Va OPEN_MAX 197file descriptors open in the calling process. 198.It Er ENODEV 199Unable to allocate state for the file descriptor. 200.El 201.Sh SEE ALSO 202.Xr poll 2 , 203.Xr sigwait 2 , 204.Xr port_create 3C , 205.Xr sigsetops 3C , 206.Xr sigwaitinfo 3C , 207.Xr signal.h 3HEAD , 208.Xr epoll 5 209