//! Wait for a process to change status

use crate::errno::Errno;

use crate::sys::signal::Signal;

use crate::unistd::Pid;

use crate::Result;

use cfg_if::cfg_if;

use libc::{self, c_int};

use std::convert::TryFrom;

#[cfg(any(

    target_os = "android",

    all(target_os = "linux", not(target_env = "uclibc")),

))]

use std::os::unix::io::{AsRawFd, BorrowedFd};

libc_bitflags!(

    /// Controls the behavior of [`waitpid`].

    pub struct WaitPidFlag: c_int {

        /// Do not block when there are no processes wishing to report status.

        WNOHANG;

        /// Report the status of selected processes which are stopped due to a

        /// [`SIGTTIN`](crate::sys::signal::Signal::SIGTTIN),

        /// [`SIGTTOU`](crate::sys::signal::Signal::SIGTTOU),

        /// [`SIGTSTP`](crate::sys::signal::Signal::SIGTSTP), or

        /// [`SIGSTOP`](crate::sys::signal::Signal::SIGSTOP) signal.

        WUNTRACED;

        /// Report the status of selected processes which have terminated.

        #[cfg(any(linux_android,

                  apple_targets,

                  target_os = "freebsd",

                  target_os = "haiku",

                  target_os = "redox",

                  target_os = "netbsd"))]

        WEXITED;

        /// Report the status of selected processes that have continued from a

        /// job control stop by receiving a

        /// [`SIGCONT`](crate::sys::signal::Signal::SIGCONT) signal.

        WCONTINUED;

        /// An alias for WUNTRACED.

        #[cfg(any(linux_android,

                  apple_targets,

                  target_os = "freebsd",

                  target_os = "haiku",

                  target_os = "redox",

                  target_os = "netbsd"))]

        WSTOPPED;

        /// Don't reap, just poll status.

        #[cfg(any(linux_android,

                  apple_targets,

                  target_os = "freebsd",

                  target_os = "haiku",

                  target_os = "redox",

                  target_os = "netbsd"))]

        WNOWAIT;

        /// Don't wait on children of other threads in this group

        #[cfg(any(linux_android, target_os = "redox"))]

        __WNOTHREAD;

        /// Wait on all children, regardless of type

        #[cfg(any(linux_android, target_os = "redox"))]

        __WALL;

        /// Wait for "clone" children only.

        #[cfg(any(linux_android, target_os = "redox"))]

        __WCLONE;

    }

);

/// Possible return values from `wait()` or `waitpid()`.

///

/// Each status (other than `StillAlive`) describes a state transition

/// in a child process `Pid`, such as the process exiting or stopping,

/// plus additional data about the transition if any.

///

/// Note that there are two Linux-specific enum variants, `PtraceEvent`

/// and `PtraceSyscall`. Portable code should avoid exhaustively

/// matching on `WaitStatus`.

#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]

pub enum WaitStatus {

    /// The process exited normally (as with `exit()` or returning from

    /// `main`) with the given exit code. This case matches the C macro

    /// `WIFEXITED(status)`; the second field is `WEXITSTATUS(status)`.

    Exited(Pid, i32),

    /// The process was killed by the given signal. The third field

    /// indicates whether the signal generated a core dump. This case

    /// matches the C macro `WIFSIGNALED(status)`; the last two fields

    /// correspond to `WTERMSIG(status)` and `WCOREDUMP(status)`.

    Signaled(Pid, Signal, bool),

    /// The process is alive, but was stopped by the given signal. This

    /// is only reported if `WaitPidFlag::WUNTRACED` was passed. This

    /// case matches the C macro `WIFSTOPPED(status)`; the second field

    /// is `WSTOPSIG(status)`.

    Stopped(Pid, Signal),

    /// The traced process was stopped by a `PTRACE_EVENT_*` event. See

    /// [`nix::sys::ptrace`] and [`ptrace`(2)] for more information. All

    /// currently-defined events use `SIGTRAP` as the signal; the third

    /// field is the `PTRACE_EVENT_*` value of the event.

    ///

    /// [`nix::sys::ptrace`]: ../ptrace/index.html

    /// [`ptrace`(2)]: https://man7.org/linux/man-pages/man2/ptrace.2.html

    #[cfg(linux_android)]

    PtraceEvent(Pid, Signal, c_int),

    /// The traced process was stopped by execution of a system call,

    /// and `PTRACE_O_TRACESYSGOOD` is in effect. See [`ptrace`(2)] for

    /// more information.

    ///

    /// [`ptrace`(2)]: https://man7.org/linux/man-pages/man2/ptrace.2.html

    #[cfg(linux_android)]

    PtraceSyscall(Pid),

    /// The process was previously stopped but has resumed execution

