Unix::Groups::FFI - Interface to Unix group syscalls
use Unix::Groups::FFI qw(getgroups setgroups getgrouplist initgroups); my @gids = getgroups; setgroups(@gids); my @gids = getgrouplist($username, $gid); initgroups($username, $gid);
This module provides a FFI interface to several syscalls related to Unix groups, including getgroups(2), setgroups(2), getgrouplist(3), and initgroups(3). As such it will only work on Unix-like operating systems.
All functions are exported individually on demand. A function will not be available for export if the system does not implement the corresponding syscall.
my @gids = getgroups;
Returns the supplementary group IDs of the current process via getgroups(2).
setgroups(@gids);
Sets the supplementary group IDs for the current process via setgroups(2). Attempting to set more than NGROUPS_MAX groups (32 before Linux 2.6.4 or 65536 since Linux 2.6.4) will result in an EINVAL error. The CAP_SETGID capability or equivalent privilege is required.
NGROUPS_MAX
EINVAL
CAP_SETGID
my @gids = getgrouplist($username, $gid); my @gids = getgrouplist($username);
Returns the group IDs for all groups of which $username is a member, also including $gid (without repetition), via getgrouplist(3). If $username does not exist on the system, only $gid will be returned.
$username
$gid
As a special case, the primary group ID of $username is included if $gid is not passed (an EINVAL error will result if the username does not exist).
initgroups($username, $gid); initgroups($username);
Initializes the supplementary group access list for the current process to all groups of which $username is a member, also including $gid (without repetition), via initgroups(3). If $username does not exist on the system, the supplementary group access list will be set only to $gid. The CAP_SETGID capability or equivalent privilege is required.
All functions will throw an exception containing the syscall error message in the event of an error. "$!" in perlvar will also have been set by the syscall, so you could check it after trapping the exception for finer exception handling:
use Unix::Groups::FFI 'setgroups'; use Syntax::Keyword::Try; use Errno qw(EINVAL EPERM ENOMEM); try { setgroups((0)x2**16) } catch { if ($! == EINVAL) { die 'Tried to set too many groups'; } elsif ($! == EPERM) { die 'Insufficient privileges to set groups'; } elsif ($! == ENOMEM) { die 'Out of memory'; } else { die $@; } }
See the documentation for each syscall for details on the possible error codes.
Report any issues on the public bugtracker.
Dan Book <dbook@cpan.org>
This software is Copyright (c) 2018 by Dan Book.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
POSIX, credentials(7), capabilities(7)
To install Unix::Groups::FFI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Unix::Groups::FFI
CPAN shell
perl -MCPAN -e shell install Unix::Groups::FFI
For more information on module installation, please visit the detailed CPAN module installation guide.