Purpose
Used to search
a table in the NIS+ namespace.
Syntax
cc [ flag .
. . ] file. . . -lnsl [ library.
. . ]
nis_result
* nis_list(name, flags, callback userdata);
nis_name name;
u_long flags;
int (*callback)( );
void userdata;
Description
One of
a group of NIS+ APIs
that is used to search and modify NIS+ tables, nis_list(
) is used to search a table in the NIS+ namespace..
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:
[ colname=value,...],tablename
The
list function, nis_list( ), takes an indexed name as the value
for the name parameter. Here, the tablename
should be a fully qualified NIS+ name unless the EXPAND_NAME flag
is set. The second parameter, flags, defines
how the function will respond to various conditions. The value for
this parameter is created by logically OR ing together one
or more flags from the following list:
- FOLLOW_LINKS
- If the table specified in name resolves to
be a LINK type object, 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 NIS_NOTSEARCHABLE will
be returned.
- FOLLOW_PATH
- 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 conjunction with the ALL_RESULTS flag,
it specifies that the path should be followed regardless of the result
of the search. When used in conjunction with the FOLLOW_LINKS flag,
named tables in the path that resolve to links will be followed 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.
- HARD_LOOKUP
- 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 NIS_NOTFOUND).
Warning: Use the flag HARD_LOOKUP carefully
since it can cause the application to block indefinitely during a
network partition.
- ALL_RESULTS
- This flag can only be used in conjunction with FOLLOW_PATH and
a callback function. 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.
- NO_CACHE
- 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.
- MASTER_ONLY
- This flag is even stronger than NO_CACHE as 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 performance
penalties associated with contacting the master server directly on
large networks. When used in conjunction with the HARD_LOOKUP flag,
this will block the list operation until the master server is up and
available.
- EXPAND_NAME
- When specified, the client library will attempt to expand a partially
qualified name by calling nis_getnames( ), which uses the environment
variable NIS_PATH.
- RETURN_RESULT
- This flag is used to specify that a copy of the returning object
be returned in the nis_result structure if the operation was
successful.
The third parameter to nis_list( ), 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 NULL,
then all entries that match the search criteria are returned in the nis_result structure;
otherwise, this function 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 passed to callback function along with the returned entry
object. The client can use this pointer to pass state information
or other relevant data that the callback function might need to process
the entries.
Return Values
These
functions return a pointer to a structure of type nis_result:
struct nis_result {
nis_error status;
struct {
u_int objects_len;
nis_object * objects_val;
} objects;
netobj cookie;
u_long zticks;
u_long dticks;
u_long aticks;
u_long 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 nis_sperrno(
).
The objects structure contains two members: objects_val is
an array of nis_object structures; objects_len is
the number of cells in the array. These objects will be freed by a
call to nis_freeresult( ). If you need to keep a copy of one
or more objects, they can be copied with the function nis_clone_object(
) and freed with the function nis_destroy_object( ).
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 anNIS+ request.
Subtracting the value in dticks from
the value in zticks will yield the time spent
in the service code itself. Subtracting 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.
Errors
The client library
can return a variety of error returns and diagnostics. Following are
some of the more pertinent ones:
- NIS_BADATTRIBUTE
- 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.
- NIS_BADNAME
- The name passed to the function is not a legal NIS+ name.
- NIS_BADREQUEST
- A problem was detected in the request structure passed to the
client library.
- NIS_CACHEEXPIRED
- 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 NO_CACHE was passed to the lookup
function, the lookup function will retry the operation to get an unexpired
copy of the object.
- NIS_CBERROR
- 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.
- NIS_CBRESULTS
- Even though the request was successful, all of the entries have
been sent to your callback function and are thus not included in this
result.
- NIS_FOREIGNNS
- 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.
- NIS_INVALIDOBJ
- 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 (for example, binary or
text) than the associated column in the table.
- NIS_LINKNAMEERROR
- The name passed resolved to a LINK type object and the
contents of the object pointed to an invalid name.
- NIS_MODFAIL
- The attempted modification failed.
- NIS_NAMEEXISTS
- 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.
- NIS_NAMEUNREACHABLE
- 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 HARD_LOOKUP flag.
- NIS_NOCALLBACK
- The server was unable to contact the callback service on your
machine. This results in no data being returned.
- NIS_NOMEMORY
- Generally a fatal result. It means that the service ran out of
heap space.
- NIS_NOSUCHNAME
- 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.
- NIS_NOSUCHTABLE
- The named table does not exist.
- NIS_NOT_ME
- A request was made to a server that does not serve the given name.
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.
- NIS_NOTFOUND
- No entries in the table matched the search criteria. If the search
criteria was null (return all entries), then this result means that
the table is empty and may safely be removed by calling the nis_remove(
). If the FOLLOW_PATH flag was set, this error indicates
that none of the tables in the path contain entries that match the
search criteria.
- NIS_NOTMASTER
- 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/NIS_SHARED_DIRCACHE file
will need to have their cache managers restarted (use nis_cachemgr
-i to flush this cache).
- NIS_NOTSAMEOBJ
- 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.
- NIS_NOTSEARCHABLE
- The table name resolved to a NIS+ object that was
not searchable.
- NIS_PARTIAL
- This result is similar to NIS_NOTFOUND 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.
- NIS_RPCERROR
- This fatal error indicates the RPC subsystem failed in some way.
Generally there will be a syslog(3) message indicating why
the RPC request failed.
- NIS_S_NOTFOUND
- 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.
- NIS_S_SUCCESS
- Even though the request was successful, 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.
- NIS_SUCCESS
- The request was successful.
- NIS_SYSTEMERROR
- Some form of generic system error occurred while attempting the
request. Check the syslog(3) record for error messages from
the server.
- NIS_TOOMANYATTRS
- The search criteria passed to the server had more attributes than
the table had searchable columns.
- NIS_TRYAGAIN
- The server connected to was too busy to handle your request. add_entry(
), remove_entry( ), and modify_entry( ) return this
error when the master server is currently updating its internal state.
It can be returned to nis_list( ) when the function specifies
a callback and the server does not have the resources to handle callbacks.
- NIS_TYPEMISMATCH
- 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
- NIS_PATH
- When set, this variable is the search path used by nis_list(
) if the flag EXPAND_NAME is set.
Notes:
- The path used when the flag FOLLOW_PATH is specified is
the one present in the first table searched.
The path values in tables that are subsequently searched are ignored.
- It is legal to call functions that would access the nameservice
from within a list callback. However, calling a function that would
itself use a callback, or calling nis_list( ) with a callback
from within a list callback function, is not currently supported.