    /// after receiving a `SIGCONT` signal. This is only reported if

    /// `WaitPidFlag::WCONTINUED` was passed. This case matches the C

    /// macro `WIFCONTINUED(status)`.

    Continued(Pid),

    /// There are currently no state changes to report in any awaited

    /// child process. This is only returned if `WaitPidFlag::WNOHANG`

    /// was used (otherwise `wait()` or `waitpid()` would block until

    /// there was something to report).

    StillAlive,

}

impl WaitStatus {

    /// Extracts the PID from the WaitStatus unless it equals StillAlive.

    pub fn pid(&self) -> Option<Pid> {

        use self::WaitStatus::*;

        match *self {

            Exited(p, _) | Signaled(p, _, _) | Stopped(p, _) | Continued(p) => {

                Some(p)

            }

            StillAlive => None,

            #[cfg(linux_android)]

            PtraceEvent(p, _, _) | PtraceSyscall(p) => Some(p),

        }

    }

}

fn exited(status: i32) -> bool {

    libc::WIFEXITED(status)

}

fn exit_status(status: i32) -> i32 {

    libc::WEXITSTATUS(status)

}

fn signaled(status: i32) -> bool {

    libc::WIFSIGNALED(status)

}

fn term_signal(status: i32) -> Result<Signal> {

    Signal::try_from(libc::WTERMSIG(status))

}

fn dumped_core(status: i32) -> bool {

    libc::WCOREDUMP(status)

}

fn stopped(status: i32) -> bool {

    libc::WIFSTOPPED(status)

}

fn stop_signal(status: i32) -> Result<Signal> {

    Signal::try_from(libc::WSTOPSIG(status))

}

#[cfg(linux_android)]

fn syscall_stop(status: i32) -> bool {

    // From ptrace(2), setting PTRACE_O_TRACESYSGOOD has the effect

    // of delivering SIGTRAP | 0x80 as the signal number for syscall

    // stops. This allows easily distinguishing syscall stops from

    // genuine SIGTRAP signals.

    libc::WSTOPSIG(status) == libc::SIGTRAP | 0x80

}

#[cfg(linux_android)]

fn stop_additional(status: i32) -> c_int {

    (status >> 16) as c_int

}

fn continued(status: i32) -> bool {

    libc::WIFCONTINUED(status)

}

impl WaitStatus {

    /// Convert a raw `wstatus` as returned by `waitpid`/`wait` into a `WaitStatus`

    ///

    /// # Errors

    ///

    /// Returns an `Error` corresponding to `EINVAL` for invalid status values.

    ///

    /// # Examples

    ///

    /// Convert a `wstatus` obtained from `libc::waitpid` into a `WaitStatus`:

    ///

    /// ```

    /// use nix::sys::wait::WaitStatus;

    /// use nix::sys::signal::Signal;

    /// let pid = nix::unistd::Pid::from_raw(1);

    /// let status = WaitStatus::from_raw(pid, 0x0002);

    /// assert_eq!(status, Ok(WaitStatus::Signaled(pid, Signal::SIGINT, false)));

    /// ```

    pub fn from_raw(pid: Pid, status: i32) -> Result<WaitStatus> {

        Ok(if exited(status) {

            WaitStatus::Exited(pid, exit_status(status))

        } else if signaled(status) {

            WaitStatus::Signaled(pid, term_signal(status)?, dumped_core(status))

        } else if stopped(status) {

            cfg_if! {

                if #[cfg(linux_android)] {

                    fn decode_stopped(pid: Pid, status: i32) -> Result<WaitStatus> {

                        let status_additional = stop_additional(status);

                        Ok(if syscall_stop(status) {

                            WaitStatus::PtraceSyscall(pid)

                        } else if status_additional == 0 {

                            WaitStatus::Stopped(pid, stop_signal(status)?)

                        } else {

                            WaitStatus::PtraceEvent(pid, stop_signal(status)?,

                                                    stop_additional(status))

                        })

                    }

                } else {

                    fn decode_stopped(pid: Pid, status: i32) -> Result<WaitStatus> {

                        Ok(WaitStatus::Stopped(pid, stop_signal(status)?))

                    }

                }

            }

            return decode_stopped(pid, status);

        } else {

            assert!(continued(status));

            WaitStatus::Continued(pid)

        })

    }

    /// Convert a `siginfo_t` as returned by `waitid` to a `WaitStatus`

    ///

    /// # Errors

    ///

    /// Returns an `Error` corresponding to `EINVAL` for invalid values.

    ///

    /// # Safety

    ///

    /// siginfo_t is actually a union, not all fields may be initialized.

    /// The functions si_pid() and si_status() must be valid to call on

    /// the passed siginfo_t.

    #[cfg(any(

        target_os = "android",

        target_os = "freebsd",

        target_os = "haiku",

        all(target_os = "linux", not(target_env = "uclibc")),

    ))]

    unsafe fn from_siginfo(siginfo: &libc::siginfo_t) -> Result<WaitStatus> {

        let si_pid = unsafe { siginfo.si_pid() };

        if si_pid == 0 {

            return Ok(WaitStatus::StillAlive);

        }

        assert_eq!(siginfo.si_signo, libc::SIGCHLD);

        let pid = Pid::from_raw(si_pid);

        let si_status = unsafe { siginfo.si_status() };

        let status = match siginfo.si_code {

            libc::CLD_EXITED => WaitStatus::Exited(pid, si_status),

            libc::CLD_KILLED | libc::CLD_DUMPED => WaitStatus::Signaled(

                pid,

                Signal::try_from(si_status)?,

                siginfo.si_code == libc::CLD_DUMPED,

            ),

            libc::CLD_STOPPED => {

                WaitStatus::Stopped(pid, Signal::try_from(si_status)?)

            }

            libc::CLD_CONTINUED => WaitStatus::Continued(pid),

            #[cfg(linux_android)]

            libc::CLD_TRAPPED => {

                if si_status == libc::SIGTRAP | 0x80 {

                    WaitStatus::PtraceSyscall(pid)

                } else {

                    WaitStatus::PtraceEvent(

                        pid,

                        Signal::try_from(si_status & 0xff)?,

                        (si_status >> 8) as c_int,

                    )

                }

            }

            _ => return Err(Errno::EINVAL),

        };

        Ok(status)

    }

}

