rustix/process/id.rs
1//! Unix user, group, and process identifiers.
2//!
3//! # Safety
4//!
5//! The `Uid`, `Gid`, and `Pid` types can be constructed from raw integers,
6//! which is marked unsafe because actual OS's assign special meaning to some
7//! integer values.
8#![allow(unsafe_code)]
9
10use crate::{backend, io};
11#[cfg(feature = "alloc")]
12use alloc::vec::Vec;
13
14pub use crate::pid::{Pid, RawPid};
15pub use crate::ugid::{Gid, RawGid, RawUid, Uid};
16
17/// `getuid()`—Returns the process' real user ID.
18///
19/// # References
20/// - [POSIX]
21/// - [Linux]
22/// - [FreeBSD]
23/// - [illumos]
24/// - [NetBSD]
25///
26/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/getuid.html
27/// [Linux]: https://man7.org/linux/man-pages/man2/getuid.2.html
28/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=getuid&sektion=2
29/// [illumos]: https://www.illumos.org/man/2/getuid
30/// [NetBSD]: https://man.netbsd.org/getuid.2
31#[inline]
32#[must_use]
33pub fn getuid() -> Uid {
34 backend::ugid::syscalls::getuid()
35}
36
37/// `geteuid()`—Returns the process' effective user ID.
38///
39/// # References
40/// - [POSIX]
41/// - [Linux]
42/// - [FreeBSD]
43/// - [illumos]
44/// - [NetBSD]
45///
46/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/geteuid.html
47/// [Linux]: https://man7.org/linux/man-pages/man2/geteuid.2.html
48/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=geteuid&sektion=2
49/// [illumos]: https://www.illumos.org/man/2/geteuid
50/// [NetBSD]: https://man.netbsd.org/geteuid.2
51#[inline]
52#[must_use]
53pub fn geteuid() -> Uid {
54 backend::ugid::syscalls::geteuid()
55}
56
57/// `getgid()`—Returns the process' real group ID.
58///
59/// # References
60/// - [POSIX]
61/// - [Linux]
62/// - [FreeBSD]
63/// - [illumos]
64/// - [NetBSD]
65///
66/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/getgid.html
67/// [Linux]: https://man7.org/linux/man-pages/man2/getgid.2.html
68/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=getgid&sektion=2
69/// [illumos]: https://www.illumos.org/man/2/getgid
70/// [NetBSD]: https://man.netbsd.org/getgid.2
71#[inline]
72#[must_use]
73pub fn getgid() -> Gid {
74 backend::ugid::syscalls::getgid()
75}
76
77/// `getegid()`—Returns the process' effective group ID.
78///
79/// # References
80/// - [POSIX]
81/// - [Linux]
82/// - [FreeBSD]
83/// - [illumos]
84/// - [NetBSD]
85///
86/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/getegid.html
87/// [Linux]: https://man7.org/linux/man-pages/man2/getegid.2.html
88/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=getegid&sektion=2
89/// [illumos]: https://www.illumos.org/man/2/getegid
90/// [NetBSD]: https://man.netbsd.org/getegid.2
91#[inline]
92#[must_use]
93pub fn getegid() -> Gid {
94 backend::ugid::syscalls::getegid()
95}
96
97/// `getpid()`—Returns the process' ID.
98///
99/// # References
100/// - [POSIX]
101/// - [Linux]
102/// - [FreeBSD]
103/// - [illumos]
104/// - [NetBSD]
105///
106/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/getpid.html
107/// [Linux]: https://man7.org/linux/man-pages/man2/getpid.2.html
108/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=getpid&sektion=2
109/// [illumos]: https://www.illumos.org/man/2/getpid
110/// [NetBSD]: https://man.netbsd.org/getpid.2
111#[inline]
112#[must_use]
113pub fn getpid() -> Pid {
114 backend::pid::syscalls::getpid()
115}
116
117/// `getppid()`—Returns the parent process' ID.
118///
119/// This will return `None` if the current process has no parent (or no parent
120/// accessible in the current PID namespace), such as if the current process is
121/// the init process ([`Pid::INIT`]).
122///
123/// # References
124/// - [POSIX]
125/// - [Linux]
126/// - [FreeBSD]
127/// - [illumos]
128/// - [NetBSD]
129///
130/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/getppid.html
131/// [Linux]: https://man7.org/linux/man-pages/man2/getppid.2.html
132/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=getppid&sektion=2
133/// [illumos]: https://www.illumos.org/man/2/getppid
134/// [NetBSD]: https://man.netbsd.org/getppid.2
135#[inline]
136#[must_use]
137pub fn getppid() -> Option<Pid> {
138 backend::process::syscalls::getppid()
139}
140
141/// `getpgid(pid)`—Returns the process group ID of the given process.
142///
143/// # References
144/// - [POSIX]
145/// - [Linux]
146/// - [FreeBSD]
147/// - [illumos]
148/// - [NetBSD]
149///
150/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/getpgid.html
151/// [Linux]: https://man7.org/linux/man-pages/man2/getpgid.2.html
152/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=getpgid&sektion=2
153/// [illumos]: https://www.illumos.org/man/2/getpgid
154/// [NetBSD]: https://man.netbsd.org/getpgid.2
155#[inline]
156pub fn getpgid(pid: Option<Pid>) -> io::Result<Pid> {
157 backend::process::syscalls::getpgid(pid)
158}
159
160/// `setpgid(pid, pgid)`—Sets the process group ID of the given process.
161///
162/// # References
163/// - [POSIX]
164/// - [Linux]
165/// - [FreeBSD]
166/// - [illumos]
167/// - [NetBSD]
168///
169/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/setpgid.html
170/// [Linux]: https://man7.org/linux/man-pages/man2/setpgid.2.html
171/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=setpgid&sektion=2
172/// [illumos]: https://www.illumos.org/man/2/setpgid
173/// [NetBSD]: https://man.netbsd.org/setpgid.2
174#[inline]
175pub fn setpgid(pid: Option<Pid>, pgid: Option<Pid>) -> io::Result<()> {
176 backend::process::syscalls::setpgid(pid, pgid)
177}
178
179/// `getpgrp()`—Returns the process' group ID.
180///
181/// # References
182/// - [POSIX]
183/// - [Linux]
184/// - [FreeBSD]
185/// - [illumos]
186/// - [NetBSD]
187///
188/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/getpgrp.html
189/// [Linux]: https://man7.org/linux/man-pages/man2/getpgrp.2.html
190/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=getpgrp&sektion=2
191/// [illumos]: https://www.illumos.org/man/2/getpgrp
192/// [NetBSD]: https://man.netbsd.org/getpgrp.2
193#[inline]
194#[must_use]
195pub fn getpgrp() -> Pid {
196 backend::process::syscalls::getpgrp()
197}
198
199/// `getsid(pid)`—Get the session ID of the given process.
200///
201/// # References
202/// - [POSIX]
203/// - [Linux]
204/// - [FreeBSD]
205/// - [illumos]
206/// - [NetBSD]
207///
208/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/getsid.html
209/// [Linux]: https://man7.org/linux/man-pages/man2/getsid.2.html
210/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=getsid&sektion=2
211/// [illumos]: https://www.illumos.org/man/2/getsid
212/// [NetBSD]: https://man.netbsd.org/getsid.2
213#[cfg(not(target_os = "redox"))]
214#[inline]
215pub fn getsid(pid: Option<Pid>) -> io::Result<Pid> {
216 backend::process::syscalls::getsid(pid)
217}
218
219/// `setsid()`—Create a new session.
220///
221/// # References
222/// - [POSIX]
223/// - [Linux]
224/// - [FreeBSD]
225/// - [illumos]
226/// - [NetBSD]
227///
228/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/setsid.html
229/// [Linux]: https://man7.org/linux/man-pages/man2/setsid.2.html
230/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=setsid&sektion=2
231/// [illumos]: https://www.illumos.org/man/2/setsid
232/// [NetBSD]: https://man.netbsd.org/setsid.2
233#[inline]
234pub fn setsid() -> io::Result<Pid> {
235 backend::process::syscalls::setsid()
236}
237
238/// `getgroups()`—Return a list of the current user's groups.
239///
240/// # References
241/// - [POSIX]
242/// - [Linux]
243/// - [FreeBSD]
244/// - [NetBSD]
245///
246/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/getgroups.html
247/// [Linux]: https://man7.org/linux/man-pages/man2/getgroups.2.html
248/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=getgroups&sektion=2
249/// [NetBSD]: https://man.netbsd.org/getgroups.2
250#[cfg(feature = "alloc")]
251#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
252pub fn getgroups() -> io::Result<Vec<Gid>> {
253 // This code would benefit from having a better way to read into
254 // uninitialized memory, but that requires `unsafe`.
255 let mut buffer = Vec::with_capacity(0);
256 let ngroups = backend::process::syscalls::getgroups(&mut buffer)?;
257 buffer.resize(ngroups, Gid::ROOT);
258 backend::process::syscalls::getgroups(&mut buffer)?;
259 Ok(buffer)
260}