sec_rgy_acct_lookup(3sec)

Synopsis

#include <dce/acct.h>

void sec_rgy_acct_lookup(
sec_rgy_handle_t context,
sec_rgy_login_name_t *name_key,
sec_rgy_cursor_t *account_cursor,
sec_rgy_login_name_t *name_result,
sec_rgy_sid_t *id_sid,
sec_rgy_unix_sid_t *unix_sid,
sec_rgy_acct_key_t *key_parts,
sec_rgy_acct_user_t *user_part,
sec_rgy_acct_admin_t *admin_part,
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_key
A pointer to the account login name. A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. Blank strings serve as wildcards, matching any entry.

Input/Output

account_cursor
An opaque pointer to a specific account in the registry database. If name_key is blank, sec_rgy_acct_lookup( ) returns information about the account to which the cursor is pointing. On return, the cursor points to the next account in the database after the returned account. If name_key is blank and the account_cursor has been reset with sec_rgy_cursor_reset( ), sec_rgy_acct_lookup( ) returns information about the first account in the database. When the end of the list of accounts in the database is reached, the routine returns the value sec_rgy_no_more_entries in the status parameter. Use sec_rgy_cursor_reset( ) to refresh the cursor.

Output

name_result
A pointer to the full login name of the account (including all three names) for which the information is returned. The remaining parameters contain the information belonging to the returned account.

id_sid
A structure containing the three UUIDs of the principal, group, and organization for the account.

unix_sid
A structure containing the three UNIX numbers of the principal, group, and organization for the account.

key_parts
A pointer to the minimum abbreviation allowed when logging in to the account. Abbreviations are not currently implemented and the only legal value is sec_rgy_acct_key_person.

user_part
A pointer to the sec_rgy_acct_user_t structure containing the user part of the account data. This represents such information as the account password, home directory, and default shell, all of which are accessible to, and may be modified by, the account owner.

admin_part
A pointer to the sec_rgy_acct_admin_t structure containing the administrative part of an account's data. This information includes the account creation and expiration dates and flags describing limits to the use of privilege attribute certificates, among other information, and can be modified only by an administrator.

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_acct_lookup( ) routine returns all the information about an account in the registry database. The account can be specified either with name_key or account_cursor. If name_key is completely blank, the routine uses the account_cursor value instead.

For name_key, a zero-length principal, group, or organization key serves as a wildcard. For example, a login name key with the principal and organization fields blank returns the next (possibly first) account whose group matches the input group field. The full login name of the returned account is passed back in name_result.

The account_cursor provides an automatic place holder in the registry database. The routine automatically updates this variable to point to the next account in the database, after the account for which the information was returned. If name_key is blank and the account_cursor has been reset with sec_rgy_cursor_reset( )*O, sec_rgy_acct_lookup( ) returns information about the first account in the database.

Permissions Required
The sec_rgy_acct_lookup( ) routine requires the r (read) permission on the account principal 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

/usr/include/dce/acct.idl
The idl file from which dce/acct.h was derived.

Errors

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

sec_rgy_no_more_entries
The cursor is at the end of the accounts in the registry.

sec_rgy_object_not_found
The input account could not be found by the registry server.

sec_rgy_server_unavailable
The DCE Registry Server is unavailable.

error_status_ok
The call was successful.

Related Information
Functions:

sec_intro(3sec)

sec_rgy_cursor_reset(3sec)

sec_rgy_acct_replace_all(3sec)

sec_rgy_acct_admin_replace(3sec)

sec_rgy_acct_user_replace(3sec)