Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
YPCLNT(3)		 BSD Library Functions Manual		     YPCLNT(3)

     yp_all, yp_bind, yp_first,	yp_get_default_domain, yp_master, yp_match,
     yp_next, yp_order,	yp_unbind, yperr_string, ypprot_err -- Interface to
     the YP subsystem

     Standard C	Library	(libc, -lc)

     #include <sys/types.h>
     #include <rpc/rpc.h>
     #include <rpcsvc/ypclnt.h>
     #include <rpcsvc/yp_prot.h>

     yp_all(const char *indomain, const	char *inmap,
	 struct	ypall_callback *incallback);

     yp_bind(const char	*dom);

     yp_first(const char *indomain, const char *inmap, char **outkey,
	 int *outkeylen, char **outval,	int *outvallen);

     yp_get_default_domain(char	**outdomain);

     yp_master(const char *indomain, const char	*inmap,	char **outname);

     yp_match(const char *indomain, const char *inmap, const char *inkey,
	 int inkeylen, char **outval, int *outvallen);

     yp_next(const char	*indomain, const char *inmap, const char *inkey,
	 int inkeylen, char **outkey, int *outkeylen, char **outval,
	 int *outvallen);

     yp_order(const char *indomain, const char *inmap, int *outorder);

     yp_unbind(const char *dom);

     char *
     yperr_string(int incode);

     ypprot_err(unsigned int incode);

     The ypclnt	suite provides an interface to the YP subsystem.  For a	gen-
     eral description of the YP	subsystem, see yp(8).

     For all functions,	input values begin with	in and output values begin
     with out.

     Any output	values of type char ** should be the addresses of uninitial-
     ized character pointers.  These values will be reset to the null pointer
     (unless the address itself	is the null pointer, in	which case the error
     YPERR_BADARGS will	be returned).  If necessary, memory will be allocated
     by	the YP client routines using malloc(), and the result will be stored
     in	the appropriate	output value.  If the invocation of a YP client	rou-
     tine doesn't return an error, and an output value is not the null
     pointer, then this	memory should be freed by the user when	there is no
     additional	need for the data stored there.	 For outkey and	outval,	two
     extra bytes of memory are allocated for a `\n' and	`\0', which are	not
     reflected in the values of	outkeylen or outvallen.

     All occurrences of	indomain and inmap must	be non-null, NUL-terminated
     strings.  All input strings which also have a corresponding length	param-
     eter cannot be the	null pointer unless the	corresponding length value is
     zero.  Such strings need not be NUL-terminated.

     All YP lookup calls (the functions	yp_all(), yp_first(), yp_master(),
     yp_match(), yp_next(), yp_order())	require	a YP domain name and a YP map
     name.  The	default	domain name may	be obtained by calling
     yp_get_default_domain(), and should thus be used before all other YP
     calls in a	client program.	 The value it places outdomain is suitable for
     use as the	indomain parameter to all subsequent YP	calls.

     In	order for YP lookup calls to succeed, the client process must be bound
     to	a YP server process.  The client process need not explicitly bind to
     the server, as it happens automatically whenever a	lookup occurs.	The
     function yp_bind()	is provided for	a backup strategy, e.g.	a local	file,
     when a YP server process is not available.	 Each binding uses one socket
     descriptor	on the client process, which may be explicitly freed using
     yp_unbind(), which	frees all per-process and per-node resources to	bind
     the domain	and marks the domain unbound.

     If, during	a YP lookup, an	RPC failure occurs, the	domain used in the
     lookup is automatically marked unbound and	the ypclnt layer retries the
     lookup as long as ypbind(8) is running and	either the client process can-
     not bind to a server for the domain specified in the lookup, or RPC re-
     quests to the YP server process fail.  If an error	is not RPC-related,
     one of the	YP error codes described below is returned and control given
     back to the user code.

     The ypclnt	suite provides the following functionality:

     yp_match()	   Provides the	value associated with the given	key.

     yp_first()	   Provides the	first key-value	pair from the given map	in the
		   named domain.

     yp_next()	   Provides the	next key-value pair in the given map.  To ob-
		   tain	the second pair, the inkey value should	be the outkey
		   value provided by the initial call to yp_first().  In the
		   general case, the next key-value pair may be	obtained by
		   using the outkey value from the previous call to yp_next()
		   as the value	for inkey.

		   Of course, the notions of "first" and "next"	are particular
		   to the type of YP map being accessed, and thus there	is no
		   guarantee of	lexical	order.	The only guarantees provided
		   with	yp_first() and yp_next(), providing that the same map
		   on the same server is polled	repeatedly until yp_next() re-
		   turns YPERR_NOMORE, are that	all key-value pairs in that
		   map will be accessed	exactly	once, and if the entire	proce-
		   dure	is repeated, the order will be the same.

		   If the server is heavily loaded or the server fails for
		   some	reason,	the domain being used may become unbound.  If
		   this	happens, and the client	process	re-binds, the re-
		   trieval rules will break: some entries may be seen twice,
		   and others not at all.  For this reason, the	function
		   yp_all() provides a better solution for reading all of the
		   entries in a	particular map.

     yp_all()	   This	function provides a way	to transfer an entire map from
		   the server to the client process with a single request.
		   This	transfer uses TCP, unlike all other functions in the
		   ypclnt suite, which use UDP.	 The entire transaction	occurs
		   in a	single RPC request-response.  The third	argument to
		   this	function provides a way	to supply the name of a	func-
		   tion	to process each	key-value pair in the map.  yp_all()
		   returns after the entire transaction	is complete, or	the
		   foreach function decides that it does not want any more
		   key-value pairs.  The third argument	to yp_all() is:

			 struct	ypall_callback *incallback {
				 int (*foreach)();
				 char *data;

		   The char *data argument is an opaque	pointer	for use	by the
		   callback function.  The foreach function should return non-
		   zero	when it	no longer wishes to process key-value pairs,
		   at which time yp_all() returns a value of 0,	and is called
		   with	the following arguments:

			 int foreach (
				 int instatus,
				 char *inkey,
				 int inkeylen,
				 char *inval,
				 int invallen,
				 char *indata


		   instatus	 Holds one of the return status	values de-
				 scribed in <rpcsvc/yp_prot.h>:	see
				 ypprot_err() below for	a function that	will
				 translate YP protocol errors into a ypclnt
				 layer error code as described in

		   inkey, inval	 The key and value arguments are somewhat dif-
				 ferent	here than described above.  In this
				 case, the memory pointed to by	inkey and
				 inval is private to yp_all(), and is over-
				 written with each subsequent key-value	pair,
				 thus the foreach function should do something
				 useful	with the contents of that memory dur-
				 ing each iteration.  If the key-value pairs
				 are not terminated with either	`\n' or	`\0'
				 in the	map, then they will not	be terminated
				 as such when given to the foreach function,

		   indata	 This is the contents of the incallback-_data
				 element of the	callback structure.  It	is
				 provided as a means to	share state between
				 the foreach function and the user code.  Its
				 use is	completely optional: cast it to	some-
				 thing useful or simply	ignore it.

     yp_order()	   Returns the order number for	a map.

     yp_master()   Returns the hostname	for the	machine	on which the master YP
		   server process for a	map is running.

		   Returns a pointer to	a NUL-terminated error string that
		   does	not contain a `.' or `\n'.

     ypprot_err()  Converts a YP protocol error	code to	a ypclnt error code
		   suitable for	yperr_string().

     All functions in the ypclnt suite which are of type int return 0 upon
     success or	one of the following error codes upon failure:

     [YPERR_BADARGS]   The passed arguments to the function are	invalid.

     [YPERR_BADDB]     The YP map that was polled is defective.

     [YPERR_DOMAIN]    Client process cannot bind to server on this YP domain.

     [YPERR_KEY]       The key passed does not exist.

     [YPERR_MAP]       There is	no such	map in the server's domain.

     [YPERR_DOM]       The local YP domain is not set.

     [YPERR_NOMORE]    There are no more records in the	queried	map.

     [YPERR_PMAP]      Cannot communicate with portmapper (see rpcbind(8)).

     [YPERR_RESRC]     A resource allocation failure occurred.

     [YPERR_RPC]       An RPC failure has occurred.  The domain	has been
		       marked unbound.

     [YPERR_VERS]      Client/server version mismatch.	If the server is run-
		       ning version 1 of the YP	protocol, yp_all() functional-
		       ity does	not exist.

     [YPERR_BIND]      Cannot communicate with ypbind(8).

     [YPERR_YPERR]     An internal server or client error has occurred.

     [YPERR_YPSERV]    The client cannot communicate with the YP server

     malloc(3),	yp(8), ypbind(8), ypserv(8)

     Theo De Raadt

BSD				 May 21, 1997				   BSD


Want to link to this manual page? Use this URL:

home | help