13d729aecSJerry Jelinek.\" 23d729aecSJerry Jelinek.\" This file and its contents are supplied under the terms of the 33d729aecSJerry Jelinek.\" Common Development and Distribution License ("CDDL"), version 1.0. 43d729aecSJerry Jelinek.\" You may only use this file in accordance with the terms of version 53d729aecSJerry Jelinek.\" 1.0 of the CDDL. 63d729aecSJerry Jelinek.\" 73d729aecSJerry Jelinek.\" A full copy of the text of the CDDL should have accompanied this 83d729aecSJerry Jelinek.\" source. A copy of the CDDL is also available via the Internet at 93d729aecSJerry Jelinek.\" http://www.illumos.org/license/CDDL. 103d729aecSJerry Jelinek.\" 11abf99a00SPatrick Mooney.\" Copyright 2016, Joyent, Inc. 123d729aecSJerry Jelinek.\" 13*4a8d6d7cSPeter Tribble.Dd "February 17, 2023" 143d729aecSJerry Jelinek.Dt SIGNALFD 3C 153d729aecSJerry Jelinek.Os 163d729aecSJerry Jelinek.Sh NAME 173d729aecSJerry Jelinek.Nm signalfd 183d729aecSJerry Jelinek.Nd create or modify a file descriptor for signal handling 193d729aecSJerry Jelinek.Sh SYNOPSIS 203d729aecSJerry Jelinek.In sys/signalfd.h 213d729aecSJerry Jelinek. 223d729aecSJerry Jelinek.Ft int 233d729aecSJerry Jelinek.Fo signalfd 243d729aecSJerry Jelinek.Fa "int fd" 253d729aecSJerry Jelinek.Fa "const sigset_t *mask" 263d729aecSJerry Jelinek.Fa "int flags" 273d729aecSJerry Jelinek.Fc 283d729aecSJerry Jelinek. 293d729aecSJerry Jelinek.Sh DESCRIPTION 303d729aecSJerry JelinekThe 313d729aecSJerry Jelinek.Fn signalfd 323d729aecSJerry Jelinekfunction returns a file descriptor that can be used 3372d3dbb9SYuri Pankovfor synchronous consumption of signals. 3472d3dbb9SYuri PankovThe file descriptor can be operated upon via 353d729aecSJerry Jelinek.Xr read 2 363d729aecSJerry Jelinekand the facilities that notify of file descriptor activity (e.g. 373d729aecSJerry Jelinek.Xr poll 2 , 383d729aecSJerry Jelinek.Xr port_get 3C , 393d729aecSJerry Jelinek.Xr epoll_wait 3C 4072d3dbb9SYuri Pankov). 4172d3dbb9SYuri PankovTo dispose of the instance 423d729aecSJerry Jelinek.Xr close 2 433d729aecSJerry Jelinekshould be called on the file descriptor. 443d729aecSJerry Jelinek.Pp 453d729aecSJerry JelinekIf the 463d729aecSJerry Jelinek.Va fd 473d729aecSJerry Jelinekargument is -1, a new signalfd file descriptor will be 483d729aecSJerry Jelinekreturned, otherwise the 493d729aecSJerry Jelinek.Va fd 503d729aecSJerry Jelinekargument should be an existing signalfd file descriptor whose signal mask will 513d729aecSJerry Jelinekbe updated. 523d729aecSJerry Jelinek.Pp 533d729aecSJerry JelinekThe 543d729aecSJerry Jelinek.Va mask 553d729aecSJerry Jelinekargument specifies the set of signals that are relevant to the file descriptor. 563d729aecSJerry JelinekIt may be manipulated with the standard signal set manipulation functions 573d729aecSJerry Jelinekdocumented in 583d729aecSJerry Jelinek.Xr sigsetops 3C . 593d729aecSJerry JelinekSignals in the mask which cannot be caught (e.g. 603d729aecSJerry Jelinek.Fa SIGKILL ) 613d729aecSJerry Jelinekare ignored. 623d729aecSJerry Jelinek.Pp 633d729aecSJerry JelinekThe 643d729aecSJerry Jelinek.Va flags 653d729aecSJerry Jelinekargument specifies additional parameters for the instance, and can have any of 663d729aecSJerry Jelinekthe following values: 673d729aecSJerry Jelinek.Bl -tag -width Dv 683d729aecSJerry Jelinek.It Sy SFD_CLOEXEC 693d729aecSJerry JelinekInstance will be closed upon an 703d729aecSJerry Jelinek.Xr exec 2 ; 713d729aecSJerry Jelineksee description for 723d729aecSJerry Jelinek.Fa O_CLOEXEC 733d729aecSJerry Jelinekin 743d729aecSJerry Jelinek.Xr open 2 . 753d729aecSJerry Jelinek.It Sy SFD_NONBLOCK 7672d3dbb9SYuri PankovInstance will be set to be non-blocking. 7772d3dbb9SYuri PankovA 783d729aecSJerry Jelinek.Xr read 2 793d729aecSJerry Jelinekon a signalfd instance that has been initialized with 803d729aecSJerry Jelinek.Fa SFD_NONBLOCK , 813d729aecSJerry Jelinekor made non-blocking in other ways, will return 823d729aecSJerry Jelinek.Er EAGAIN 833d729aecSJerry Jelinekin lieu of blocking if there are no signals from the 843d729aecSJerry Jelinek.Va mask 853d729aecSJerry Jelinekthat are pending. 863d729aecSJerry Jelinek.El 873d729aecSJerry Jelinek.Pp 883d729aecSJerry JelinekAs with 893d729aecSJerry Jelinek.Xr sigwait 2 , 9072d3dbb9SYuri Pankovreading a signal from the file descriptor will consume the signal. 9172d3dbb9SYuri PankovThe signals used with signalfd file descriptors are normally first blocked so 9272d3dbb9SYuri Pankovthat their handler does not run when a signal arrives. 9372d3dbb9SYuri PankovIf the signal is not blocked the behavior matches that of 943d729aecSJerry Jelinek.Xr sigwait 2 ; 953d729aecSJerry Jelinekif a 963d729aecSJerry Jelinek.Xr read 2 973d729aecSJerry Jelinekis pending then the signal is consumed by the read, otherwise the signal is 983d729aecSJerry Jelinekconsumed by the handler. 993d729aecSJerry Jelinek.Pp 1003d729aecSJerry JelinekThe following operations can be performed upon a signalfd file descriptor: 1013d729aecSJerry Jelinek.Bl -tag -width Dv 1023d729aecSJerry Jelinek.It Sy read(2) 1033d729aecSJerry JelinekReads and consumes one or more of the pending signals that match the file 1043d729aecSJerry Jelinekdescriptor's 1053d729aecSJerry Jelinek.Va mask . 1063d729aecSJerry JelinekThe read buffer must be large enough to hold one or more 1073d729aecSJerry Jelinek.Vt signalfd_siginfo 1083d729aecSJerry Jelinekstructures, which is described below. 1093d729aecSJerry Jelinek.Xr read 2 1103d729aecSJerry Jelinekwill block if there are no matching signals pending, or return 1113d729aecSJerry Jelinek.Er EAGAIN 1123d729aecSJerry Jelinekif the instance was created with 1133d729aecSJerry Jelinek.Fa SFD_NONBLOCK . 1143d729aecSJerry JelinekAfter a 1153d729aecSJerry Jelinek.Xr fork 2 , 1163d729aecSJerry Jelinekif the child reads from the descriptor it will only consume signals from itself. 1173d729aecSJerry Jelinek.It Sy poll(2) 1183d729aecSJerry JelinekProvide notification when one of the signals from the 1193d729aecSJerry Jelinek.Va mask 1203d729aecSJerry Jelinekarrives. 1213d729aecSJerry Jelinek.Fa POLLIN 1223d729aecSJerry Jelinekand 1233d729aecSJerry Jelinek.Fa POLLRDNORM 1243d729aecSJerry Jelinekwill be set. 1253d729aecSJerry Jelinek.It Sy close(2) 126*4a8d6d7cSPeter TribbleCloses the descriptor. 1273d729aecSJerry Jelinek.El 1283d729aecSJerry Jelinek.Pp 1293d729aecSJerry JelinekThe 1303d729aecSJerry Jelinek.Vt signalfd_siginfo 1313d729aecSJerry Jelinekstructure returned from 1323d729aecSJerry Jelinek.Xr read 2 1333d729aecSJerry Jelinekis a fixed size 128 byte structure defined as follows: 1343d729aecSJerry Jelinek.Bd -literal 1353d729aecSJerry Jelinektypedef struct signalfd_siginfo { 1363d729aecSJerry Jelinek uint32_t ssi_signo; /* signal from signal.h */ 1373d729aecSJerry Jelinek int32_t ssi_errno; /* error from errno.h */ 1383d729aecSJerry Jelinek int32_t ssi_code; /* signal code */ 1393d729aecSJerry Jelinek uint32_t ssi_pid; /* PID of sender */ 1403d729aecSJerry Jelinek uint32_t ssi_uid; /* real UID of sender */ 1413d729aecSJerry Jelinek int32_t ssi_fd; /* file descriptor (SIGIO) */ 1423d729aecSJerry Jelinek uint32_t ssi_tid; /* unused */ 1433d729aecSJerry Jelinek uint32_t ssi_band; /* band event (SIGIO) */ 1443d729aecSJerry Jelinek uint32_t ssi_overrun; /* unused */ 1453d729aecSJerry Jelinek uint32_t ssi_trapno; /* trap number that caused signal */ 1463d729aecSJerry Jelinek int32_t ssi_status; /* exit status or signal (SIGCHLD) */ 1473d729aecSJerry Jelinek int32_t ssi_int; /* unused */ 1483d729aecSJerry Jelinek uint64_t ssi_ptr; /* unused */ 1493d729aecSJerry Jelinek uint64_t ssi_utime; /* user CPU time consumed (SIGCHLD) */ 1503d729aecSJerry Jelinek uint64_t ssi_stime; /* system CPU time consumed (SIGCHLD) */ 1513d729aecSJerry Jelinek uint64_t ssi_addr; /* address that generated signal */ 1523d729aecSJerry Jelinek uint8_t ssi_pad[48]; /* pad size to 128 bytes */ 1533d729aecSJerry Jelinek} signalfd_siginfo_t; 1543d729aecSJerry Jelinek.Ed 155abf99a00SPatrick Mooney.Sh NOTES 156abf99a00SPatrick MooneyFile descriptor duplication during fork presents a challenge to the 157abf99a00SPatrick Mooney.Sy signalfd 158abf99a00SPatrick Mooneyfacility since signal data and events are dependent on the process from which 15972d3dbb9SYuri Pankovthey are queried. 16072d3dbb9SYuri PankovIts use with caching event systems such as 161bbf21555SRichard Lowe.Xr epoll 7 , 16272d3dbb9SYuri Pankov.Pa /dev/poll , 163abf99a00SPatrick Mooneyor 164abf99a00SPatrick Mooney.Xr port_create 3C 165abf99a00SPatrick Mooneycan result in undefined behavior if signalfd and polling descriptors are used 16672d3dbb9SYuri Pankovtogether after being shared across a fork. 16772d3dbb9SYuri PankovSuch restrictions do not apply if the child only calls 168abf99a00SPatrick Mooney.Xr close 2 169abf99a00SPatrick Mooneyon the descriptors. 1703d729aecSJerry Jelinek.Sh RETURN VALUES 171843c398eSCody Peter MelloUpon successful completion, a file descriptor associated with the instance 17272d3dbb9SYuri Pankovis returned. 17372d3dbb9SYuri PankovOtherwise, -1 is returned and errno is set to indicate the error. 1743d729aecSJerry JelinekWhen 1753d729aecSJerry Jelinek.Va fd 1763d729aecSJerry Jelinekis not -1 and there is no error, the value of 1773d729aecSJerry Jelinek.Va fd 1783d729aecSJerry Jelinekis returned. 1793d729aecSJerry Jelinek.Sh ERRORS 1803d729aecSJerry JelinekThe 1813d729aecSJerry Jelinek.Fn signalfd function 1823d729aecSJerry Jelinekwill fail if: 1833d729aecSJerry Jelinek.Bl -tag -width Er 1843d729aecSJerry Jelinek.It Er EBADF 1853d729aecSJerry JelinekThe 1863d729aecSJerry Jelinek.Va fd 1873d729aecSJerry Jelinekdescriptor is invalid. 1883d729aecSJerry Jelinek.It Er EFAULT 1893d729aecSJerry JelinekThe 1903d729aecSJerry Jelinek.Va mask 1913d729aecSJerry Jelinekaddress is invalid. 1923d729aecSJerry Jelinek.It Er EINVAL 1933d729aecSJerry JelinekThe 1943d729aecSJerry Jelinek.Va fd 1953d729aecSJerry Jelinekdescriptor is not a signalfd descriptor or the 1963d729aecSJerry Jelinek.Va flags 1973d729aecSJerry Jelinekare invalid. 1983d729aecSJerry Jelinek.It Er EMFILE 1993d729aecSJerry JelinekThere are currently 2003d729aecSJerry Jelinek.Va OPEN_MAX 2013d729aecSJerry Jelinekfile descriptors open in the calling process. 2023d729aecSJerry Jelinek.It Er ENODEV 2033d729aecSJerry JelinekUnable to allocate state for the file descriptor. 2043d729aecSJerry Jelinek.El 2053d729aecSJerry Jelinek.Sh SEE ALSO 2063d729aecSJerry Jelinek.Xr poll 2 , 2073d729aecSJerry Jelinek.Xr sigwait 2 , 208abf99a00SPatrick Mooney.Xr port_create 3C , 2093d729aecSJerry Jelinek.Xr sigsetops 3C , 2103d729aecSJerry Jelinek.Xr sigwaitinfo 3C , 211abf99a00SPatrick Mooney.Xr signal.h 3HEAD , 212bbf21555SRichard Lowe.Xr epoll 7 213