Unix::Groups::FFI(3pm)

1Unix::Groups::FFI(3)  User Contributed Perl Documentation Unix::Groups::FFI(3)
2
3
4

NAME

6       Unix::Groups::FFI - Interface to Unix group syscalls
7

SYNOPSIS

9         use Unix::Groups::FFI qw(getgroups setgroups getgrouplist initgroups);
10
11         my @gids = getgroups;
12         setgroups(@gids);
13         my @gids = getgrouplist($username, $gid);
14         initgroups($username, $gid);
15

DESCRIPTION

17       This module provides a FFI interface to several syscalls related to
18       Unix groups, including getgroups(2), setgroups(2), getgrouplist(3), and
19       initgroups(3). As such it will only work on Unix-like operating
20       systems.
21

FUNCTIONS

23       All functions are exported individually on demand. A function will not
24       be available for export if the system does not implement the
25       corresponding syscall.
26
27   getgroups
28         my @gids = getgroups;
29
30       Returns the supplementary group IDs of the current process via
31       getgroups(2).
32
33   setgroups
34         setgroups(@gids);
35
36       Sets the supplementary group IDs for the current process via
37       setgroups(2).  Attempting to set more than "NGROUPS_MAX" groups (32
38       before Linux 2.6.4 or 65536 since Linux 2.6.4) will result in an
39       "EINVAL" error. Passing an empty list of group IDs may result in
40       unspecified behavior. The "CAP_SETGID" capability or equivalent
41       privilege is required.
42
43   getgrouplist
44         my @gids = getgrouplist($username, $gid);
45         my @gids = getgrouplist($username);
46
47       Returns the group IDs for all groups of which $username is a member,
48       also including $gid (without repetition), via getgrouplist(3). If
49       $username does not exist on the system, an "EINVAL" error will result.
50
51       As a special case, the primary group ID of $username is included if
52       $gid is not passed.
53
54   initgroups
55         initgroups($username, $gid);
56         initgroups($username);
57
58       Initializes the supplementary group access list for the current process
59       to all groups of which $username is a member, also including $gid
60       (without repetition), via initgroups(3). If $username does not exist on
61       the system, an "EINVAL" error will result. The "CAP_SETGID" capability
62       or equivalent privilege is required.
63
64       As a special case, the primary group ID of $username is included if
65       $gid is not passed.
66

ERROR HANDLING

68       All functions will throw an exception containing the syscall error
69       message in the event of an error. "$!" in perlvar will also have been
70       set by the syscall, so you could check it after trapping the exception
71       for finer exception handling:
72
73         use Unix::Groups::FFI 'setgroups';
74         use Syntax::Keyword::Try;
75         use Errno qw(EINVAL EPERM ENOMEM);
76
77         try { setgroups((0)x2**16) }
78         catch {
79           if ($! == EINVAL) {
80             die 'Tried to set too many groups';
81           } elsif ($! == EPERM) {
82             die 'Insufficient privileges to set groups';
83           } elsif ($! == ENOMEM) {
84             die 'Out of memory';
85           } else {
86             die $@;
87           }
88         }
89
90       See the documentation for each syscall for details on the possible
91       error codes.
92

BUGS

94       Report any issues on the public bugtracker.
95

AUTHOR

97       Dan Book <dbook@cpan.org>
98

COPYRIGHT AND LICENSE

100       This software is Copyright (c) 2018 by Dan Book.
101
102       This is free software, licensed under:
103
104         The Artistic License 2.0 (GPL Compatible)
105