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

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

nis_tables(3N) nis_tables(3N)

If the ﬂags parameter contains the ﬂag

MOD_SAMEOBJ then the object pointed to by object is assumed to

be a cached copy of the original object. If the OID of the object passed is different than the OID of the

object the server fetches, then the operation fails with the

NIS_NOTSAMEOBJ

error. This can be used to

implement a simple read-modify-write protocol which will fail if the object is modiﬁed before the client can

write the object back.

If the ﬂag

RETURN_RESULT

has been speciﬁed, the server will return a copy of the resulting object if the

operation was successful.

nis_first_entry()

fetches entries from a table one at a time. This mode of operation is extremely

inefﬁcient and callbacks should be used instead wherever possible. The table containing the entries of

interest is identiﬁed by name. If a search criteria is present in name it is ignored. The value of cookie

within the nis_result structure must be copied by the caller into local storage and passed as an argu-

ment to

nis_next_entry( )

nis_next_entry()

retrieves the next entry from a table speciﬁed by table_name. The order in which

entries are returned is not guaranteed. Further, should an update occur in the table between client calls to

nis_next_entry()

there is no guarantee that an entry that is added or modiﬁed will be seen by the

client. Should an entry be removed from the table that would have been the next entry returned, the error

NIS_CHAINBROKEN is returned instead.

MULTITHREAD USAGE

Thread Safe: Yes

Cancel Safe: Yes

Fork Safe: No

Async-cancel Safe: No

Async-signal Safe: No

These functions can be called safely in a multithreaded environment. These functions may be thread can-

cellation points because they invoke functions that are thread cancellation points.

In a multithreaded environment, these functions are not safe to be called by a child process after

fork()

and before exec(). These functions should not be called by a multithreaded application that support

asynchronous cancellation or asynchronous signals.

RETURN VALUES

These functions return a pointer to a structure of type nis_result :

struct nis_result {

nis_error status;

struct {

u_int objects_len;

nis_object *objects_val;

} objects;

netobj cookie;

u_long zticks;

u_long dticks;

u_long aticks;

u_long cticks;

};

The status member contains the error status of the the operation. A text message that describes the error

can be obtained by calling the function nis_sperrno() (see nis_error(3N)).

The objects structure contains two members. objects_val is an array of nis_object structures; objects_len

is the number of cells in the array. These objects will be freed by a call to nis_freeresult() (see

nis_names(3N)). If you need to keep a copy of one or more objects, they can be copied with the function

nis_clone_object() and freed with the function nis_destroy_object()

(see nis_server(3N)).

The various ticks contain details of where the time (in microseconds) was taken during a request. They can

be used to tune one’s data organization for faster access and to compare different database implementations

(see nis_db(3N)).

zticks

The time spent in the NIS+ service itself, this count starts when the server receives the request and

stops when it sends the reply.

Section 3−−610 Hewlett-Packard Company − 3 − HP-UX 11i Version 1: September 2005