NAME
   sec_login_get_groups - Returns the groupset from a login context

 SYNOPSIS

 #include <dce/sec_login.h>

 void sec_login_get_groups(
         sec_login_handle_t login_context,
         unsigned32 *num_groups,
         signed32 **group_set,
         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.)

 Output

 num_groups
        An unsigned 32-bit integer indicating the total number of groups
        returned in the group_set array.

 group_set
        The list of groups to which the user belongs.

 status
     A pointer to the completion status.  On successful completion,
      the routine returns one of the following status codes:

         + error_status_ok to indicate that the login context has
           been validated and certified.

         + sec_login_s_not_certified to indicate that the login context
           has been validated, but not certified.  Although this code
           indicates successful completion, it warns you that the
           context is not validated.

 If the call does not complete successfully, it returns an error.

 DESCRIPTION

 The sec_login_get_groups() routine returns the groups contained in the
 supplied login context.  Part of a network identity is a list of the
 various groups to which the principal belongs. The groups are used to
 determine a user's access to various objects and services.  This
 routine extracts from the login context a list of the groups for which
 the user has established network privileges.

 The routine works only on previously validated contexts.

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

 ERRORS

 sec_login_s_context_invalid
              The login context itself is not valid.

 sec_login_s_info_not_avail
              The login context has no UNIX information.

 sec_login_s_default_use
              Illegal use of the default login handle occurred.

 sec_login_s_not_certified
              The login context has not been certified.

 sec_login_s_not_certified
              The login context is not certified.

 sec_rgy_object_not_found
              The registry server could not find the specified
 	     login context data.

 sec_rgy_server_unavailable
              The DCE Registry Server is unavailable.

 error_status_ok
              The call was successful.

 EXAMPLES

 The following example illustrates use of the sec_login_get_groups()
 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_rgy_acct_get_projlist