Struct UsersSnapshot 

pub struct UsersSnapshot { /* private fields */ }

A container of user and group instances.

Included users and groups are determined by the method used to construct the snapshot:

• UsersSnapshot::new() includes all system users and groups,
• UsersSnapshot::only_users() filters users and includes only their primary groups,
• UsersSnapshot::filtered() filters users and groups separately.

This cache is immutable: it’s not possible to alter or refresh it in any way after creation. Create a new UsersSnapshot to see changes in the underlying system database.

Examples

use std::sync::Arc;
use uzers::{Users, UsersSnapshot};

let cache     = unsafe { UsersSnapshot::new() };
let user      = cache.get_user_by_uid(502).expect("User not found");
let same_user = cache.get_user_by_uid(502).unwrap();

// The two returned values point to the same User
assert!(Arc::ptr_eq(&user, &same_user));

use uzers::{AllUsers, UsersSnapshot};

// Exclude MacOS system users
let cache = unsafe { UsersSnapshot::only_users(|u| u.uid() >= 500) };

// Users and groups can be iterated
let user_count = cache.get_all_users().count();

See also

Unless iteration is required, UsersCache is likely safer, easier and faster.

For thread safety considerations, see the users::cache module documentation.

Implementations

impl UsersSnapshot

pub unsafe fn filtered<U, G>(user_filter: U, group_filter: G) -> Self

where U: FnMut(&User) -> bool, G: FnMut(&Group) -> bool,

Creates a new snapshot containing all system users and groups that pass the filter.

Safety

This is unsafe because we cannot prevent data races if two caches were attempted to be initialised on different threads at the same time. For more information, see the all_users documentation.

Note that this method uses both all_users and all_groups.

Examples

use uzers::cache::UsersSnapshot;

// Exclude Linux system users, include all groups
let snapshot = unsafe {
    UsersSnapshot::filtered(|u| u.uid() >= 1000, |_| true)
};

See also

• UsersSnapshot::only_users() - if only primary groups of users are needed
• UsersSnapshot::new() - if no filtering is needed

pub unsafe fn only_users<F>(user_filter: F) -> Self

where F: FnMut(&User) -> bool,

Creates a new snapshot containing all system users that pass the filter and their primary groups.

Note that some primary groups may be missing on the system.

Safety

This is unsafe because we cannot prevent data races if two caches were attempted to be initialised on different threads at the same time. For more information, see the all_users documentation.

Note that this method uses both all_users and all_groups.

Examples

use uzers::cache::UsersSnapshot;

// Include Linux system users and their primary groups
let snapshot = unsafe { UsersSnapshot::only_users(|u| u.uid() < 1000) };

See also

• UsersSnapshot::filtered() - for more elaborate group filtering
• UsersSnapshot::new() - if no filtering is needed

pub unsafe fn new() -> Self

Creates a new snapshot containing all system users and groups.

Safety

This is unsafe because we cannot prevent data races if two caches were attempted to be initialised on different threads at the same time. For more information, see the all_users documentation.

Note that this method uses both all_users and all_groups.

Examples

use uzers::cache::UsersSnapshot;

let snapshot = unsafe { UsersSnapshot::new() };

See also

UsersSnapshot::only_users(), UsersSnapshot::filtered() provide performance benefits if only some users and groups will be needed.

Trait Implementations

impl AllGroups for UsersSnapshot

type GroupIter<'a> = FilterMap<Values<'a, u32, Option<Arc<Group>>>, for<'b> fn(&'b Option<Arc<Group>>) -> Option<&'b Group>>

Group iterator returned by get_all_groups.

fn get_all_groups(&self) -> Self::GroupIter<'_>

Creates a new iterator over every group.

impl AllUsers for UsersSnapshot

type UserIter<'a> = FilterMap<Values<'a, u32, Option<Arc<User>>>, for<'b> fn(&'b Option<Arc<User>>) -> Option<&'b User>>

User iterator returned by get_all_users.

fn get_all_users(&self) -> Self::UserIter<'_>

Creates a new iterator over every user.

impl Default for UsersSnapshot

fn default() -> UsersSnapshot

Returns the “default value” for a type.

impl Groups for UsersSnapshot

fn get_group_by_gid(&self, gid: gid_t) -> Option<Arc<Group>>

Returns a Group if one exists for the given group ID; otherwise, returns None.

fn get_group_by_name<S: AsRef<OsStr> + ?Sized>( &self, group_name: &S, ) -> Option<Arc<Group>>

Returns a Group if one exists for the given groupname; otherwise, returns None.

fn get_current_gid(&self) -> gid_t

Returns the group ID for the user running the process.

fn get_current_groupname(&self) -> Option<Arc<OsStr>>

Returns the group name of the user running the process.

fn get_effective_gid(&self) -> gid_t

Returns the effective group id.

fn get_effective_groupname(&self) -> Option<Arc<OsStr>>

Returns the effective group name.

impl Users for UsersSnapshot

fn get_user_by_uid(&self, uid: uid_t) -> Option<Arc<User>>

Returns a User if one exists for the given user ID; otherwise, returns None.

fn get_user_by_name<S: AsRef<OsStr> + ?Sized>( &self, username: &S, ) -> Option<Arc<User>>

Returns a User if one exists for the given username; otherwise, returns None.

fn get_current_uid(&self) -> uid_t

Returns the user ID for the user running the process.

fn get_current_username(&self) -> Option<Arc<OsStr>>

Returns the username of the user running the process.

fn get_effective_uid(&self) -> uid_t

Returns the effective user id.

fn get_effective_username(&self) -> Option<Arc<OsStr>>

Returns the effective username.