Networking Services Library Functions nissubr(3NSL)
NAME
nissubr, nisleafof, nisnameof, nisdomainof,
nisgetnames, nisfreenames, nisdircmp, niscloneobject,
nisdestroyobject, nisprintobject - NIS] subroutines
SYNOPSIS
cc [ flag ... ] file ... -lnsl [ library ... ]
#include
nisname nisleafof(const nisname name);
nisname nisnameof(const nisname name);
nisname nisdomainof(const nisname name);
nisname *nisgetnames(const nisname name);
void nisfreenames(nisname *namelist);
namepos nisdircmp(const nisname n1, const nisname n2);
nisobject *niscloneobject(const nisobject *src, nisobject *dest);
void nisdestroyobject(nisobject *obj);
void nisprintobject(const nisobject *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, nisleafof(), nisdomainof(), and
nisnameof() provide the functions for parsing NIS] names.
nisleafof() 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.
SunOS 5.11 Last change: 10 Nov 2005 1
Networking Services Library Functions nissubr(3NSL)
nisdomainof() returns the name of the NIS] domain in which
an object resides. This name will always be a fully quali-
fied NIS] name and ends with a dot. By iteratively calling
nisleafof() and nisdomainof() it is possible to break a
NIS] name into its individual components.
nisnameof() 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
nisnameof() were passed a name bob.friends.foo.bar.baz,
then nisnameof() 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 func-
tion will return null.
nisgetnames() will return a list of candidate names for the
name passed in as name. If this name is not fully qualified,
nisgetnames() will generate a list of names using the
default NIS] directory search path, or the environment vari-
able NISPATH if it is set. The returned array of pointers
is terminated by a null pointer, and the memory associated
with this array should be freed by calling nisfreenames()
Though nisdircmp() 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 namepos. When the names passed
to this function are identical, the function returns a
value of SAMENAME. If the name n1 is a direct ancestor of
name n2, then this function returns the result HIGHERNAME.
Similarly, if the name n1 is a direct descendant of name n2,
then this function returns the result LOWERNAME. 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 NOTSEQUENTIAL. Finally, if either name
cannot be parsed as a legitimate name then this function
returns the value BADNAME.
The second set of functions, consisting of
niscloneobject() and nisdestroyobject(), are used for
manipulating objects. niscloneobject() 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 nisobjects(3NSL)
SunOS 5.11 Last change: 10 Nov 2005 2
Networking Services Library Functions nissubr(3NSL)
for a description of the nisobject structure.
nisdestroyobject() can be used to destroy an object
created by niscloneobject(). 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 niscloneobject(), then the object cannot be freed with
this function. Instead, the function
xdrfree(xdrnisobject,dest) must be used.
nisprintobject() prints out the contents of a NIS] object
structure on the standard output. Its primary use is for
debugging NIS] programs.
nisleafof(), nisnameof()and niscloneobject() return
their results as thread-specific data in multithreaded
applications.
ENVIRONMENT VARIABLES
NISPATH This variable overrides the default NIS] direc-
tory search path used by nisgetnames(). It con-
tains 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 directories between the default domain
and the global root that are at least two levels
deep. The default NIS] directory search path is
'$'.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level Safe
SEE ALSO
nisnames(3NSL), nisobjects(3NSL), nistables(3NSL), attri-
butes(5)
SunOS 5.11 Last change: 10 Nov 2005 3
Networking Services Library Functions nissubr(3NSL)
NOTES
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
http:/www.sun.com/directory/nisplus/transition.html.
SunOS 5.11 Last change: 10 Nov 2005 4
|
