yp_all man page on NeXTSTEP

Man page or keyword search:  
man Server   1419 pages
apropos Keyword Search (all sections)
Output format
NeXTSTEP logo
[printable version]


YPCLNT(3N)							    YPCLNT(3N)

NAME
       ypclnt,	yp_get_default_domain, yp_bind, yp_unbind, yp_match, yp_first,
       yp_next, yp_all, yp_order, yp_master, yperr_string, ypprot_err - yellow
       pages client interface

SYNOPSIS
       #include <rpcsvc/ypclnt.h>
       yp_bind(indomain);
       char *indomain;
       void yp_unbind(indomain)
       char *indomain;
       yp_get_default_domain(outdomain);
       char **outdomain;
       yp_match(indomain, inmap, inkey, inkeylen, outval, outvallen)
       char *indomain;
       char *inmap;
       char *inkey;
       int inkeylen;
       char **outval;
       int *outvallen;
       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;
       yp_all(indomain, inmap, incallback);
       char *indomain;
       char *inmap;
       struct ypall_callback incallback;
       yp_order(indomain, inmap, outorder);
       char *indomain;
       char *inmap;
       int *outorder;
       yp_master(indomain, inmap, outname);
       char *indomain;
       char *inmap;
       char **outname;
       char *yperr_string(incode)
       int incode;
       ypprot_err(incode)
       unsigned int incode;

