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