sec_rgy_pgo_get_by_eff_unix_num-Returns the name and data for a PGO item identified by its effective UNIX number
#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);
An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle.
This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows:
The UNIX number identifies a principal.
The UNIX number identifies a group.
Note that this function does not support the value sec_rgy_domain_org.
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.
The UNIX number of the desired registry PGO item.
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.
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.
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, even though some of the fields may have been overridden locally.
A pointer to a sec_rgy_name_t character string containing the returned name for the PGO item. This string might contain a local override value if the supplied UNIX number is found in the passwd_override or group_override file.
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).
A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error.
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 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 RequiredThe sec_rgy_pgo_get_by_eff_unix_num() routine requires the r (read) permission on the PGO item to be viewed.
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.
The idl file from which dce/pgo.h was derived.
The local group override file.
The local password override file.
The call was successful.
The cursor is at the end of the list of PGO items.
The specified PGO item was not found.
The DCE Registry Server is unavailable.
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().