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

n
nis_names(3N) nis_names(3N)
On return, the objects array in the result will contain one and possibly several objects that were resolved
by the request. If the FOLLOW_LINKS flag was present, on success the function could return several
entry objects if the link in question pointed within a table. If an error occurred when following a link, the
objects array will contain a copy of the link object itself.
The function
nis_add() will take the object obj and add it to the NIS+ namespace with the name name.
This operation will fail if the client making the request does not have the create access right for the
domain in which this object will be added. The parameter name must contain a fully qualified NIS+
name. The object members zo_name and zo_domain will be constructed from this name. This operation
will fail if the object already exists. This feature prevents the accidental addition of objects over another
object that has been added by another process.
The function
nis_remove() will remove the object with name name from the NIS+ namespace. The
client making this request must have the destroy access right for the domain in which this object resides.
If the named object is a link, the link is removed and not the object that it points to. If the parameter obj
is not NULL, it is assumed to point to a copy of the object being removed. In this case, if the object on the
server does not have the same object identifier as the object being passed, the operation will fail with the
NIS_NOTSAMEOBJ error. This feature allows the client to insure that it is removing the desired object.
The parameter name must contain a fully qualified NIS+ name.
The function
nis_modify() will modify the object named by name to the field values in the object
pointed to by obj. This object should contain a copy of the object from the name space that is being
modified. This operation will fail with the error NIS_NOTSAMEOBJ if the object identifier of the passed
object does not match that of the object being modified in the namespace.
Note: Normally the contents of the member zo_name in the nis_object structure would be constructed
from the name passed in the name parameter. However, if it is non-NULL the client library will use the
name in the zo_name member to perform a rename operation on the object. This name must not contain
any unquoted ‘.’(dot) characters. If these conditions are not met the operation will fail and return the
NIS_BADNAME error code.
Results
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 the call to
nis_freeresult(). 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)). Refer to nis_objects (3N)
for a description of the
nis_object structure.
The various ticks contain details of where the time 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.
dticks The time spent in the database backend. This time is measured from the time a database
call starts, until the result is returned. If the request results in multiple calls to the data-
base, this is the sum of all the time spent in those calls.
HP-UX 11i Version 2: September 2004 − 2 − Hewlett-Packard Company Section 3−−665