/// Wait for a process to change status

///

/// See also [waitpid(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/waitpid.html)

pub fn waitpid<P: Into<Option<Pid>>>(

    pid: P,

    options: Option<WaitPidFlag>,

) -> Result<WaitStatus> {

    use self::WaitStatus::*;

    let mut status: i32 = 0;

    let option_bits = match options {

        Some(bits) => bits.bits(),

        None => 0,

    };

    let res = unsafe {

        libc::waitpid(

            pid.into().unwrap_or_else(|| Pid::from_raw(-1)).into(),

            &mut status as *mut c_int,

            option_bits,

        )

    };

    match Errno::result(res)? {

        0 => Ok(StillAlive),

        res => WaitStatus::from_raw(Pid::from_raw(res), status),

    }

}

/// Wait for any child process to change status or a signal is received.

///

/// See also [wait(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/wait.html)

pub fn wait() -> Result<WaitStatus> {

    waitpid(None, None)

}

/// The ID argument for `waitid`

#[cfg(any(

    target_os = "android",

    target_os = "freebsd",

    target_os = "haiku",

    all(target_os = "linux", not(target_env = "uclibc")),

))]

#[derive(Debug)]

pub enum Id<'fd> {

    /// Wait for any child

    All,

    /// Wait for the child whose process ID matches the given PID

    Pid(Pid),

    /// Wait for the child whose process group ID matches the given PID

    ///

    /// If the PID is zero, the caller's process group is used since Linux 5.4.

    PGid(Pid),

    /// Wait for the child referred to by the given PID file descriptor

    #[cfg(linux_android)]

    PIDFd(BorrowedFd<'fd>),

    /// A helper variant to resolve the unused parameter (`'fd`) problem on platforms

    /// other than Linux and Android.

    #[doc(hidden)]

    _Unreachable(std::marker::PhantomData<&'fd std::convert::Infallible>),

}

/// Wait for a process to change status

///

/// See also [waitid(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/waitid.html)

#[cfg(any(

    target_os = "android",

    target_os = "freebsd",

    target_os = "haiku",

    all(target_os = "linux", not(target_env = "uclibc")),

))]

pub fn waitid(id: Id, flags: WaitPidFlag) -> Result<WaitStatus> {

    let (idtype, idval) = match id {

        Id::All => (libc::P_ALL, 0),

        Id::Pid(pid) => (libc::P_PID, pid.as_raw() as libc::id_t),

        Id::PGid(pid) => (libc::P_PGID, pid.as_raw() as libc::id_t),

        #[cfg(linux_android)]

        Id::PIDFd(fd) => (libc::P_PIDFD, fd.as_raw_fd() as libc::id_t),

        Id::_Unreachable(_) => {

            unreachable!("This variant could never be constructed")

        }

    };

    let siginfo = unsafe {

        // Memory is zeroed rather than uninitialized, as not all platforms

        // initialize the memory in the StillAlive case

        let mut siginfo: libc::siginfo_t = std::mem::zeroed();

        Errno::result(libc::waitid(idtype, idval, &mut siginfo, flags.bits()))?;

        siginfo

    };

    unsafe { WaitStatus::from_siginfo(&siginfo) }

}