-
-
09 Jan 2020 23:46:11 UTC
- Distribution: Unix-Groups-FFI
- Module version: 1.000
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues
- Testers (146 / 0 / 5)
- Kwalitee
Bus factor: 1- 100.00% Coverage
- License: artistic_2
- Perl: v5.8.1
- Activity
24 month- Tools
- Download (16.98KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
NAME
Unix::Groups::FFI - Interface to Unix group syscalls
SYNOPSIS
use Unix::Groups::FFI qw(getgroups setgroups getgrouplist initgroups); my @gids = getgroups; setgroups(@gids); my @gids = getgrouplist($username, $gid); initgroups($username, $gid);
DESCRIPTION
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.
FUNCTIONS
All functions are exported individually on demand. A function will not be available for export if the system does not implement the corresponding syscall.
getgroups
my @gids = getgroups;
Returns the supplementary group IDs of the current process via getgroups(2).
setgroups
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 anEINVAL
error. Passing an empty list of group IDs may result in unspecified behavior. TheCAP_SETGID
capability or equivalent privilege is required.getgrouplist
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, anEINVAL
error will result.As a special case, the primary group ID of
$username
is included if$gid
is not passed.initgroups
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, anEINVAL
error will result. TheCAP_SETGID
capability or equivalent privilege is required.As a special case, the primary group ID of
$username
is included if$gid
is not passed.ERROR HANDLING
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.
BUGS
Report any issues on the public bugtracker.
AUTHOR
Dan Book <dbook@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2018 by Dan Book.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
SEE ALSO
Module Install Instructions
To install Unix::Groups::FFI, copy and paste the appropriate command in to your terminal.
cpanm Unix::Groups::FFI
perl -MCPAN -e shell install Unix::Groups::FFI
For more information on module installation, please visit the detailed CPAN module installation guide.