https://github.com/grinnz/unix-groups-ffi

Unix::Groups::FFI - Interface to Unix group syscalls
https://github.com/grinnz/unix-groups-ffi

Last synced: 5 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/grinnz/unix-groups-ffi
• Owner: Grinnz
• License: other
• Created: 2018-02-16T19:34:16.000Z (almost 7 years ago)
• Default Branch: master
• Last Pushed: 2020-01-09T23:45:29.000Z (almost 5 years ago)
• Last Synced: 2024-11-13T05:19:54.895Z (about 2 months ago)
• Language: Perl
• Homepage: https://metacpan.org/pod/Unix::Groups::FFI
• Size: 36.1 KB
• Stars: 1
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.pod
  • Changelog: Changes
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

        
=pod

=head1 NAME

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

=head1 SYNOPSIS

  use Unix::Groups::FFI qw(getgroups setgroups getgrouplist initgroups);

  my @gids = getgroups;

  setgroups(@gids);

  my @gids = getgrouplist($username, $gid);

  initgroups($username, $gid);

=head1 DESCRIPTION

This module provides a L interface to several syscalls

related to Unix groups, including L, L,

L, and L. As such it will only work on

Unix-like operating systems.

=head1 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.

=head2 getgroups

  my @gids = getgroups;

Returns the supplementary group IDs of the current process via L.

=head2 setgroups

  setgroups(@gids);

Sets the supplementary group IDs for the current process via L.

Attempting to set more than C groups (32 before Linux 2.6.4 or

65536 since Linux 2.6.4) will result in an C error. Passing an empty

list of group IDs may result in unspecified behavior. The C

L or equivalent privilege is required.

=head2 getgrouplist

  my @gids = getgrouplist($username, $gid);

  my @gids = getgrouplist($username);

Returns the group IDs for all groups of which C<$username> is a member, also

including C<$gid> (without repetition), via L. If C<$username>

does not exist on the system, an C error will result.

As a special case, the primary group ID of C<$username> is included if C<$gid>

is not passed.

=head2 initgroups

  initgroups($username, $gid);

  initgroups($username);

Initializes the supplementary group access list for the current process to all

groups of which C<$username> is a member, also including C<$gid> (without

repetition), via L. If C<$username> does not exist on the

system, an C error will result. The C

L or equivalent privilege is required.

As a special case, the primary group ID of C<$username> is included if C<$gid>

is not passed.

=head1 ERROR HANDLING

All functions will throw an exception containing the syscall error message in

the event of an error. L 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.

=head1 BUGS

Report any issues on the public bugtracker.

=head1 AUTHOR

Dan Book 

=head1 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)

=head1 SEE ALSO

L, L, L

=cut