Networking Services Library Functions nisnames(3NSL)
NAME
nisnames, nislookup, nisadd, nisremove, nismodify,
nisfreeresult - NIS] namespace functions
SYNOPSIS
cc [ flag ... ] file ... -lnsl [ library ... ]
#include
nisresult *nislookup(nisname name, uintt flags);
nisresult *nisadd(nisname name, nisobject *obj);
nisresult *nisremove(nisname name, nisobject *obj);
nisresult *nismodify(nisname name, nisobject *obj);
void nisfreeresult(nisresult *result);
DESCRIPTION
The NIS] namespace functions are used to locate and manipu-
late all NIS] objects except the NIS] entry objects. See
nisobjects(3NSL). To look up the NIS] entry objects within
a NIS] table, refer to nissubr(3NSL).
nislookup() resolves a NIS] name and returns a copy of that
object from a NIS] server. nisadd() and nisremove() add
and remove objects to the NIS] namespace, respectively.
nismodify() 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 func-
tions listed in nissubr(3NSL) should be used.
nisfreeresult() frees all memory associated with a
nisresult structure. This function must be called to free
the memory associated with a NIS] result. nislookup(),
nisadd(), nisremove(), and nismodify() all return a
pointer to a nisresult() structure which must be freed by
calling nisfreeresult() when you have finished using it. If
one or more of the objects returned in the structure need to
SunOS 5.11 Last change: 10 Nov 2005 1
Networking Services Library Functions nisnames(3NSL)
be retained, they can be copied with niscloneobject(3NSL).
See nissubr(3NSL).
nislookup() takes two parameters, the name of the object to
be resolved in name, and a flags parameter, flags, which is
defined below. The object name is expected to correspond to
the syntax of a non-indexed NIS] name . See
nistables(3NSL). The nislookup() 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 EXPANDNAME must be specified in the call. If
this flag is not specified, the function will fail with the
error NISBADNAME.
The flags parameter is constructed by logically ORing zero
or more flags from the following list.
FOLOWLINKS 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 process will iterate until the
either a object is found that is not a LINK
type object, or the library has followed 16
links.
HARDLOKUP 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 available. If the network connec-
tivity is impaired, this can be a rela-
tively long time.
NOCACHE 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.
MASTERONLY When specified, the client library will
bypass any object caches and any domain
replicas 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.
SunOS 5.11 Last change: 10 Nov 2005 2
Networking Services Library Functions nisnames(3NSL)
EXPANDNAME When specified, the client library will
attempt to expand a partially qualified name
by calling the function nisgetnames(),
which uses the environment variable
NISPATH. See nissubr(3NSL).
The status value may be translated to ASCI text using the
function nissperrno(). See niserror(3NSL).
On return, the objects array in the result will contain one
and possibly several objects that were resolved by the
request. If the FOLOWLINKS 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 nisadd() 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 zoname and zodomain 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 nisremove() 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 NUL, 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 identif-
ier as the object being passed, the operation will fail with
the NISNOTSAMEOBJ error. This feature allows the client to
insure that it is removing the desired object. The parame-
ter name must contain a fully qualified NIS] name.
The function nismodify() 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 NISNOTSAMEOBJ if the object identifier of
SunOS 5.11 Last change: 10 Nov 2005 3
Networking Services Library Functions nisnames(3NSL)
the passed object does not match that of the object being
modified in the namespace.
Normally the contents of the member zoname in the
nisobject 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 zoname member to
perform a rename operation on the object. This name must not
contain any unquoted `.'(dot) characters. If these condi-
tions are not met the operation will fail and return the
NISBADNAME error code.
You cannot modify the name of an object if that modification
would cause the object to reside in a different domain.
You cannot modify the schema of a table object.
Results
These functions return a pointer to a structure of type
nisresult:
struct nisresult {
niserror status;
struct {
uintt objectslen;
nisobject *objectsval;
} objects;
netobj cookie;
uint32t zticks;
uint32t dticks;
uint32t aticks;
uint32t 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 nissperrno(). See
niserror(3NSL).
The objects structure contains two members. objectsval is
an array of nisobject structures; objectslen is the number
of cells in the array. These objects will be freed by the
call to nisfreeresult(). If you need to keep a copy of one
or more objects, they can be copied with the function
niscloneobject() and freed with the function
nisdestroyobject(). See nisserver(3NSL). Refer to
SunOS 5.11 Last change: 10 Nov 2005 4
Networking Services Library Functions nisnames(3NSL)
nisobjects(3NSL) for a description of the nisobject
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.
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 database, this is
the sum of all the time spent in those calls.
aticks The time spent in any ``accelerators'' or caches.
This includes the time required to locate the
server needed to resolve the request.
cticks The total time spent in the request. This clock
starts when you enter the client library and
stops when a result is returned. By subtracting
the sum of the other ticks values from this value,
you can obtain the local overhead of generating a
NIS] request.
Subtracting the value in dticks from the value in zticks
will yield the time spent in the service code itself. Sub-
tracting the sum of the values in zticks and aticks from
the value in cticks will yield the time spent in the client
library itself. Note: all of the tick times are measured in
microseconds.
RETURN VALUES
The client library can return a variety of error returns and
diagnostics. The more salient ones are documented below.
NISUCES The request was successful.
NISUCES The request was successful, however
the object returned came from an
object cache and not directly from
SunOS 5.11 Last change: 10 Nov 2005 5
Networking Services Library Functions nisnames(3NSL)
the server. If you do not wish to see
objects from object caches you must
specify the flag NOCACHE when you
call the lookup function.
NISNOTFOUND The named object does not exist in
the namespace.
NISCACHEXPIRED The object returned came from an
object cache taht has expired. The
time to live value has gone to zero
and the object may have changed. If
the flag NOCACHE was passed to the
lookup function then the lookup func-
tion will retry the operation to get
an unexpired copy of the object.
NISNAMEUNREACHABLE A server for the directory of the
named object could not be reached.
This can occur when there is a net-
work partition or all servers have
crashed. See the HARDLOKUP flag.
NISUNKNOWNOBJ The object returned is of an unknown
type.
NISTRYAGAIN The server connected to was too busy
to handle your request. For the add,
remove, and modify operations this is
returned when either the master
server for a directory is unavail-
able, or it is in the process of
checkpointing its database. It can
also be returned when the server is
updating its internal state. In the
case of nislist(), NISTRYAGAIN is
returned if the client specifies a
callback and the server does not have
enough resources to handle the call-
back.
NISYSTEMEROR A generic system error occurred while
attempting the request. Most commonly
the server has crashed or the data-
base has become corrupted. Check the
syslog record for error messages from
SunOS 5.11 Last change: 10 Nov 2005 6
Networking Services Library Functions nisnames(3NSL)
the server.
NISNOTME A request was made to a server that
does not serve the name in question.
Normally this will not occur, however
if you are not using the built in
location mechanism for servers you
may see this if your mechanism is
broken.
NISNOMEMORY Generally a fatal result. It means
that the service ran out of heap
space.
NISNAMEXISTS An attempt was made to add a name
that already exists. To add the name,
first remove the existing name and
then add the new object or modify the
existing named object.
NISNOTMASTER An attempt was made to update the
database on a replica server.
NISINVALIDOBJ The object pointed to by obj is not a
valid NIS] object.
NISBADNAME The name passed to the function is
not a legal NIS] name.
NISLINKNAMEROR The name passed resolved to a LINK
type object and the contents of the
link pointed to an invalid name.
NISNOTSAMEOBJ An attempt to remove an object from
the namespace was aborted because the
object that would have been removed
was not the same object that was
passed in the request.
NISNOSUCHNAME This hard error indicates that the
named directory of the table object
does not exist. This occurs when the
server that should be the parent of
SunOS 5.11 Last change: 10 Nov 2005 7
Networking Services Library Functions nisnames(3NSL)
the server that serves the table,
does not know about the directory in
which the table resides.
NISNOSUCHTABLE The named table does not exist.
NISMODFAIL The attempted modification failed.
NISFOREIGNS The name could not be completely
resolved. When the name passed to the
function would resolve in a namespace
that is outside the NIS] name tree,
this error is returned with a NIS]
object of type DIRECTORY, which con-
tains the type of namespace and con-
tact information for a server within
that namespace.
NISRPCEROR This fatal error indicates the RPC
subsystem failed in some way. Gen-
erally there will be a syslog(3C)
message indicating why the RPC
request failed.
ENVIRONMENT VARIABLES
NISPATH If the flag EXPANDNAME is set, this variable is
the search path used by nislookup().
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
SEE ALSO
niserror(3NSL), nisobjects(3NSL), nisserver(3NSL),
nissubr(3NSL), nistables(3NSL), attributes(5)
SunOS 5.11 Last change: 10 Nov 2005 8
Networking Services Library Functions nisnames(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 9
|
