[ Previous | Next | Table of Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Communications, Volume 1
Used to search a table in the NIS+ namespace.
cc [ flag . . . ]
file. . . -lnsl [
library. . . ]
#include <rpcsvc/nis.h>
nis_result * nis_list(name, flags,
callback userdata);
nis_name name;
u_long flags;
int (*callback)( );
void userdata;
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.
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.
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.
- NIS_PATH
- When set, this variable is the search path used by nis_list( )
if the flag EXPAND_NAME is set.
- 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.
nis_add_entry, nis_first_entry, nis_local_directory, nis_lookup, nis_modify_entry, nis_next_entry, nis_perror,
nis_remove_entry, and nis_sperror.
Network Information Services+ and NIS+ Namespace and Structure in AIX 5L Version
5.1 Network Information Services (NIS and NIS+) Guide.
TCP/IP Protocols in AIX 5L Version 5.1
System Management Guide: Communications and Networks.
List of NIS and NIS+ Programming References and Remote Procedure Call (RPC) Overview for Programming in
AIX 5L Version 5.1 Communications Programming
Concepts.
[ Previous | Next | Table of Contents | Index |
Library Home |
Legal |
Search ]