GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Unix::Groups::FFI(3) User Contributed Perl Documentation Unix::Groups::FFI(3)

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. Passing an empty list of group IDs may result in unspecified behavior. The "CAP_SETGID" capability or equivalent privilege is required.

  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, an "EINVAL" error will result.

As a special case, the primary group ID of $username is included if $gid is not passed.

  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, an "EINVAL" error will result. The "CAP_SETGID" capability or equivalent privilege is required.

As a special case, the primary group ID of $username is included if $gid is not passed.

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)
2020-01-09 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.