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
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.
11 .\" Copyright 2015, Joyent, Inc.
18 .Nd create or modify a file descriptor for signal handling
25 .Fa "const sigset_t *mask"
32 function returns a file descriptor that can be used
33 for synchronous consumption of signals. The file descriptor can be operated
36 and the facilities that notify of file descriptor activity (e.g.
40 ). To dispose of the instance
42 should be called on the file descriptor.
46 argument is -1, a new signalfd file descriptor will be
47 returned, otherwise the
49 argument should be an existing signalfd file descriptor whose signal mask will
54 argument specifies the set of signals that are relevant to the file descriptor.
55 It may be manipulated with the standard signal set manipulation functions
58 Signals in the mask which cannot be caught (e.g.
64 argument specifies additional parameters for the instance, and can have any of
68 Instance will be closed upon an
75 Instance will be set to be non-blocking. A
77 on a signalfd instance that has been initialized with
79 or made non-blocking in other ways, will return
81 in lieu of blocking if there are no signals from the
88 reading a signal from the file descriptor will consume the signal. The signals
89 used with signalfd file descriptors are normally first blocked so that their
90 handler does not run when a signal arrives. If the signal is not blocked the
91 behavior matches that of
95 is pending then the signal is consumed by the read, otherwise the signal is
96 consumed by the handler.
98 The following operations can be performed upon a signalfd file descriptor:
101 Reads and consumes one or more of the pending signals that match the file
104 The read buffer must be large enough to hold one or more
106 structures, which is described below.
108 will block if there are no matching signals pending, or return
110 if the instance was created with
114 if the child reads from the descriptor it will only consume signals from itself.
116 Provide notification when one of the signals from the
124 Closes the desriptor.
129 structure returned from
131 is a fixed size 128 byte structure defined as follows:
133 typedef struct signalfd_siginfo {
134 uint32_t ssi_signo; /* signal from signal.h */
135 int32_t ssi_errno; /* error from errno.h */
136 int32_t ssi_code; /* signal code */
137 uint32_t ssi_pid; /* PID of sender */
138 uint32_t ssi_uid; /* real UID of sender */
139 int32_t ssi_fd; /* file descriptor (SIGIO) */
140 uint32_t ssi_tid; /* unused */
141 uint32_t ssi_band; /* band event (SIGIO) */
142 uint32_t ssi_overrun; /* unused */
143 uint32_t ssi_trapno; /* trap number that caused signal */
144 int32_t ssi_status; /* exit status or signal (SIGCHLD) */
145 int32_t ssi_int; /* unused */
146 uint64_t ssi_ptr; /* unused */
147 uint64_t ssi_utime; /* user CPU time consumed (SIGCHLD) */
148 uint64_t ssi_stime; /* system CPU time consumed (SIGCHLD) */
149 uint64_t ssi_addr; /* address that generated signal */
150 uint8_t ssi_pad[48]; /* pad size to 128 bytes */
151 } signalfd_siginfo_t;
154 Upon successful completion, a file descriptor associated with the instance
155 is returned. Otherwise, -1 is returned and errno is set to indicate the error.
158 is not -1 and there is no error, the value of
163 .Fn signalfd function
169 descriptor is invalid.
177 descriptor is not a signalfd descriptor or the
183 file descriptors open in the calling process.
185 Unable to allocate state for the file descriptor.