[ Next Article |
Previous Article |
Book Contents |
Library Home |
Legal |
Search ]
Communications Technical Reference, Volume 1
nis_lookup (NIS+ API)
Purpose
Used to resolve an NIS+ name and return a copy of that object
from an NIS+ server.
Syntax
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);
Description
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.
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_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.
Errors
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.
Environment
- NIS_PATH
- If the flag EXPAND_NAME is set, this variable is the search path used
by nis_lookup( ).
Related Information
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 Version 4.3 Network Information Services (NIS and NIS+) Guide.
TCP/IP
Protocols in AIX Version 4.3 System Management Guide: Communications and Networks.
List of NIS and NIS+ Programming References
and Remote Procedure Call (RPC) Overview for
Programming in AIX Version 4.3 Communications Programming Concepts.
[ Next Article |
Previous Article |
Book Contents |
Library Home |
Legal |
Search ]