NETWORK INFO SVCE CLIENT I'FACE(3n,L) NETWORK INFO SVCE CLIENT I'FACE(3n,L)
-------------------------------------------------------------------------------
Network Information Service Client Interface
PURPOSE
Provides system information for networked NIS host machines.
LIBRARY
Internet Library (libc.a)
SYNTAX
# include <rpcsvc/ypclnt.h>
DESCRIPTION
The IBM AIX Network File System NIS client interface is composed of the library
functions used by the network information service to look up and return system
information in a network that has the network information service installed.
The network information service (NIS) is a distributed network lookup service
that provides system information, such as user passwords and host names, to
other machines running NIS. Read-only NIS data bases can be maintained on
multiple nodes in a network of machines. Other network machines function as
NIS clients by requesting information from the NIS data bases. See the section
on network information service in Managing the AIX Operating System for more
detailed information.
The NIS client interface handles client requests through the Remote Procedure
Call (RPC) facility. RPC is a paradigm for interprocess communication that
allows one process to call another process to execute functions in a remote
environment. The input and output to NIS remote procedure calls are described
using the External Data Representation (XDR) specification for representing
basic data types in a uniform format. The XDR specification establishes
standard representations for data types so that they can be transferred among
machines without being dependent on machine type or architecture. See "Remote
Procedure Call (RPC)" for more information on RPC, and "XDR (External Data
Representation)" for more information on XDR.
How NIS Works
When NIS is configured into a network, the person who manages the system
selects one server to be the NIS master server for a set of networked machines,
and builds the master NIS data base on this server. After the master NIS data
base is built, the NIS lookup service daemon, ypserv, is started. The master
NIS data base is propagated, or replicated, to a number of other servers in the
network that are designated as NIS slave servers. The ypserv daemons are
started on these servers.
Processed Nov. 7, 1990 NETWORK INFORMATION SERVICE CLIENT INTERFACE(3n,L) 1
NETWORK INFO SVCE CLIENT I'FACE(3n,L) NETWORK INFO SVCE CLIENT I'FACE(3n,L)
When NIS clients request system information, such as a host name, that
information may reside on a remote NIS server, which means they are making a
remote procedure call. The remote procedure call is sent to a ypserv daemon on
one of the NIS servers. The ypserv daemon looks up the information in its
local NIS data base and returns it to the client. See AIX Operating System
Commands Reference and Managing the AIX Operating System for more information
on the ypserv daemon.
NIS Maps
Network system information is stored in NIS maps. Each map contains data sets
stored as keys and their associated values. The keys identify the names of
such system information as hosts, passwords, and user IDs. For example, the
hosts map contains the names and Internet addresses for all machines in the
network. The host names are the keys and the Internet addresses are the
values. The NIS lookup service matches the keys in the map to the name of the
item requested by the client (the input string to the item) in order to return
the associated value data to the client.
Each NIS map has a name that programs must use to access the data in the map.
In addition, programs requesting information must know the format of the data
in the NIS map. The format of the data in default NIS maps matches the format
of the ASCII files used as input for the maps.
NIS maps are grouped by NIS domain. A NIS domain refers collectively to a
designated group of hosts. Maps are stored in a subdirectory of /etc/yp that
corresponds to the appropriate domain. For example, the NIS maps for hosts in
the publications domain are stored in /etc/yp/publications on the NIS servers.
To find the correct map, the ypserv daemon uses the publications domain name
when calling map lookup functions.
NIS CLIENT INTERFACE ROUTINES
The NIS client interface is composed of the library functions used by the
ypserv daemon to look up information and to return it to the client. NIS uses
matching and enumeration routines to get information from its data bases and
return it to the clients. The system calls and parameters that are used for
these functions are discussed in the following sections.
It is important to note that NIS clients must be bound to a NIS server that
services the appropriate domain in order to use NIS services. When a client
requests information, the lookup processes call the ypbind daemon to bind the
client to a NIS server that can service the request. It is also possible to
directly bind a client with a yp_bind routine. This is useful for programs
that use backup strategies for instances when NIS is not available. For that
reason, the yp_bind routine (and the contrasting yp_unbind routine) are listed
at the end of this section.
A NOTE ABOUT PARAMETERS: Memory is allocated to the NIS client interface
routines using the malloc system call and can be freed if the user code has no
continuing need for it.
Processed Nov. 7, 1990 NETWORK INFORMATION SERVICE CLIENT INTERFACE(3n,L) 2
NETWORK INFO SVCE CLIENT I'FACE(3n,L) NETWORK INFO SVCE CLIENT I'FACE(3n,L)
Parameters with the prefix in are input parameters. The values of the indomain
and inmap parameters cannot be null but must be null-terminated.
Parameters with the prefix out are output parameters. Output parameters of the
char ** type are addresses of uninitialized character pointers. The outkey and
outval parameters cause 2 extra bytes of memory to be allocated at the end that
contain new-line escape characters or the NULL value. The 2 bytes are not
reflected in the outkeylen and outvallen parameter values.
String parameters that are accompanied by a count parameter cannot be null.
They can point to null strings if the count parameter specifies it. Counted
strings do not have to be null-terminated.
ENUMERATING MAP VALUES:
yp_first (indomain, inmap, outkey, outkeylen, outval, outvallen)
char *indomain;
char *inmap;
char **outkey;
int *outkeylen;
char **outval;
int *outvallen;
yp_next (indomain, inmap, inkey, inkeylen, outkey, outkeylen,
outval, outvallen)
char *indomain;
char *inmap;
char *inkey
int inkeylen
char **outkey;
int *outkeylen;
char **outval;
int *outvallen;
The yp_first routine returns the first value from the map it associates
with the named key.
The yp_next routine returns each subsequent value it finds in the named
map until it reaches the end of the list.
The indomain and inmap parameters point to the names of the domain and
map used as input to the system call.
In the yp_first routine the inkey parameter is not needed since the value
returned is considered the first key.
The yp_next routine must be preceded by an initial yp_first call. Use
the outkey value returned from the initial yp_first as the value of the
inkey parameter for yp_next. The inkey values for subsequent calls are
retrieved as the nth + second key-value pair. That is, each time the
routine returns a key-value pair, the outkey value returned becomes the
value to use as the next inkey parameter.
Processed Nov. 7, 1990 NETWORK INFORMATION SERVICE CLIENT INTERFACE(3n,L) 3
NETWORK INFO SVCE CLIENT I'FACE(3n,L) NETWORK INFO SVCE CLIENT I'FACE(3n,L)
The inkeylen parameter is the length, in bytes, of the string inkey.
The outval parameter is an uninitialized pointer to a buffer where the
values associated with the key are placed. The outvallen parameter is
the length, in bytes, of the string pointed to by outval.
The concepts of first and next depend on the structure of the NIS map
being processed. The routines do not retrieve the information in a
specific order, such as the lexical order from the original data base
information files or the numerical sorting order of the keys, values, or
key-value pairs. They do show every entry in the NIS map if the yp_first
function is called on a specific map with yp_next called repeatedly. The
process returns the message "NISERR_NOMORE" to the user to indicate that
every entry in the NIS map has been seen once. If the same sequence of
operations is performed on the same map at the same server, the entries
are seen in the same order.
Note: If a server operates under a heavy load or fails, the domain can
become unbound and then bound again while a client is running. If
it binds itself to a different server, it can cause entries to be
seen twice or not be seen at all. The domain rebinds itself to
protect the enumeration process from being interrupted before it
completes. You can avoid this situation by returning all of the
keys and values with the following yp_all routine.
yp_all (indomain, inmap, incallback)
char *indomain;
char *inmap;
struct ypall_callback incallback {
int (* foreach) ();
char *data;
};
foreach (instatus, inkey, inkeylen, inval, invallen, indata)
int instatus;
char *inkey;
int inkeylen;
char *inval;
int invalllen;
char *indata;
The yp_all routine transfers all of the key-value pairs from the NIS
server to the client as the entire map. It uses TCP (rather than UDP) to
transport the data. The entire transaction takes places as a single
remote procedure call and response function.
The indomain and inmap parameters point to the names of the domain and
map used as input to the system call.
Processed Nov. 7, 1990 NETWORK INFORMATION SERVICE CLIENT INTERFACE(3n,L) 4
NETWORK INFO SVCE CLIENT I'FACE(3n,L) NETWORK INFO SVCE CLIENT I'FACE(3n,L)
The instatus parameter of the foreach routine holds a return status value
of the form "NIS_TRUE" or an error code. The error codes are defined in
the <rpcsvc/yp_prot.h> header file.
The inkey parameter points to memory that is private to the yp_all
function and is overwritten when each new key-value pair arrives. The
foreach function can use the contents of the memory but does not own the
memory itself. Key and value objects presented to foreach look exactly
like they do in the server's map. Objects not terminated by NEWLINE or
NULL in the server's map are not terminated by NEWLINE or NULL in the
client's map.
The indata parameter holds the contents of the incallback->data element
passed to the yp_all routine. The data element shares state information
between the foreach function and the mainline code. It is an optional
parameter because no part of the NIS client package inspects its
contents.
Since the foreach function is a Boolean, it returns 0 (zero) to indicate
that it wants to be called again for additional received key-value pairs.
It returns a nonzero value to stop the flow of key-value pairs. If
foreach returns a nonzero value, it is not called again, and yp_all
returns a value of 0 (zero).
WORKING WITH DOMAINS AND MAPS:
yp_get_default_domain (outdomain)
char **outdomain;
NIS lookup calls require a map name and a domain name. The client
processes can get the default domain of the node by calling the
yp_get_default_domain routine and using the value returned by the
outdomain parameter as the input domain (indomain) parameter for its NIS
remote procedure calls.
yp_master (indomain, inmap, outname)
char *indomain;
char *inmap;
char **outname;
The yp_master routine returns the machine name of the NIS master server
for a map.
The indomain and inmap parameters point to the names of the domain and
map used as input to the system call. The outname parameter points to
the character string that identifies the NIS master server by name.
yp_match (indomain, inmap, inkey, inkeylen, outval, outvallen)
char *indomain;
char *inmap;
char *inkey;
int inkeylen;
Processed Nov. 7, 1990 NETWORK INFORMATION SERVICE CLIENT INTERFACE(3n,L) 5
NETWORK INFO SVCE CLIENT I'FACE(3n,L) NETWORK INFO SVCE CLIENT I'FACE(3n,L)
char **outval;
int *outvallen;
The yp_match routine searches for the value associated with a key. The
input character string entered as the key must match a key in the NIS map
exactly because pattern matching is not available in the NIS.
The indomain, inmap, and inkey parameters point to the names of the
domain, map, and key used as input to the function. The inkeylen
parameter is the length, in bytes, of the string inkey.
The outval parameter is an uninitialized pointer to a buffer where the
values associated with the key are placed. The outvallen parameter is
the length, in bytes, of the string pointed to by outval.
yp_order (indomain, inmap, outorder)
char *indomain;
char *inmap;
unsigned long *outorder;
The yp_order routine returns the order number for a map which identifies
when the map was built. This is important in determining if the local
map is the most current version or if the master NIS data base has a more
current one.
The indomain and inmap parameters point to the names of the domain and
map used as input to the system call.
The outorder parameter points to the order number, which is a ten-digit
ASCII integer that represents the AIX time, in seconds, when the map was
built.
ERROR INFORMATION:
char *yperr_string (incode)
int incode;
The yperr_string routine returns a pointer to an error message string.
The error message string is null-terminated but contains no period or
new-line escape characters.
ypprot_err (incode)
u_int incode;
The ypprot_err routine takes a NIS protocol error code as input, and
returns an error code to be used as input to an yperr_string call.
BINDING AND UNBINDING NIS SERVICE:
yp_bind (indomain)
char *indomain;
Processed Nov. 7, 1990 NETWORK INFORMATION SERVICE CLIENT INTERFACE(3n,L) 6
NETWORK INFO SVCE CLIENT I'FACE(3n,L) NETWORK INFO SVCE CLIENT I'FACE(3n,L)
void yp_unbind (indomain)
char *indomain;
In order to use the NIS services, the client process must be bound to a
NIS server that serves the appropriate domain. That is, the client must
be associated with a specific NIS server that services the client's
requests for NIS information. The NIS lookup processes automatically use
the ypbind daemon to bind the client, but yp_bind can be used in programs
to call the daemon directly for processes that use backup strategies when
NIS is not available.
Each NIS binding allocates, or uses up, one client process socket
descriptor, and each bound domain uses one socket descriptor. Multiple
requests to the same domain use the same descriptor.
The yp_unbind routine is available to manage socket descriptors for
processes that access multiple domains. When yp_unbind is used to free a
domain, all per-process and per-node resources that were used to bind it
are also freed.
Note: If an RPC failure status returns from the use of yp_bind, the
domain is unbound automatically. When this occurs, the NIS client
tries to complete the operation if the ypbind daemon is running
and one of the following is true:
o The client process cannot bind a server for the proper domain.
o Remote procedure calls to the server fail.
The NIS client returns control to the user with either an error or
success code with results if any of the following occurs:
o The error is not related to RPC.
o The ypbind daemon is not running.
o The ypserv daemon returns an answer.
RETURN VALUE
Upon successful completion, the NIS client interface routines return the value
0. Otherwise, they return a failure code with the prefix "NISERR_".
ERROR CONDITIONS
The NIS function calls fail if one or more of the following is true:
NISERR_BADARGS Arguments to the function are not correct.
NISERR_RPC Unable to complete remote procedure call because domain is not
bound.
NISERR_DOMAIN Cannot bind to NIS server on this domain.
Processed Nov. 7, 1990 NETWORK INFORMATION SERVICE CLIENT INTERFACE(3n,L) 7
NETWORK INFO SVCE CLIENT I'FACE(3n,L) NETWORK INFO SVCE CLIENT I'FACE(3n,L)
NISERR_MAP Map is not in server's domain.
NISERR_KEY Key is not in map.
NISERR_NISERR Internal NIS server or client error.
NISERR_RESRC Resource allocation failure.
NISERR_NOMORE No more records in map data base.
NISERR_PMAP Cannot communicate with portmap daemon.
NISERR_NISBIND Cannot communicate with ypbind daemon.
NISERR_NISSERV Cannot communicate with the ypserv daemon.
NISERR_NODOM Local NIS domain name not set.
FILES
/usr/include/rpcsvc/ypclnt.h
/usr/include/rpcsvc/yp_prot.h
RELATED INFORMATION
In this book: "Remote Procedure Call (RPC)" and "XDR (External Data
Representation)."
The ypbind, ypserv, and administrative commands in AIX Operating System
Commands Reference.
Processed Nov. 7, 1990 NETWORK INFORMATION SERVICE CLIENT INTERFACE(3n,L) 8