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

 NAME
   sec_rgy_pgo_get_by_eff_unix_num - Returns the name and data for a
                                     PGO item identified by its
                                     effective UNIX number

 SYNOPSIS

   #include <dce/pgo.h>

   void sec_rgy_pgo_get_by_eff_unix_num(
           sec_rgy_handle_t context,
           sec_rgy_domain_t name_domain,
           sec_rgy_name_t scope,
           signed32 unix_id,
           boolean32 allow_aliases,
           sec_rgy_cursor_t *item_cursor,
           sec_rgy_pgo_item_t *pgo_item,
           sec_rgy_name_t name,
           boolean32 *overridden,
           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_domain
          This variable identifies the type of the principal, group, or
          organization (PGO) item identified by the given name.  The
          valid values are as follows:

          sec_rgy_domain_person
                      The UNIX number identifies a principal.

          sec_rgy_domain_group
                      The UNIX number identifies a group.

   Note that this function does not support the value sec_rgy_domain_org.

   scope  A character string (type sec_rgy_name_t) containing the scope
          of the desired search. The registry database is designed to
          accommodate a tree-structured name hierarchy. The scope of a
          search is the name of the branch under which the search takes
          place. For example, all names in a registry might start with
          /alpha, and be divided further into /beta or /gamma. To search
          only the part of the database under /beta, the scope of the
          search would be /alpha/beta, and any resulting PGO items would
          have names beginning with this string. Note that these naming
          conventions need not have anything to do with group or
          organization PGO item membership lists.

   unix_id
          The UNIX number of the desired registry PGO item.

   allow_aliases
          A boolean32 value indicating whether to search for a primary
          PGO item, or whether the search can be satisfied with an alias.
          If TRUE, the routine returns the next entry found for the PGO
          item. If FALSE, the routine returns only the primary entry.

   Input/Output

   item_cursor
          An opaque pointer indicating a specific PGO item entry in the
          registry database. The sec_rgy_pgo_get_next() 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 the value
          sec_rgy_no_more_entries in the status parameter.  Use
          sec_rgy_cursor_reset() to reset the cursor.

   Output

   pgo_item
          A pointer to a sec_rgy_pgo_item_t structure to receive the data
          for the returned PGO item. The data in this structure includes
          the PGO item's name, UUID, UNIX number (if any), and
          administrative data, such as whether the item, if a principal,
          may have a concurrent group set.  The data is as it appears in
          the registry, for that UNIX number.

   name   A pointer to a sec_rgy_name_t character string containing the
          returned name for the PGO item.

   overridden
          A pointer to a boolean32 value indicating whether or not the
          supplied UNIX number has an entry in the local override file
          (passwd_override or group_override). [NOT APPLICABLE ON OPENVMS]

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

 DESCRIPTION

   The sec_rgy_pgo_get_by_eff_unix_num() routine returns the name and
   data for a PGO item. The desired item is identified by its type
   (domain) and its UNIX number.

   This routine is similar to the sec_rgy_pgo_get_by_unix_num() routine.
   The difference between the routines is that on UNIX,
   sec_rgy_pgo_get_by_eff_unix_num() first searches the local override
   files for the respective name_domain for a match with the supplied
   UNIX number.  If an override match is found, and an account or group
   name is found in that entry, then that name is used to obtain PGO
   data from the registry and the value of the overridden parameter is
   set to TRUE.

   The item_cursor parameter specifies the starting point for the search
   through the registry database.  It provides an automatic place holder
   in the database.  The routine automatically updates this variable to
   point to the next PGO item after the returned item.  The returned
   cursor location can be supplied on a subsequent database access call
   that also uses a PGO item cursor.

   Permissions Required

   The sec_rgy_pgo_get_by_eff_unix_num() routine requires the r (read)
   permission on the PGO item to be viewed.

 CAUTIONS

   There are several different types of cursors used in the registry
   Application Programmer Interface (API). Some cursors point to PGO
   items, others point to members in a membership list, and others point
   to account data. Do not use a cursor for one sort of object in a call
   expecting another sort of object. For example, you cannot use the same
   cursor on a call to sec_rgy_acct_get_projlist() and
   sec_rgy_pgo_get_next().  The behavior in this case is undefined.

   Furthermore, cursors are specific to a server. A cursor pointing
   into one replica of the registry database is useless as a pointer
   into another replica.

   Use sec_rgy_cursor_reset() to renew a cursor for use with another
   call or for another server.

 FILES

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

 ERRORS

   sec_rgy_no_more_entries
                The cursor is at the end of the list of PGO items.

   sec_rgy_object_not_found
                The specified PGO item was not found.

   sec_rgy_server_unavailable
                The DCE Registry Server is unavailable.

   error_status_ok
                The call was successful.

 RELATED INFORMATION

   Functions: sec_intro
              sec_rgy_pgo_add
              sec_rgy_pgo_get_by_id
              sec_rgy_pgo_get_by_name
              sec_rgy_pgo_get_by_unix_num
              sec_rgy_pgo_get_next
              sec_rgy_pgo_id_to_name
              sec_rgy_pgo_id_to_unix_num
              sec_rgy_pgo_name_to_id
              sec_rgy_pgo_unix_num_to_id
              sec_rgy_cursor_reset