NAME
   sec_login_newgroups - Changes the group list for a login context

 SYNOPSIS

 #include <dce/sec_login.h>

 boolean32 sec_login_newgroups(
         sec_login_handle_t login_context,
         sec_login_flags_t flags,
         unsigned32 num_local_groups,
         sec_id_t local_groups[],
         sec_login_handle_t *restricted_context,
         error_status_t *status);

 PARAMETERS

 Input

 login_context
        An opaque handle to login context data. The login context
        contains, among other data, the account principal name and
        UUID, account restrictions, records of group membership, and
        the process home directory.  (See sec_intro for more details
        about the login context.)

 flags  A set of flags of type sec_login_flags_t. These contain
        information about how the new network credentials will be used.
        Currently, the only flag used is sec_login_credentials_private,
        that, when set, implies that the new context is only to be used
        by the calling process. If this flag is not set (flags =
        sec_login_no_flags), descendants of the calling process may
        also use the new network credentials.

 num_local_groups
        An unsigned 32-bit integer containing the number of local group
        identities to include in the new context.

 local_groups[]
        An array of sec_id_t elements. Each element contains the UUID
        of a local group identity to include in the new context. These
        identities are local to the cell. Optionally, each element may
        also contain a pointer to a character string containing the
        name of the local group.

 Output

 restricted_context
        An opaque handle to the login context containing the changed
        group list.

 status
        A pointer to the completion status.  On successful completion,
        the routine returns error_status_ok.  Otherwise, it returns an
        error.

 DESCRIPTION

 The sec_login_newgroups() routine changes the group list for the
 specified login context.  Part of a network identity is a list of the
 various groups to which a principal belongs. The groups are used to
 determine a user's access to various objects and services.  This
 routine returns a new login context that contains the changed group
 list. To remove the new login context when it is no longer needed,
 use sec_login_purge_context().

 This operation does not need to be validated as the user identity does
 not change. Consequently, knowledge of the password is not needed.

 NOTES

  urrently you can have only groups from the local cell.

 FILES
       SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL
              The idl file from which dce/sec_login.h was derived.

 RETURN VALUES

 This routine returns TRUE when the new login context is successfully
 established.

 ERRORS

 sec_login_s_auth_local
              Operation not valid on local context.

 sec_login_s_default_use
              It is an error to try to certify the default context.

 sec_login_s_groupset_invalid
              The input list of group names is invalid. There may be
              groups to which the caller does not belong, or the list
              may contain groups that do not exist.

 error_status_ok
              The call was successful.

 EXAMPLES

 The following example illustrates use of the sec_login_newgroups()
 routine as part of a process to change the groupset:

      sec_login_get_current_context(&login_context, &st);

      sec_login_get_groups(login_context, &num_groups, &groups, &st);

         ...the group IDs have to be converted from the returned UNIX
         numbers into UUIDs (use sec_rgy_pgo_unix_num_to_id)...

      for (i=0; i < num_groups; i++) {
         ... query whether the user wants to discard any of the
         current group memberships. Copy new groupset to the new_groups
         array ...
      }

      if ( !sec_login_newgroups(sec_login_no_flags, num_new_groups,
               new_groups, &login_context, &st)) {
         if (st == sec_login_s_groupset_invalid)
               printf("New groupset invalid0);

         ... application specific error handling ...
      }

 RELATED INFORMATION

 Functions: sec_intro
            sec_login_get_groups
            sec_login_purge_context