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

n
nis_db(3N) nis_db(3N)
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, con-
tains 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.
db_list_entries() returns copies of entries that satisfy the given attributes. db_free_result()
can be used to free up the returned db_result structure. attrs is an array of nis_attr structure
Section 3−−656 Hewlett-Packard Company − 2 − HP-UX 11i Version 2: September 2004