Networking Services Library Functions nistables(3NSL)
NAME
nistables, nislist, nisaddentry, nisremoveentry,
nismodifyentry, nisfirstentry, nisnextentry - NIS]
table functions
SYNOPSIS
cc [ flag ... ] file ... -lnsl [ library ... ]
#include
nisresult *nislist(nisname name, uinttflags,
int (*callback)(nisname tablename,nisobject *object,
void *userdata), void *userdata);
nisresult *nisaddentry(nisname tablename, nisobject *object,
uintt flags);
nisresult *nisremoveentry(nisname name, nisobject *object,
uintt flags);
nisresult *nismodifyentry(nisname name, nisobject *object,
uintt flags);
nisresult *nisfirstentry(nisname tablename);
nisresult *nisnextentry(nisname tablename, netobj *cookie);
void nisfreeresult(nisresult *result);
DESCRIPTION
Use the NIS] table functions to search and modify NIS]
tables. nislist() is used to search a table in the NIS]
namespace. nisfirstentry() and nisnextentry() are used
to enumerate a table one entry at a time. nisaddentry(),
nisremoveentry(), and nismodifyentry() are used to
change the information stored in a table. nisfreeresult()
is used to free the memory associated with the nisresult
structure.
Entries within a table are named by NIS] indexed names. An
indexed name is a compound name that is composed of a search
criteria and a simple NIS] name that identifies a table
object. A search criteria is a series of column names and
their associated values enclosed in bracket '[]' characters.
Indexed names have the following form:
SunOS 5.11 Last change: 10 Nov 2005 1
Networking Services Library Functions nistables(3NSL)
[ colname=value, ... ], tablename
The list function, nislist(), takes an indexed name as the
value for the name parameter. Here, the tablename should be
a fully qualified NIS] name unless the EXPANDNAME flag
(described below) is set. The second parameter, flags,
defines how the function will respond to various conditions.
The value for this parameter is created by logically ORing
together one or more flags from the following list.
FOLOWLINKS If the table specified in name resolves to
be a LINK type object (see
nisobjects(3NSL)), this flag specifies
that the client library follow that link
and do the search at that object. If this
flag is not set and the name resolves to a
link, the error NISNOTSEARCHABLE will be
returned.
FOLOWPATH This flag specifies that if the entry is
not found within this table, the list
operation should follow the path specified
in the table object. When used in conjunc-
tion with the ALRESULTS flag below, it
specifies that the path should be followed
regardless of the result of the search.
When used in conjunction with the
FOLOWLINKS flag above, named tables in
the path that resolve to links will be fol-
lowed until the table they point to is
located. If a table in the path is not
reachable because no server that serves it
is available, the result of the operation
will be either a "soft" success or a "soft"
failure to indicate that not all tables in
the path could be searched. If a name in
the path names is either an invalid or
non-existent object then it is silently
ignored.
HARDLOKUP This flag specifies that the operation
should continue trying to contact a server
of the named table until a definitive
result is returned (such as NISNOTFOUND).
ALRESULTS This flag can only be used in conjunction
with FOLOWPATH and a callback function.
SunOS 5.11 Last change: 10 Nov 2005 2
Networking Services Library Functions nistables(3NSL)
When specified, it forces all of the tables
in the path to be searched. If name does
not specify a search criteria (imply that
all entries are to be returned), then this
flag will cause all of the entries in all
of the tables in the path to be returned.
NOCACHE This flag specifies that the client library
should bypass any client object caches and
get its information directly from either
the master server or a replica server for
the named table.
MASTERONLY This flag is even stronger than NOCACHE in
that it specifies that the client library
should only get its information from the
master server for a particular table. This
guarantees that the information will be up
to date. However, there may be severe per-
formance penalties associated with contact-
ing the master server directly on large
networks. When used in conjunction with the
HARDLOKUP flag, this will block the list
operation until the master server is up
and available.
EXPANDNAME When specified, the client library will
attempt to expand a partially qualified
name by calling nisgetnames(), which uses
the environment variable NISPATH. See
nislocalnames(3NSL).
RETURNRESULT This flag is used to specify that a copy of
the returning object be returned in the
nisresult structure if the operation was
successful.
The third parameter to nislist(), callback, is an optional
pointer to a function that will process the ENTRY type
objects that are returned from the search. If this pointer
is NUL, then all entries that match the search criteria are
returned in the nisresult structure, otherwise this func-
tion will be called once for each entry returned. When
called, this function should return 0 when additional
objects are desired and 1 when it no longer wishes to see
any more objects. The fourth parameter, userdata, is simply
SunOS 5.11 Last change: 10 Nov 2005 3
Networking Services Library Functions nistables(3NSL)
passed to callback function along with the returned entry
object. The client can use this pointer to pass state infor-
mation or other relevant data that the callback function
might need to process the entries.
The nislist() function is not MT-Safe with callbacks.
nisaddentry() will add the NIS] object to the NIS]
tablename. The flags parameter is used to specify the
failure semantics for the add operation. The default (flags
equal 0) is to fail if the entry being added already exists
in the table. The ADOVERWRITE flag may be used to specify
that existing object is to be overwritten if it exists, (a
modify operation) or added if it does not exist. With the
ADOVERWRITE flag, this function will fail with the error
NISPERMISION if the existing object does not allow modify
privileges to the client.
If the flag RETURNRESULT has been specified, the server
will return a copy of the resulting object if the operation
was successful.
nisremoveentry() removes the identified entry from the
table or a set of entries identified by tablename. If the
parameter object is non-null, it is presumed to point to a
cached copy of the entry. When the removal is attempted, and
the object that would be removed is not the same as the
cached object pointed to by object then the operation will
fail with an NISNOTSAMEOBJ error. If an object is passed
with this function, the search criteria in name is optional
as it can be constructed from the values within the entry.
However, if no object is present, the search criteria must
be included in the name parameter. If the flags variable is
null, and the search criteria does not uniquely identify an
entry, the NISNOTUNIQUE error is returned and the operation
is aborted. If the flag parameter REMULTIPLE is passed,
and if remove permission is allowed for each of these
objects, then all objects that match the search criteria
will be removed. Note that a null search criteria and the
REMULTIPLE flag will remove all entries in a table.
nismodifyentry() modifies an object identified by name.
The parameter object should point to an entry with the
ENMODIFIED flag set in each column that contains new infor-
mation.
SunOS 5.11 Last change: 10 Nov 2005 4
Networking Services Library Functions nistables(3NSL)
The owner, group, and access rights of an entry are modified
by placing the modified information into the respective
fields of the parameter, object: zoowner, zogroup, and
zoaccess.
These columns will replace their counterparts in the entry
that is stored in the table. The entry passed must have the
same number of columns, same type, and valid data in the
modified columns for this operation to succeed.
If the flags parameter contains the flag MODSAMEOBJ then
the object pointed to by object is assumed to be a cached
copy of the original object. If the OID of the object passed
is different than the OID of the object the server fetches,
then the operation fails with the NISNOTSAMEOBJ error. This
can be used to implement a simple read-modify-write protocol
which will fail if the object is modified before the client
can write the object back.
If the flag RETURNRESULT has been specified, the server
will return a copy of the resulting object if the operation
was successful.
nisfirstentry() fetches entries from a table one at a
time. This mode of operation is extremely inefficient and
callbacks should be used instead wherever possible. The
table containing the entries of interest is identified by
name. If a search criteria is present in name it is ignored.
The value of cookie within the nisresult structure must be
copied by the caller into local storage and passed as an
argument to nisnextentry().
nisnextentry() retrieves the "next" entry from a table
specified by tablename. The order in which entries are
returned is not guaranteed. Further, should an update occur
in the table between client calls to nisnextentry() there
is no guarantee that an entry that is added or modified will
be seen by the client. Should an entry be removed from the
table that would have been the "next" entry returned, the
error NISCHAINBROKEN is returned instead.
The path used when the flag FOLOWPATH is specified, is the
one present in the first table searched. The path values in
tables that are subsequently searched are ignored.
SunOS 5.11 Last change: 10 Nov 2005 5
Networking Services Library Functions nistables(3NSL)
It is legal to call functions that would access the nameser-
vice from within a list callback. However, calling a func-
tion that would itself use a callback, or calling
nislist() with a callback from within a list callback func-
tion is not currently supported.
There are currently no known methods for nisfirstentry()
and nisnextentry() to get their answers from only the mas-
ter server.
The nislist() function is not MT-Safe with callbacks.
nislist() callbacks are serialized. A call to nislist()
with a callback from within nislist() will deadlock.
nislist() with a callback cannot be called from an rpc
server. See rpcsvccalls(3NSL). Otherwise, this function
is MT-Safe.
RETURN VALUES
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 a call
to nisfreeresult(). See nisnames(3NSL). 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).
SunOS 5.11 Last change: 10 Nov 2005 6
Networking Services Library Functions nistables(3NSL)
The various ticks contain details of where the time, in
microseconds, 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 a 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.
ERORS
The client library can return a variety of error returns and
diagnostics. The more salient ones are documented below.
NISBADATRIBUTE The name of an attribute did not
match up with a named column in the
table, or the attribute did not have
an associated value.
NISBADNAME The name passed to the function is
not a legal NIS] name.
SunOS 5.11 Last change: 10 Nov 2005 7
Networking Services Library Functions nistables(3NSL)
NISBADREQUEST A problem was detected in the request
structure passed to the client
library.
NISCACHEXPIRED The entry returned came from an
object cache that has expired. This
means that the time to live value has
gone to zero and the entry may have
changed. If the flag NOCACHE was
passed to the lookup function then
the lookup function will retry the
operation to get an unexpired copy of
the object.
NISCBEROR An RPC error occurred on the server
while it was calling back to the
client. The transaction was aborted
at that time and any unsent data was
discarded.
NISCBRESULTS Even though the request was success-
ful, all of the entries have been
sent to your callback function and
are thus not included in this result.
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. The
returned object contains the type of
namespace and contact information for
a server within that namespace.
NISINVALIDOBJ The object pointed to by object is
not a valid NIS] entry object for the
given table. This could occur if it
had a mismatched number of columns,
or a different data type than the
associated column in the table, for
example, binary or text.
NISLINKNAMEROR The name passed resolved to a LINK
type object and the contents of the
object pointed to an invalid name.
SunOS 5.11 Last change: 10 Nov 2005 8
Networking Services Library Functions nistables(3NSL)
NISMODFAIL The attempted modification failed for
some reason.
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 name or modify the
existing named object.
NISNAMEUNREACHABLE This soft error indicates that a
server for the desired directory of
the named table object could not be
reached. This can occur when there
is a network partition or the server
has crashed. Attempting the operation
again may succeed. See the
HARDLOKUP flag.
NISNOCALBACK The server was unable to contact the
callback service on your machine.
This results in no data being
returned.
NISNOMEMORY Generally a fatal result. It means
that the service ran out of heap
space.
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
the server that serves the table,
does not know about the directory in
which the table resides.
NISNOSUCHTABLE The named table does not exist.
NISNOTME A request was made to a server that
does not serve the given name. Nor-
mally this will not occur, however if
you are not using the built in loca-
tion mechanism for servers, you may
see this if your mechanism is broken.
SunOS 5.11 Last change: 10 Nov 2005 9
Networking Services Library Functions nistables(3NSL)
NISNOTFOUND No entries in the table matched the
search criteria. If the search cri-
teria was null (return all entries)
then this result means that the table
is empty and may safely be removed by
calling the nisremove().
If the FOLOWPATH flag was set,
this error indicates that none of the
tables in the path contain entries
that match the search criteria.
NISNOTMASTER A change request was made to a server
that serves the name, but it is not
the master server. This can occur
when a directory object changes and
it specifies a new master server.
Clients that have cached copies of
the directory object in the
/var/nis/NISHAREDIRCACHE file
will need to have their cache
managers restarted to flush this
cache. Use niscachemgr -i.
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.
NISNOTSEARCHABLE The table name resolved to a NIS]
object that was not searchable.
NISPARTIAL This result is similar to
NISNOTFOUND except that it means the
request succeeded but resolved to
zero entries. When this occurs, the
server returns a copy of the table
object instead of an entry so that
the client may then process the path
or implement some other local policy.
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.
SunOS 5.11 Last change: 10 Nov 2005 10
Networking Services Library Functions nistables(3NSL)
NISNOTFOUND The named entry does not exist in the
table, however not all tables in the
path could be searched, so the entry
may exist in one of those tables.
NISUCES Even though the request was success-
ful, a table in the search path was
not able to be searched, so the
result may not be the same as the one
you would have received if that table
had been accessible.
NISUCES The request was successful.
NISYSTEMEROR Some form of generic system error
occurred while attempting the
request. Check the syslog(3C) record
for error messages from the server.
NISTOMANYATRS The search criteria passed to the
server had more attributes than the
table had searchable columns.
NISTRYAGAIN The server connected to was too busy
to handle your request. addentry(),
removeentry(), and modifyentry()
return this error when the master
server is currently updating its
internal state. It can be returned
to nislist() when the function
specifies a callback and the server
does not have the resources to handle
callbacks.
NISTYPEMISMATCH An attempt was made to add or modify
an entry in a table, and the entry
passed was of a different type than
the table.
ENVIRONMENT VARIABLES
NISPATH When set, this variable is the search path used
by nislist() if the flag EXPANDNAME is set.
SunOS 5.11 Last change: 10 Nov 2005 11
Networking Services Library Functions nistables(3NSL)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe with exceptions
SEE ALSO
niscat(1), niserror(1), nismatch(1), niscachemgr(1M),
niscloneobject(3NSL), n, nisdestroyobject(3NSL),
niserror(3NSL), nisgetnames(3NSL), nislocalnames(3NSL),
nisnames(3NSL), nisobjects(3NSL), nisserver(3NSL),
rpcsvccalls(3NSL), syslog(3C), attributes(5)
WARNINGS
Use the flag HARDLOKUP carefully since it can cause the
application to block indefinitely during a network parti-
tion.
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 12
|
