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