summaryrefslogtreecommitdiff
path: root/src/sys/signalfd.rs
blob: 01ea66b9304cfdf54b22191226a98ad14de54051 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
//! Interface for the `signalfd` syscall.
//!
//! # Signal discarding
//! When a signal can't be delivered to a process (or thread), it will become a pending signal.
//! Failure to deliver could happen if the signal is blocked by every thread in the process or if
//! the signal handler is still handling a previous signal.
//!
//! If a signal is sent to a process (or thread) that already has a pending signal of the same
//! type, it will be discarded. This means that if signals of the same type are received faster than
//! they are processed, some of those signals will be dropped. Because of this limitation,
//! `signalfd` in itself cannot be used for reliable communication between processes or threads.
//!
//! Once the signal is unblocked, or the signal handler is finished, and a signal is still pending
//! (ie. not consumed from a signalfd) it will be delivered to the signal handler.
//!
//! Please note that signal discarding is not specific to `signalfd`, but also happens with regular
//! signal handlers.
use libc::{c_int, pid_t, uid_t};
use unistd;
use {Errno, Result};
use sys::signal::signal::siginfo as signal_siginfo;
pub use sys::signal::{self, SigSet};

use std::os::unix::io::{RawFd, AsRawFd};
use std::mem;

mod ffi {
    use libc::c_int;
    use sys::signal::sigset_t;

    extern {
        pub fn signalfd(fd: c_int, mask: *const sigset_t, flags: c_int) -> c_int;
    }
}

bitflags!{
    flags SfdFlags: c_int {
        const SFD_NONBLOCK  = 0o00004000, // O_NONBLOCK
        const SFD_CLOEXEC   = 0o02000000, // O_CLOEXEC
    }
}

pub const CREATE_NEW_FD: RawFd = -1;

/// Creates a new file descriptor for reading signals.
///
/// **Important:** please read the module level documentation about signal discarding before using
/// this function!
///
/// The `mask` parameter specifies the set of signals that can be accepted via this file descriptor.
///
/// A signal must be blocked on every thread in a process, otherwise it won't be visible from
/// signalfd (the default handler will be invoked instead).
///
/// See [the signalfd man page for more information](http://man7.org/linux/man-pages/man2/signalfd.2.html)
pub fn signalfd(fd: RawFd, mask: &SigSet, flags: SfdFlags) -> Result<RawFd> {
    unsafe {
        Errno::result(ffi::signalfd(fd as c_int, mask.as_ref(), flags.bits()))
    }
}

/// A helper struct for creating, reading and closing a `signalfd` instance.
///
/// **Important:** please read the module level documentation about signal discarding before using
/// this struct!
///
/// # Examples
///
/// ```
/// use nix::sys::signalfd::*;
///
/// let mut mask = SigSet::empty();
/// mask.add(signal::SIGUSR1).unwrap();
///
/// // Block the signal, otherwise the default handler will be invoked instead.
/// mask.thread_block().unwrap();
///
/// // Signals are queued up on the file descriptor
/// let mut sfd = SignalFd::with_flags(&mask, SFD_NONBLOCK).unwrap();
///
/// match sfd.read_signal() {
///     // we caught a signal
///     Ok(Some(sig)) => (),
///
///     // there were no signals waiting (only happens when the SFD_NONBLOCK flag is set,
///     // otherwise the read_signal call blocks)
///     Ok(None) => (),
///
///     Err(err) => (), // some error happend
/// }
/// ```
#[derive(Debug)]
pub struct SignalFd(RawFd);

impl SignalFd {
    pub fn new(mask: &SigSet) -> Result<SignalFd> {
        Self::with_flags(mask, SfdFlags::empty())
    }

    pub fn with_flags(mask: &SigSet, flags: SfdFlags) -> Result<SignalFd> {
        let fd = try!(signalfd(CREATE_NEW_FD, mask, flags));

        Ok(SignalFd(fd))
    }

    pub fn set_mask(&mut self, mask: &SigSet) -> Result<()> {
        signalfd(self.0, mask, SfdFlags::empty()).map(|_| ())
    }

    pub fn read_signal(&mut self) -> Result<Option<siginfo>> {
        let mut buffer: [u8; SIGINFO_SIZE] = unsafe { mem::uninitialized() };

        match unistd::read(self.0, &mut buffer) {
            Ok(SIGINFO_SIZE) => Ok(Some(unsafe { mem::transmute_copy(&buffer) })),
            Ok(_) => unreachable!("partial read on signalfd"),
            Err(Error::Sys(Errno::EAGAIN)) => Ok(None),
            Err(error) => Err(error)
        }
    }
}

impl Drop for SignalFd {
    fn drop(&mut self) {
        let _ = unistd::close(self.0);
    }
}

impl AsRawFd for SignalFd {
    fn as_raw_fd(&self) -> RawFd {
        self.0
    }
}

impl Iterator for SignalFd {
    type Item = siginfo;

    fn next(&mut self) -> Option<Self::Item> {
        match self.read_signal() {
            Ok(Some(sig)) => Some(sig),
            Ok(None) => None,
            Err(..) => None,
        }
    }
}

pub const SIGINFO_SIZE: usize = 128;
pub const SIGINFO_PADDING: usize = 48;

#[derive(Debug, Clone, PartialEq)]
#[repr(C, packed)]
pub struct siginfo {
    pub ssi_signo: u32,
    pub ssi_errno: i32,
    pub ssi_code: i32,
    pub ssi_pid: u32,
    pub ssi_uid: u32,
    pub ssi_fd: i32,
    pub ssi_tid: u32,
    pub ssi_band: u32,
    pub ssi_overrun: u32,
    pub ssi_trapno: u32,
    pub ssi_status: i32,
    pub ssi_int: i32,
    pub ssi_ptr: u64,
    pub ssi_utime: u64,
    pub ssi_stime: u64,
    pub ssi_addr: u64,
}

impl Into<signal_siginfo> for siginfo {
    fn into(self) -> signal_siginfo {
        signal_siginfo {
            si_signo: self.ssi_signo as c_int,
            si_errno: self.ssi_errno as c_int,
            si_code: self.ssi_code as c_int,
            pid: self.ssi_pid as pid_t,
            uid: self.ssi_uid as uid_t,
            status: self.ssi_status as c_int,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::mem;

    #[test]
    fn check_siginfo_size() {
        assert_eq!(mem::size_of::<siginfo>() + SIGINFO_PADDING, SIGINFO_SIZE);
    }

    #[test]
    fn create_signalfd() {
        let mask = SigSet::empty();
        let fd = SignalFd::new(&mask);
        assert!(fd.is_ok());
    }

    #[test]
    fn create_signalfd_with_opts() {
        let mask = SigSet::empty();
        let fd = SignalFd::with_flags(&mask, SFD_CLOEXEC | SFD_NONBLOCK);
        assert!(fd.is_ok());
    }

    #[test]
    fn read_empty_signalfd() {
        let mask = SigSet::empty();
        let mut fd = SignalFd::with_flags(&mask, SFD_NONBLOCK).unwrap();

        let res = fd.read_signal();
        assert_eq!(res, Ok(None));
    }
}