From f82397f2288292ac75d372d793651701fd83ab38 Mon Sep 17 00:00:00 2001 From: auronandace Date: Wed, 3 Jun 2026 15:13:31 +0100 Subject: [PATCH] add descriptions to grp header --- src/header/grp/mod.rs | 44 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/src/header/grp/mod.rs b/src/header/grp/mod.rs index 60b4e5730c..15e31aa4d8 100644 --- a/src/header/grp/mod.rs +++ b/src/header/grp/mod.rs @@ -30,12 +30,15 @@ use crate::{ use super::{errno::*, string::strncmp}; +/// cbindgen:ignore #[cfg(target_os = "linux")] const SEPARATOR: char = ':'; +/// cbindgen:ignore #[cfg(target_os = "redox")] const SEPARATOR: char = ';'; +/// cbindgen:ignore const GROUP_FILE: &core::ffi::CStr = c"/etc/group"; #[derive(Clone, Copy, Debug)] @@ -73,7 +76,9 @@ impl DerefMut for MaybeAllocated { } } +/// cbindgen:ignore static mut GROUP_BUF: Option = None; +/// cbindgen:ignore static mut GROUP: group = group { gr_name: ptr::null_mut(), gr_passwd: ptr::null_mut(), @@ -81,6 +86,7 @@ static mut GROUP: group = group { gr_mem: ptr::null_mut(), }; +/// cbindgen:ignore static LINE_READER: SyncUnsafeCell>>> = SyncUnsafeCell::new(None); /// See . @@ -88,9 +94,16 @@ static LINE_READER: SyncUnsafeCell>>> = SyncUnsafeC #[repr(C)] #[derive(Debug)] pub struct group { + /// The name of the group. pub gr_name: *mut c_char, + /// Non-POSIX, see . + /// + /// Group password. pub gr_passwd: *mut c_char, + /// Numerical group ID. pub gr_gid: gid_t, + /// Pointer to a null-terminated array of character pointers to member + /// names. pub gr_mem: *mut *mut c_char, } @@ -250,6 +263,8 @@ fn parse_grp(line: String, destbuf: Option) -> Result. +/// +/// Searches the group database for an entry with a matching `gid`. #[unsafe(no_mangle)] pub unsafe extern "C" fn getgrgid(gid: gid_t) -> *mut group { let Ok(db) = File::open(GROUP_FILE.into(), fcntl::O_RDONLY) else { @@ -275,6 +290,8 @@ pub unsafe extern "C" fn getgrgid(gid: gid_t) -> *mut group { /// MT-Unsafe race:grnam locale /// /// See . +/// +/// Searches the group database for an entry with a matching `name`. #[unsafe(no_mangle)] pub unsafe extern "C" fn getgrnam(name: *const c_char) -> *mut group { let Ok(db) = File::open(GROUP_FILE.into(), fcntl::O_RDONLY) else { @@ -308,6 +325,9 @@ pub unsafe extern "C" fn getgrnam(name: *const c_char) -> *mut group { /// MT-Safe locale /// /// See . +/// +/// Updates the `group` structure pointed to by `result_buf` and store a +/// pointer to that structure at the location pointed to by `result`. #[unsafe(no_mangle)] pub unsafe extern "C" fn getgrgid_r( gid: gid_t, @@ -369,6 +389,9 @@ pub unsafe extern "C" fn getgrgid_r( /// MT-Safe locale /// /// See . +/// +/// Updates the `group` structure pointed to by `result_buf` and store a +/// pointer to that structure at the location pointed to by `result`. #[unsafe(no_mangle)] pub unsafe extern "C" fn getgrnam_r( name: *const c_char, @@ -415,6 +438,9 @@ pub unsafe extern "C" fn getgrnam_r( /// MT-Unsafe race:grent race:grentbuf locale /// /// See . +/// +/// Returns a pointer to a structure containing the broken-out fields of an +/// entry in the group database. #[unsafe(no_mangle)] pub unsafe extern "C" fn getgrent() -> *mut group { let mut line_reader = unsafe { &mut *LINE_READER.get() }; @@ -447,6 +473,8 @@ pub unsafe extern "C" fn getgrent() -> *mut group { /// MT-Unsafe race:grent locale /// /// See . +/// +/// Closes the group database. #[unsafe(no_mangle)] pub unsafe extern "C" fn endgrent() { unsafe { @@ -457,6 +485,9 @@ pub unsafe extern "C" fn endgrent() { /// MT-Unsafe race:grent locale /// /// See . +/// +/// Rewinds the group database so that the next `getgrent()` call returns the +/// first entry, allowing repeated searches. #[unsafe(no_mangle)] pub unsafe extern "C" fn setgrent() { let line_reader = unsafe { &mut *LINE_READER.get() }; @@ -466,10 +497,11 @@ pub unsafe extern "C" fn setgrent() { *line_reader = Some(BufReader::new(db).lines()); } +// TODO should be guarded by `_DEFAULT_SOURCE` /// MT-Safe locale -/// Not POSIX +/// Non-POSIX, see . /// -/// See . +/// Get a list of groups to which a user belongs. #[unsafe(no_mangle)] pub unsafe extern "C" fn getgrouplist( user: *const c_char, @@ -536,10 +568,11 @@ pub unsafe extern "C" fn getgrouplist( } } +// TODO should be guarded by `_DEFAULT_SOURCE` /// MT-Safe locale -/// Not POSIX +/// Non-POSIX, see . /// -/// See . +/// Initialize the supplementary group access list. #[unsafe(no_mangle)] pub unsafe extern "C" fn initgroups(user: *const c_char, gid: gid_t) -> c_int { let mut groups = [0; limits::NGROUPS_MAX]; @@ -550,7 +583,10 @@ pub unsafe extern "C" fn initgroups(user: *const c_char, gid: gid_t) -> c_int { unsafe { setgroups(count as size_t, groups.as_ptr()) } } +// TODO should be guarded by `_DEFAULT_SOURCE` /// Non-POSIX, see . +/// +/// Set a list of supplementary group IDs. #[unsafe(no_mangle)] pub unsafe extern "C" fn setgroups(size: size_t, list: *const gid_t) -> c_int { unsafe { Sys::setgroups(size, list) }