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