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

n
nis_subr(3N) nis_subr(3N)
NAME
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
SYNOPSIS
cc [ flag ... ] le...
-lnsl [ library. . . ]
#include <rpcsvc/nis.h>
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);
DESCRIPTION
These subroutines are provided to assist in the development of NIS+ applications. They provide several
useful operations on both NIS+ names and objects.
The first group, nis_leaf_of()
, nis_domain_of(), and nis_name_of() provide 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) characters 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 return null.
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 ter-
minated by a NULL pointer, and the memory associated 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 allocates 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(3N) 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
Section 3606 Hewlett-Packard Company 1 HP-UX 11i Version 1: September 2005