nis_subr(3NSL) Networking Services Library Functions nis_subr(3NSL)
nis_subr, nis_leaf_of, nis_name_of, nis_domain_of, nis_getnames,
nis_freenames, nis_dir_cmp, nis_clone_object, nis_destroy_object,
nis_print_object - NIS+ subroutines
cc [ flag ... ] file ... -lnsl [ library ... ]
nis_name nis_leaf_of(const nis_name name);
nis_name nis_name_of(const nis_name name);
nis_name nis_domain_of(const nis_name name);
nis_name *nis_getnames(const nis_name name);
void nis_freenames(nis_name *namelist);
name_pos nis_dir_cmp(const nis_name n1, const nis_name n2);
nis_object *nis_clone_object(const nis_object *src, nis_object *dest);
void nis_destroy_object(nis_object *obj);
void nis_print_object(const nis_object *obj);
These subroutines are provided to assist in the development of NIS+
applications. They provide several useful operations on both NIS+ names
The first group, nis_leaf_of(), nis_domain_of(), and nis_name_of() pro‐
vide the functions for parsing NIS+ names. nis_leaf_of() will return
the first label in an NIS+ name. It takes into account the double quote
character `"' which can be used to protect embedded `.' (dot) charac‐
ters in object names. Note that the name returned will never have a
trailing dot character. If passed the global root directory name ".",
it will return the null string.
nis_domain_of() returns the name of the NIS+ domain in which an object
resides. This name will always be a fully qualified NIS+ name and ends
with a dot. By iteratively calling nis_leaf_of() and nis_domain_of()
it is possible to break a NIS+ name into its individual components.
nis_name_of() is used to extract the unique part of a NIS+ name. This
function removes from the tail portion of the name all labels that are
in common with the local domain. Thus if a machine were in domain
foo.bar.baz. and nis_name_of() were passed a name
bob.friends.foo.bar.baz, then nis_name_of() would return the unique
part, bob.friends. If the name passed to this function is not in
either the local domain or one of its children, this function will
nis_getnames() will return a list of candidate names for the name
passed in as name. If this name is not fully qualified, nis_getnames()
will generate a list of names using the default NIS+ directory search
path, or the environment variable NIS_PATH if it is set. The returned
array of pointers is terminated by a null pointer, and the memory asso‐
ciated with this array should be freed by calling nis_freenames()
Though nis_dir_cmp() can be used to compare any two NIS+ names, it is
used primarily to compare domain names. This comparison is done in a
case independent fashion, and the results are an enum of type
name_pos. When the names passed to this function are identical, the
function returns a value of SAME_NAME. If the name n1 is a direct
ancestor of name n2, then this function returns the result HIGHER_NAME.
Similarly, if the name n1 is a direct descendant of name n2, then this
function returns the result LOWER_NAME. When the name n1 is neither a
direct ancestor nor a direct descendant of n2, as it would be if the
two names were siblings in separate portions of the namespace, then
this function returns the result NOT_SEQUENTIAL. Finally, if either
name cannot be parsed as a legitimate name then this function returns
the value BAD_NAME.
The second set of functions, consisting of nis_clone_object() and
nis_destroy_object(), are used for manipulating objects.
nis_clone_object() creates an exact duplicate of the NIS+ object src.
If the value of dest is non-null, it creates the clone of the object
into this object structure and allocate the necessary memory for the
variable length arrays. If this parameter is null, a pointer to the
cloned object is returned. Refer to nis_objects(3NSL) for a description
of the nis_object structure.
nis_destroy_object() can be used to destroy an object created by
nis_clone_object(). This will free up all memory associated with the
object and free the pointer passed. If the object was cloned into an
array using the dest parameter to nis_clone_object(), then the object
cannot be freed with this function. Instead, the function
xdr_free(xdr_nis_object,dest) must be used.
nis_print_object() prints out the contents of a NIS+ object structure
on the standard output. Its primary use is for debugging NIS+ programs.
nis_leaf_of(), nis_name_of()and nis_clone_object() return their results
as thread-specific data in multithreaded applications.
NIS_PATH This variable overrides the default NIS+ directory search
path used by nis_getnames(). It contains an ordered list of
directories separated by ':' (colon) characters. The '$'
(dollar sign) character is treated specially. Directory
names that end in '$' have the default domain appended to
them, and a '$' by itself is replaced by the list of direc‐
tories between the default domain and the global root that
are at least two levels deep. The default NIS+ directory
search path is '$'.
See attributes(5) for descriptions of the following attributes:
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
│MT-Level │Safe │
nis_names(3NSL), nis_objects(3NSL), nis_tables(3NSL), attributes(5)
NIS+ might not be supported in future releases of the Solaris operating
system. Tools to aid the migration from NIS+ to LDAP are available in
the current Solaris release. For more information, visit
SunOS 5.11 10 Nov 2005 nis_subr(3NSL)