man3/initgroups.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
  11 .\" Modified 2004-10-10 by aeb
  12 .\"
  13 .TH initgroups 3 (date) "Linux man-pages (unreleased)"
  14 .SH NAME
  15 initgroups \- initialize the supplementary group access list
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <sys/types.h>
  22 .B #include <grp.h>
  23 .P
  24 .BI "int initgroups(const char *" user ", gid_t " group );
  25 .fi
  26 .P
  27 .RS -4
  28 Feature Test Macro Requirements for glibc (see
  29 .BR feature_test_macros (7)):
  30 .RE
  31 .P
  32 .BR initgroups ():
  33 .nf
  34     Since glibc 2.19:
  35         _DEFAULT_SOURCE
  36     glibc 2.19 and earlier:
  37         _BSD_SOURCE
  38 .fi
  39 .SH DESCRIPTION
  40 The
  41 .BR initgroups ()
  42 function initializes the group access list by
  43 reading the group database
  44 .I /etc/group
  45 and using all groups of
  46 which
  47 .I user
  48 is a member.
  49 The additional group
  50 .I group
  51 is
  52 also added to the list.
  53 .P
  54 The
  55 .I user
  56 argument must be non-NULL.
  57 .SH RETURN VALUE
  58 The
  59 .BR initgroups ()
  60 function returns 0 on success.
  61 On error, \-1 is returned, and
  62 .I errno
  63 is set to indicate the error.
  64 .SH ERRORS
  65 .TP
  66 .B ENOMEM
  67 Insufficient memory to allocate group information structure.
  68 .TP
  69 .B EPERM
  70 The calling process has insufficient privilege.
  71 See the underlying system call
  72 .BR setgroups (2).
  73 .SH FILES
  74 .TP
  75 .I /etc/group
  76 group database file
  77 .SH ATTRIBUTES
  78 For an explanation of the terms used in this section, see
  79 .BR attributes (7).
  80 .TS
  81 allbox;
  82 lbx lb lb
  83 l l l.
  84 Interface       Attribute       Value
  85 T{
  86 .na
  87 .nh
  88 .BR initgroups ()
  89 T}      Thread safety   MT-Safe locale
  90 .TE
  91 .SH STANDARDS
  92 None.
  93 .SH HISTORY
  94 SVr4, 4.3BSD.
  95 .SH SEE ALSO
  96 .BR getgroups (2),
  97 .BR setgroups (2),
  98 .BR credentials (7)