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

n
nis_names(3N) nis_names(3N)
NAME
nis_names, nis_lookup, nis_add, nis_remove, nis_modify, nis_freeresult - NIS+ namespace functions
SYNOPSIS
cc [ flag ... ] file...
-lnsl [ library. . . ]
#include <rpcsvc/nis.h>
nis_result *nis_lookup(const nis_name
name, const u_long flags
);
nis_result *nis_add(const nis_name
name, const nis_object *obj);
nis_result *nis_remove(const nis_name
name, const nis_object *obj
);
nis_result *nis_modify(const nis_name
name, const nis_object *obj
);
void nis_freeresult(nis_result *
result);
DESCRIPTION
These functions are used to locate and manipulate all NIS+ objects (see nis_objects(3N)) except the NIS+
entry objects. To look up the NIS+ entry objects within a NIS+ table, refer to nis_subr(3N).
nis_lookup() resolves a NIS+ name and returns a copy of that object from a NIS+ server.
nis_add() and nis_remove() add and remove objects to the NIS+ namespace, respectively.
nis_modify() can change specific attributes of an object that already exists in the namespace.
These functions should be used only with names that refer to an NIS+ Directory, NIS+ Table, NIS+ Group,
or NIS+ Private object. If a name refers to an NIS+ entry object, the functions listed in nis_subr(3N)
should be used.
nis_freeresult() frees all memory associated with a
nis_result structure. This function must
be called to free the memory associated with a NIS+ result.
nis_lookup() , nis_add(),
nis_remove() , and nis_modify() all return a pointer to a nis_result structure which must be
freed by calling
nis_freeresult()
when you have finished using it. If one or more of the objects
returned in the structure need to be retained, they can be copied with nis_clone_object(3N) (see
nis_subr(3N)).
nis_lookup() takes two parameters, the name of the object to be resolved in name, and a flags param-
eter, flags, which is defined below. The object name is expected to correspond to the syntax of a non-
indexed NIS+ name (see nis_tables(3N)). The
nis_lookup() function is the only function from this
group that can use a non-fully qualified name. If the parameter name is not a fully qualified name, then
the flag
EXPAND_NAME must be specified in the call. If this flag is not specified, the function will fail with
the error NIS_BADNAME.
The flags parameter is constructed by logically ORing zero or more flags from the following list.
FOLLOW_LINKS When specified, the client library will ‘‘follow’’ links by issuing another NIS+ lookup
call for the object named by the link. If the linked object is itself a link, then this pro-
cess will iterate until the either a object is found that is not a LINK type object, or the
library has followed 16 links.
HARD_LOOKUP When specified, the client library will retry the lookup until it is answered by a server.
Using this flag will cause the library to block until at least one NIS+ server is avail-
able. If the network connectivity is impaired, this can be a relatively long time.
NO_CACHE When specified, the client library will bypass any object caches and will get the object
from either the master NIS+ server or one of its replicas.
MASTER_ONLY When specified, the client library will bypass any object caches and any domain repli-
cas and fetch the object from the NIS+ master server for the object’s domain. This
insures that the object returned is up to date at the cost of a possible performance
degradation and failure if the master server is unavailable or physically distant.
EXPAND_NAME When specified, the client library will attempt to expand a partially qualified name by
calling the function
nis_getnames() (see nis_subr(3N)) which uses the environ-
ment variable NIS_PATH.
The status value may be translated to ascii text using the function nis_sperrno() (see nis_error(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
HP-UX 11i Version 1: September 2005 − 1 − Hewlett-Packard Company Section 3−−593