DESCRIPTION
       This  package  of  functions  provides an interface to the yellow pages
       (YP) network lookup service.   The  package  can	 be  loaded  from  the
       standard	 library,  /lib/libc.a.	 Refer to ypfiles(5) and ypserv(8) for
       an overview of the yellow pages, including the definitions of  map  and
       domain  ,  and  a  description  of  the various servers, databases, and
       commands that comprise the YP.

       All input parameters names begin with in.  Output parameters begin with
       out.   Output  parameters  of  type  char  **  should  be  addresses of
       uninitialized character pointers.  Memory is allocated by the YP client
       package	using  malloc(3),  and	may  be	 freed if the user code has no
       continuing need for it.	For each outkey and outval, two extra bytes of
       memory  are  allocated  at  the	end  that  contain  NEWLINE  and NULL,
       respectively, but these two bytes are not  reflected  in	 outkeylen  or
       outvallen  .   indomain	and  inmap  strings must be non-null and null-
       terminated.   String  parameters	 which	are  accompanied  by  a	 count
       parameter  may  not  be	null,  but may point to null strings, with the
       count parameter indicating this.	 Counted strings  need	not  be	 null-
       terminated.

       All functions in this package of type int return 0 if they succeed, and
       a failure code (YPERR_xxxx) otherwise.	Failure	 codes	are  described
       under DIAGNOSTICS below.

       The  YP	lookup calls require a map name and a domain name, at minimum.
       It is assumed that the client process knows the	name  of  the  map  of
       interest.   Client  processes should fetch the node's default domain by
       calling yp_get_default_domain() , and use the returned outdomain as the
       indomain parameter to successive YP calls.

       To  use	the  YP services, the client process must be ``bound'' to a YP
       server that serves the appropriate domain using yp_bind.	 Binding  need
       not  be	done  explicitly  by  user  code;  this	 is done automatically
       whenever a YP  lookup  function	is  called.   yp_bind  can  be	called
       directly	 for  processes	 that  make  use of a backup strategy (e.g., a
       local file) in cases when YP services are not available.

       Each binding allocates (uses up) one client process socket  descriptor;
       each  bound  domain  costs  one	socket	descriptor.  However, multiple
       requests to the same domain use that same descriptor.   yp_unbind()  is
       available  at the client interface for processes that explicitly manage
       their socket descriptors while accessing multiple domains.  The call to
       yp_unbind()  make the domain unbound, and free all per-process and per-
       node resources used to bind it.

       If an RPC failure results upon use of a binding, that  domain  will  be
       unbound	automatically.	 At  that  point,  the ypclnt layer will retry
       forever or until	 the  operation	 succeeds,  provided  that  ypbind  is
       running, and either

       a)     the client process can't bind a server for the proper domain, or

       b)     RPC requests to the server fail.

       If  an  error  is not RPC-related, or if ypbind is not running, or if a
       bound ypserv process returns  any  answer  (success  or	failure),  the
       ypclnt layer will return control to the user code, either with an error
       code, or a success code and any results.

       yp_match returns the value associated with a passed key.	 This key must
       be exact; no pattern matching is available.

       yp_first	 returns  the  first  key-value pair from the named map in the
       named domain.

       yp_next() returns the next key-value pair in a named  map.   The	 inkey
       parameter  should  be  the  outkey  returned  from  an  initial call to
       yp_first() (to get the second key-value pair) or the one returned  from
       the nth call to yp_next() (to get the nth + second key-value pair).

       The  concept  of first (and, for that matter, of next) is particular to
       the structure of the YP map being processing; there is no  relation  in
       retrieval  order	 to either the lexical order within any original (non-
       YP) data base, or to any obvious numerical sorting order on  the	 keys,
       values,	or  key-value pairs.  The only ordering guarantee made is that
       if the yp_first() function is called on a particular map, and then  the
       yp_next()  function  is	repeatedly  called on the same map at the same
       server until the call fails with a reason of YPERR_NOMORE, every	 entry
       in  the	data  base  will  be  seen exactly once.  Further, if the same
       sequence of operations is performed on the same map at the same server,
       the entries will be seen in the same order.

       Under conditions of heavy server load or server failure, it is possible
       for the domain to become unbound, then bound once again (perhaps	 to  a
       different server) while a client is running.  This can cause a break in
       one of the enumeration rules; specific entries may be seen twice by the
       client,	or  not	 at all.  This approach protects the client from error
       messages	 that  would  otherwise	 be  returned  in  the	midst  of  the
       enumeration.   The  next	 paragraph  describes  a  better  solution  to
       enumerating all entries in a map.

       yp_all provides a way to transfer an entire map from server  to	client
       in  a single request using TCP (rather than UDP as with other functions
       in this package).  The entire transaction take place as	a  single  RPC
       request	and  response.	 You  can  use	yp_all	just like any other YP
       procedure, identify the map in the normal manner, and supply  the  name
       of  a  function	which  will  be	 called to process each key-value pair
       within the map.	You return from the  call  to  yp_all  only  when  the
       transaction  is	completed  (successfully  or  unsuccessfully), or your
       ``foreach'' function decides that it doesn't want to see any more  key-
       value pairs.

       The third parameter to yp_all is
	    struct ypall_callback *incallback {
		 int (*foreach)();
		 char *data;
	    };

       The function foreach is called

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

       The  instatus  parameter	 will  hold  one  of  the return status values
       defined in <rpcsvc/yp_prot.h> — either YP_TRUE or an error code.	  (See
       ypprot_err  ,  below, for a function which converts a YP protocol error
       code to a ypclnt layer error code.)

       The key and value parameters are somewhat different than defined in the
       synopsis	 section above.	 First, the memory pointed to by the inkey and
       inval parameters is private to the yp_all function, and is  overwritten
       with  the arrival of each new key-value pair.  It is the responsibility
       of the foreach function to do something useful  with  the  contents  of
       that  memory,  but  it  does  not own the memory itself.	 Key and value
       objects presented to the foreach function look exactly as  they	do  in
       the  server's  map  —  if  they	were  not  newline-terminated or null-
       terminated in the map, they won't be here either.

       The indata parameter is the contents of	the  incallback->data  element
       passed  to  yp_all .  The data element of the callback structure may be
       used to share state information between the foreach  function  and  the
       mainline	 code.	 Its  use  is  optional,  and no part of the YP client
       package inspects its contents — cast it to something useful, or	ignore
       it as you see fit.

       The  foreach  function is a Boolean.  It should return zero to indicate
       that it wants to be called again for further received key-value	pairs,
       or  non-zero to stop the flow of key-value pairs.  If foreach returns a
       non-zero value, it is not called again; the functional value of	yp_all
       is then 0.

       yp_order returns the order number for a map.

       yp_master returns the machine name of the master YP server for a map.

       yperr_string returns a pointer to an error message string that is null-
       terminated but contains no period or newline.

       ypprot_err takes a YP protocol error  code  as  input,  and  returns  a
       ypclnt  layer  error  code,  which  may	be used in turn as an input to
       yperr_string .

FILES
       <bsd/rpcsvc/ypclnt.h>
       <bsd/rpcsvc/yp_prot.h>

SEE ALSO
       ypfiles(5), ypserv(8),

DIAGNOSTICS
       All  integer  functions	return	0  if  the  requested	operation   is
       successful, or one of the following errors if the operation fails.

	      #define YPERR_BADARGS  1	/* args to function are bad */
	      #define YPERR_RPC	     2	/* RPC failure - domain has been unbound */
	      #define YPERR_DOMAIN   3	/* can't bind to server on this domain */
	      #define YPERR_MAP	     4	/* no such map in server's domain */
	      #define YPERR_KEY	     5	/* no such key in map */
	      #define YPERR_YPERR    6	/* internal yp server or client error */
	      #define YPERR_RESRC    7	/* resource allocation failure */
	      #define YPERR_NOMORE   8	/* no more records in map database */
	      #define YPERR_PMAP     9	/* can't communicate with portmapper */
	      #define YPERR_YPBIND   10 /* can't communicate with ypbind */
	      #define YPERR_YPSERV   11 /* can't communicate with ypserv */
	      #define YPERR_NODOM    12 /* local domain name not set */

			       14 September 1985		    YPCLNT(3N)
[top]

List of man pages available for NeXTSTEP

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net