getprivgrp(2)                                                 getprivgrp(2)




 NAME    [Toc]    [Back]
      getprivgrp(), setprivgrp() - get and set special attributes for group

 SYNOPSIS    [Toc]    [Back]
      #include <sys/privgrp.h>

      int getprivgrp(struct privgrp_map *grplist);

      int setprivgrp(gid_t grpid, const int *mask);

 DESCRIPTION    [Toc]    [Back]
    getprivgrp()
      The getprivgrp() system call returns a table of the privileged group
      assignments into a user-supplied structure.  grplist points to an
      array of structures of type privgrp_map, associating a group ID with a
      privilege mask.  Privilege masks are formed by ORing together elements
      from the access types specified in <sys/privgrp.h>.  The array may
      have gaps in it, distinguished as having a priv_groupno field value of
      PRIV_NONE.  The group number PRIV_GLOBAL gives the global privilege
      mask.  Only information about groups which are in the user's group
      access list, or about the user's real or effective group ID, is
      returned to an ordinary user.  The complete set is returned to a
      privileged user.

    setprivgrp()
      The setprivgrp() system call associates a kernel capability with a
      group ID.  This allows subletting of superuser-like privileges to
      members of a particular group or groups.  setprivgrp() takes two
      arguments: grpid, the integer group ID, and mask, a mask of
      permissions.  The mask is created by treating the access types defined
      in <sys/privgrp.h> as bit numbers (using 1 for the least significant
      bit).  Thus, privilege number 5 would be represented by the bits
      1<<(5-1) or 16.  More generally, privilege p is represented by:
           mask[((p-1) / BITS_PER_INT)] & (1 << ((p-1) % BITS_PER_INT))

      where BITS_PER_INT is 8*sizeof(mask[0]) given 8 bits per byte.  As it
      is possible to have more than word-size distinct privileges, mask is a
      pointer to an integer array of size PRIV_MASKSIZ.

      setprivgrp() privileges include those specified in the file
      <sys/privgrp.h>.  A process can access the system call protected by a
      specific privileged group if it belongs to or has an effective group
      ID of a group having access to the system call.  All processes are
      considered to belong to the pseudo-group PRIV_GLOBAL.

      Specifying a grpid of PRIV_NONE causes privileges to be revoked on all
      privileged groups that have any of the privileges specified in mask.
      Specifying a grpid of PRIV_GLOBAL causes privileges to be granted to
      all processes.





 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 getprivgrp(2)                                                 getprivgrp(2)




      The constant PRIV_MAXGRPS in <sys/privgrp.h> defines the system limit
      on the number of groups that can be assigned privileges.  One of these
      is always the psuedo-group PRIV_GLOBAL, allowing for PRIV_MAXGRPS - 1
      actual groups.

      Only processes with appropriate privileges can use setprivgrp().

 RETURN VALUE    [Toc]    [Back]
      getprivgrp() and setprivgrp() return the following values:

            0   Successful completion.
           -1   Failure.  errno is set to indicate the error.

 ERRORS    [Toc]    [Back]
      If getprivgrp() fails, errno is set to one of the following values.

           [EFAULT]       grplist points to an illegal address.  The
                          reliable detection of this error is implementation
                          dependent.
      If setprivgrp() fails, errno is set to one of the following values.

           [E2BIG]        The request would require assigning privileges to
                          more than PRIV_MAXGRPS groups.

           [EFAULT]       mask points to an illegal address.  The reliable
                          detection of this error is implementation
                          dependent.

           [EINVAL]       mask has bits set for one or more unknown
                          privileges.

           [EINVAL]       grpid is out of range.

           [EPERM]        The caller is not a privileged user.

 EXAMPLES    [Toc]    [Back]
      The following example prints out PRIV_GLOBAL and the group IDs of the
      privilege groups to which the user belongs:

           #include <sys/types.h>

           struct privgrp_map pgrplist[PRIV_MAXGRPS];
           int i;
           gid_t pgid;

           getprivgrp (pgrplist);
           for (i=0; i<PRIV_MAXGRPS; i++) {
               if ((pgid = pgrplist[i].priv_groupno) != PRIV_NONE) {
                   if (pgid == PRIV_GLOBAL)
                       printf ("(PRIV_GLOBAL) ");
                   printf ("privilege group id = %d\n", pgid);



 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 getprivgrp(2)                                                 getprivgrp(2)




               }
           }

 AUTHOR    [Toc]    [Back]
      getprivgrp() and setprivgrp() were developed by HP.

 SEE ALSO    [Toc]    [Back]
      getprivgrp(1), setprivgrp(1M), setgroups(2), privgrp(4).


 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003