[ Previous | Next | Table of Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Communications, Volume 1
Used to resolve an NIS+ name and return a copy of that object from an NIS+
server.
cc [ flag . . . ]
file. . . -lnsl [
library. . . ]
#include <rpcsvc/nis.h>
nis_result * nis_lookup(nis_name name, u_long flags);
void nis_freeresult(nis_result * result);
One of a group of NIS+ APIs that is used to locate and manipulate all NIS+
objects except the NIS+ entry objects, nis_lookup( ) resolves an
NIS+ name and returns a copy of that object from an NIS+ server.
This function 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 functions listed in
nis_subr(3N) should be used.
nis_lookup returns a pointer to a nis_result
structure that must be freed by calling
nis_freeresult( ) when you have finished using it. If one or
more of the objects returned in the structure need to be retained, they can be
copied with nis_clone_object(3N).
nis_lookup( ) takes two parameters, the name of the object to be
resolved in name, and a flags parameter,
flags. The object name is expected to correspond
to the syntax of a non-indexed NIS+ name. The nis_lookup( )
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
EXPAND_NAME must be specified in the call. If
this flag is not specified, the function will fail with the error
NIS+BADNAME.
The flags parameter is constructed by logically
OR ing zero or more flags from the following list:
- EXPAND_NAME
- When specified, the client library will attempt to expand a partially
qualified name by calling the function nis_getnames( ), which uses
the environment variable nis_path.
- FOLLOW_LINKS
- 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 either an object is
found that is not a link type object, or the library has followed
16 links.
- HARD_LOOKUP
- 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
connectivity is impaired, this can be a relatively long time.
- MASTER_ONLY
- 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.
- NO_CACHE
- 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.
The status value may be translated to ascii text using the function
nis_sperrno( ).
On return, the objects array in the result will
contain one and possibly several objects that were resolved by the
request. If the FOLLOW_LINKS 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.
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_lenis 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 an NIS+ 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_BADNAME
- The name passed to the function is not a legal NIS+
name.
- NIS_CACHEEXPIRED
- The object 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_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 obj is not a valid
NIS+ object.
- 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
- A server for the directory of the named object could not be
reached. This can occur when there is a network partition or all the
server s have crashed. Attempting the operation again may
succeed. See the HARD_LOOKUP
flag.
- 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
- The named object does not exist in the namespace.
- NIS_NOTMASTER
- An attempt was made to update the database on a replica server.
- 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_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_SUCCESS
- The request was successful; however, the object returned came from an
object cache and not directly from the server. If you want to see
objects from object caches, you must specify the flag NO_CACHE when
you call the lookup function.
- NIS_SUCCESS
- The request was successful.
- NIS_SYSTEMERROR
- A generic system error occurred while attempting the request. Most
commonly the server has crashed or the database has become corrupted.
Check the syslog record for error messages from the server.
- NIS_TRYAGAIN
- 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 unavailable or it is in the process of
checkpointing its database. It can also be returned when the server is
updating its internal state or, in the case of nis_list( ), if the
client specifies a callback and the server does not have the resources to
handle callbacks.
- NIS_UNKNOWNOBJ
- The object returned is of an unknown type.
- NIS_PATH
- If the flag EXPAND_NAME is set, this variable is the search
path used by nis_lookup( ).
nis_add_entry, nis_first_entry, nis_list,
nis_local_directory, 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 ]