usr/src/man/man3c/signalfd.3c

   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
  30 The
  31 .Fn signalfd
  32 function returns a file descriptor that can be used
  33 for synchronous consumption of signals.
  34 The file descriptor can be operated upon via
  35 .Xr read 2
  36 and 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 ).
  41 To dispose of the instance
  42 .Xr close 2
  43 should be called on the file descriptor.
  44 .Pp
  45 If the
  46 .Va fd
  47 argument is -1, a new signalfd file descriptor will be
  48 returned, otherwise the
  49 .Va fd
  50 argument should be an existing signalfd file descriptor whose signal mask will
  51 be updated.
  52 .Pp
  53 The
  54 .Va mask
  55 argument specifies the set of signals that are relevant to the file descriptor.
  56 It may be manipulated with the standard signal set manipulation functions
  57 documented in
  58 .Xr sigsetops 3C .
  59 Signals in the mask which cannot be caught (e.g.
  60 .Fa SIGKILL )
  61 are ignored.
  62 .Pp
  63 The
  64 .Va flags
  65 argument specifies additional parameters for the instance, and can have any of
  66 the following values:
  67 .Bl -tag -width Dv
  68 .It Sy SFD_CLOEXEC
  69 Instance will be closed upon an
  70 .Xr exec 2 ;
  71 see description for
  72 .Fa O_CLOEXEC
  73 in
  74 .Xr open 2 .
  75 .It Sy SFD_NONBLOCK
  76 Instance will be set to be non-blocking.
  77 A
  78 .Xr read 2
  79 on a signalfd instance that has been initialized with
  80 .Fa SFD_NONBLOCK ,
  81 or made non-blocking in other ways, will return
  82 .Er EAGAIN
  83 in lieu of blocking if there are no signals from the
  84 .Va mask
  85 that are pending.
  86 .El
  87 .Pp
  88 As with
  89 .Xr sigwait 2 ,
  90 reading a signal from the file descriptor will consume the signal.
  91 The signals used with signalfd file descriptors are normally first blocked so
  92 that their handler does not run when a signal arrives.
  93 If the signal is not blocked the behavior matches that of
  94 .Xr sigwait 2 ;
  95 if a
  96 .Xr read 2
  97 is pending then the signal is consumed by the read, otherwise the signal is
  98 consumed by the handler.
  99 .Pp
 100 The following operations can be performed upon a signalfd file descriptor:
 101 .Bl -tag -width Dv
 102 .It Sy read(2)
 103 Reads and consumes one or more of the pending signals that match the file
 104 descriptor's
 105 .Va mask .
 106 The read buffer must be large enough to hold one or more
 107 .Vt signalfd_siginfo
 108 structures, which is described below.
 109 .Xr read 2
 110 will block if there are no matching signals pending, or return
 111 .Er EAGAIN
 112 if the instance was created with
 113 .Fa SFD_NONBLOCK .
 114 After a
 115 .Xr fork 2 ,
 116 if the child reads from the descriptor it will only consume signals from itself.
 117 .It Sy poll(2)
 118 Provide notification when one of the signals from the
 119 .Va mask
 120 arrives.
 121 .Fa POLLIN
 122 and
 123 .Fa POLLRDNORM
 124 will be set.
 125 .It Sy close(2)
 126 Closes the desriptor.
 127 .El
 128 .Pp
 129 The
 130 .Vt signalfd_siginfo
 131 structure returned from
 132 .Xr read 2
 133 is a fixed size 128 byte structure defined as follows:
 134 .Bd -literal
 135 typedef 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
 156 File descriptor duplication during fork presents a challenge to the
 157 .Sy signalfd
 158 facility since signal data and events are dependent on the process from which
 159 they are queried.
 160 Its use with caching event systems such as
 161 .Xr epoll 5 ,
 162 .Pa /dev/poll ,
 163 or
 164 .Xr port_create 3C
 165 can result in undefined behavior if signalfd and polling descriptors are used
 166 together after being shared across a fork.
 167 Such restrictions do not apply if the child only calls
 168 .Xr close 2
 169 on the descriptors.
 170 .Sh RETURN VALUES
 171 Upon successful completion, a file descriptor associated with the instance
 172 is returned.
 173 Otherwise, -1 is returned and errno is set to indicate the error.
 174 When
 175 .Va fd
 176 is not -1 and there is no error, the value of
 177 .Va fd
 178 is returned.
 179 .Sh ERRORS
 180 The
 181 .Fn signalfd function
 182 will fail if:
 183 .Bl -tag -width Er
 184 .It Er EBADF
 185 The
 186 .Va fd
 187 descriptor is invalid.
 188 .It Er EFAULT
 189 The
 190 .Va mask
 191 address is invalid.
 192 .It Er EINVAL
 193 The
 194 .Va fd
 195 descriptor is not a signalfd descriptor or the
 196 .Va flags
 197 are invalid.
 198 .It Er EMFILE
 199 There are currently
 200 .Va  OPEN_MAX
 201 file descriptors open in the calling process.
 202 .It Er ENODEV
 203 Unable 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 5