VMS Help DCE_SECURITY, API Routines, sec_rgy_unix_getgrnam  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME
   sec_rgy_unix_getgrnam - Returns a UNIX style group entry for the
                           account matching the specified group name

 SYNOPSIS

   #include <dce/rgynbase.h>

   void sec_rgy_unix_getgrnam(
           sec_rgy_handle_t context,
           sec_rgy_name_t name,
           signed32 name_length,
           signed32 max_num_members,
           sec_rgy_cursor_t item_cursor,
           sec_rgy_unix_group_t group_entry,
           signed32 number_members,
           sec_rgy_member_t member_list[],
           error_status_t *status);

 PARAMETERS

   Input

   context
          An opaque handle bound to a registry server.  Use
          sec_rgy_site_open() to acquire a bound handle.

   name   A character string (of type sec_rgy_name_t) specifying the
          group name to be matched.

   name_length
          An signed 32-bit integer specifying the length of name in
          characters.

   max_num_members
          The maximum number of members to be returned by the call.
          This must be no larger than the allocated size of the
          member_list[] array.

   Input/Output

   item_cursor
          An opaque pointer indicating a specific PGO item entry in the
          registry database. The sec_rgy_unix_getgrnam() routine returns
          the PGO item indicated by item_cursor, and advances the cursor
          to point to the next item in the database.  When the end of the
          list of entries is reached, the routine returns
          sec_rgy_no_more_entries.  Use sec_rgy_cursor_reset() to refresh
          the cursor.

   Output

   group_entry
          A UNIX style group entry structure returned with information
          about the account matching name.

   number_members
          An signed 32-bit integer containing the total number of member
          names returned in the member_list[] array.

   member_list[]
          An array of character strings to receive the returned member
          names.  The size allocated for the array is given by max_number.
          If this value is less than the total number of members in the
          membership list, multiple calls must be made to return all of
          the members.

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

 DESCRIPTION

   The sec_rgy_unix_getgrnam() routine looks up the next group entry in
   the registry that matches the input group name and returns the
   corresponding UNIX style group structure.  The structure is in the
   following form:

        typedef struct {
            sec_rgy_name_t              name;
            signed32                    gid;
            sec_rgy_member_buf_t        members;
        }               sec_rgy_unix_group_t;

   The structure includes

     +  The name of the group.

     +  The group's UNIX ID.

     +  A string containing the names of the group members.  This string
        is limited in size by the size of the sec_rgy_member_buf_t type
        defined in rgynbase.idl.

   The routine also returns an array of member names, limited in size
   by the number_members parameter. Note that the array contains only
   the names explicitly specified as members of the group.  A principal
   that was made a member of the group because that group was assigned
   as the principal's primary group will not appear in the array.

   This call is provided in source code form.

 FILES

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

 ERRORS

   sec_rgy_no_more_entries
                The end of the list of entries has been reached.

   sec_rgy bad_data
                The name supplied as input was too long.

   error_status_ok
                The call was successful.

   sec_rgy_server_unavailable
                The DCE Registry Server is unavailable.

 RELATED INFORMATION

   Functions: sec_intro