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

use std::io;
#[cfg(target_os = "macos")]
use std::path::Path;

use crate::libproc::sys::*;

/// `ProcFilter` is used to filter process ids.
/// See [`pids_by_type`] and `pids_by_type_and_path` (macos only) for details.
#[derive(Copy, Clone)]
pub enum ProcFilter {
    /// All processes
    All,
    /// Filter by program group id
    ByProgramGroup {
        /// List PIDs that are members of this process group
        pgrpid: u32,
    },
    /// Filter by TTY
    ByTTY {
        /// List PIDs attached to the specific TTY
        tty: u32,
    },
    /// Filter by (effective) user ID
    ByUID {
        /// List PIDs of processes with the permissions of this specific user.
        uid: u32,
    },
    /// Filter by real user ID
    ByRealUID {
        /// List PIDs of processes started by this specific user.
        ruid: u32,
    },
    /// Filter by parent process ID
    ByParentProcess {
        /// List PIDs of processes that are children of this specific process.
        ppid: u32,
    },
}

/// Returns the PIDs of active processes that match the given [`ProcFilter`] filter.
///
/// # Examples
///
/// Get the list of all running process IDs using [`pids_by_type`] and [`ProcFilter::All`]:
///
/// ```
/// use std::io::Write;
/// use libproc::processes;
///
/// if let Ok(pids) = processes::pids_by_type(processes::ProcFilter::All) {
///     println!("There are {} processes running on this system", pids.len());
/// }
/// ```
///
/// Get a list of running process IDs that are children of the current process:
///
/// ```
/// use std::io::Write;
/// use std::process;
/// use libproc::processes;
///
/// let filter = processes::ProcFilter::ByParentProcess { ppid: process::id() };
/// if let Ok(pids) = processes::pids_by_type(filter) {
///     println!("Found {} child processes of this process", pids.len());
/// }
/// ```
pub fn pids_by_type(filter: ProcFilter) -> io::Result<Vec<u32>> {
    listpids(filter)
}

/// Returns the PIDs of active processes that reference reference an open file
/// with the given path or volume, with or without files opened with the
/// `O_EVTONLY` flag.
///
/// (Files opened with the `O_EVTONLY` flag will not prevent a volume from being
/// unmounted).
///
/// # Examples
///
/// Get the list of all running process IDs that have a specific filename open:
///
/// ```
/// use std::path::Path;
/// use std::io::Write;
/// use libproc::processes;
///
/// let path = Path::new("/etc/hosts");
/// if let Ok(pids) = processes::pids_by_path(&path, false, false) {
///     println!("Found {} processes accessing {}", pids.len(), path.display());
/// }
/// ```
///
/// List all processes that have a file open on a specific volume; the path
/// argument is used to get the filesystem device ID, and processes that have
/// a file open on that same device ID match the filter:
/// ```
/// use std::path::Path;
/// use std::io::Write;
/// use libproc::processes;
///
/// let path = Path::new("/Volumes/MountedDrive");
/// if let Ok(pids) = processes::pids_by_path(&path, true, false) {
///     println!("Found {} processes accessing files on {}", pids.len(), path.display());
/// }
/// ```
#[cfg(target_os = "macos")]
pub fn pids_by_path(
    path: &Path,
    is_volume: bool,
    exclude_event_only: bool,
) -> io::Result<Vec<u32>> {
    listpidspath(ProcFilter::All, path, is_volume, exclude_event_only)
}

/// Returns a filtered list of PIDs of active processes that reference reference
/// an open file with the given path or volume, with or without files opened
/// with the `O_EVTONLY` flag. Use a [`ProcFilter`] member to specify how to
/// filter the list of PIDs returned.
///
/// (Files opened with the `O_EVTONLY` flag will not prevent a volume from being
/// unmounted).
///
/// # Examples
///
/// Get the list of process ids for child processes that have a specific filename open:
///
/// ```
/// use std::path::Path;
/// use std::process;
/// use std::io::Write;
/// use libproc::processes;
///
/// let path = Path::new("/etc/hosts");
/// let filter = processes::ProcFilter::ByParentProcess { ppid: process::id() };
/// if let Ok(pids) = processes::pids_by_type_and_path(filter, &path, false, false) {
///     println!("Found {} processes accessing {}", pids.len(), path.display());
/// }
/// ```
///
/// List all processes within the current process group that have a file open on
/// a specific volume; the path argument is used to get the filesystem device
/// ID, and processes that have a file open on that same device ID match the
/// filter:
/// ```
/// use std::path::Path;
/// use std::process;
/// use std::io::Write;
/// use libproc::processes;
///
/// let path = Path::new("/Volumes/MountedDrive");
/// let filter = processes::ProcFilter::ByParentProcess { ppid: process::id() };
/// if let Ok(pids) = processes::pids_by_type_and_path(filter, &path, true, false) {
///     println!("Found {} processes accessing files on {}", pids.len(), path.display());
/// }
/// ```
#[cfg(target_os = "macos")]
pub fn pids_by_type_and_path(
    filter: ProcFilter,
    path: &Path,
    is_volume: bool,
    exclude_event_only: bool,
) -> io::Result<Vec<u32>> {
    listpidspath(filter, path, is_volume, exclude_event_only)
}