HP-UX Reference (11i v2 07/12) - 3 Library Functions N-Z (vol 7)

n
nis_db(3N) nis_db(3N)
NIS+ server converts directory lookup requests in the namespace into table searches. The table it searches
in response to these requests will have the same name as the directory of the name it is searching for.
The structure returned by the DB access routines is defined as:
enum db_status {DB_SUCCESS, DB_NOTFOUND, DB_NOTUNIQUE, DB_BADTABLE,
DB_BADQUERY, DB_BADOBJECT, DB_MEMORY_LIMIT, DB_STORAGE_LIMIT,
DB_INTERNAL_ERROR };
struct db_result {
db_status status; /* Result status */
db_next_desc nextinfo; /* descriptor */
struct {
u_int objects_len;
entry_obj *objects_val;
} objects; /* A variable list of objects */
long ticks; /* execution time in microseconds */
};
For a complete description of NIS+ objects, see nis_objects(3N).
The structure db_next_desc should be used as an opaque handle for db_next_entry( )
and
db_reset_next_entry( )
.
The
nis_attr structure used in db_first_entry
and other related functions is defined as follows:
struct nis_attr {
char *zattr_ndx;
struct {
u_int zattr_val_len;
char *zattr_val_val;
} zattr_val;
};
zattr_ndx
is the name of the attribute. zattr_val_len
is the value of the attribute
zattr_val_val.
In db_result , the objects array contains objects if and only if the result returned in the status variable is
DB_SUCCESS . A null pointer, instead of a pointer to a db_result structure, is returned if there is
insufficient memory to create the structure.
db_initialize() is called prior to any interaction with the database. It takes as argument the path-
name of the file that contains, or will contain, catalog information associated with the database.
db_create_table()
creates a new table using the given table name and the table object. It returns
TRUE if the table was successfully created; FALSE otherwise.
db_destroy_table()
destroys the table of the given name. It returns TRUE if the destruction was
successful; FALSE otherwise.
db_first_entry() returns a copy of the first entry in the specified table that satisfies the given attri-
butes. If no attributes are supplied, a copy of the first entry in the table is returned.
attrs is an array of
nis_attr structure with numattrs number of elements. The returned structure, db_result,contains
a structure, db_next_desc , to be used as an argument to db_next_entry() or
db_reset_next_entry(). db_next_desc should be used only as an opaque handle.
db_free_result() can be used to free up the returned db_result structure.
db_next_entry() returns a copy of the next entry as indicated by the next_handle. An initial call to
db_first_entry(), followed by a sequence of calls to db_next_entry()
, can be used to success-
fully obtain entries of an entire table or entries that satisfy the attributes supplied to
db_first_entry(). db_free_result() can be used to free up the returned
db_result struc-
ture.
db_reset_next_entry() terminates the db_first_entry()
/db_next_entry() sequence as
indicated by next_handle, freeing any resources that have been used to maintain the sequence. After a call
to
db_reset_next_entry(), a call to db_next_entry() using the same next_handle would fail,
returning a DB_BADQUERY reply. db_free_result() can be used to free up the returned
db_result structure.
78 Hewlett-Packard Company − 2 − HP-UX 11i Version 2: December 2007 Update