ypclnt man page on Ultrix

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

ypclnt(3yp)							   ypclnt(3yp)

Name
       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 package

Syntax
       #include <rpcsvc/ypclnt.h>
       yp_get_default_domain(outdomain)
       char **outdomain;
       yp_bind(indomain)
       char *indomain;
       void yp_unbind(indomain)
       char *indomain;
       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) data base lookup service.  The package  can	 be  loaded  from  the
       standard	 library,  Refer  to  and for an overview of the Yellow Pages,
       including the definitions of map and domain, and for a  description  of
       the  servers,  data bases, and commands that constitute the YP applica‐
       tion.

       All input parameters names begin with in.  Output parameters begin with
       out.   Output  parameters of type char ** should be addresses of unini‐
       tialized character pointers.  The YP client  package  allocates	memory
       using  This memory can 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.  The indo‐
       main  and  inmap	 strings must be non-null and null-terminated.	String
       parameters that are accompanied by a count parameter  cannot  be	 null,
       but  can	 point	to  null  strings, with the count parameter indicating
       this.  Counted strings need not be null-terminated.

       All functions of type int return 0 if they succeed, or a	 failure  code
       (YPERR_	xxxx  )	 if  they do not succeed.  Failure codes are described
       under Diagnostics.

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

       To  use	YP  services,  the client process must be bound to a YP server
       that serves the appropriate domain. The binding	is  accomplished  with
       Binding	need not be done explicitly by user code; it is done automati‐
       cally whenever a YP lookup function is called.	The  function  can  be
       called  directly	 for  processes	 that make use of a backup strategy in
       cases when YP services are not available.

       Each binding allocates one client process socket descriptor; each bound
       domain  requires	 one socket descriptor.	 Multiple requests to the same
       domain use that same descriptor.	 The  function	is  available  at  the
       client  interface  for  processes  that	explicitly manage their socket
       descriptors while accessing multiple domains.  The call	to  makes  the
       domain  unbound,	 and frees 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 for‐
       ever or until the operation succeeds. This action occurs provided  that
       is  running, and either the client process cannot bind a server for the
       proper domain, or RPC requests to the server fail.

       The -s option allows the system administrator to lock to	 a  particular
       domain  and  set	 of servers.  Up to four servers can be specified.  An
       example of the -s option follows:
       /etc/ypbind -s domain,server1[,server2,server3,server4]

       The ypclnt layer will return control to the user code, either  with  an
       error  code,  or with a success code and any results under certain cir‐
       cumstances.  For example, control will be returned  to  the  user  code
       when an error is not RPC-related and also when the function is not run‐
       ning.  An additional situation that will cause the return of control is
       when a bound ypserv process returns any answer (success or failure).

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

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

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

       The concept of first and of next is particular to the structure of  the
       YP  map	being  processed;  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  function  is
       called  on a particular map, and then the 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 enumera‐
       tion.  Enumerating all entries in a map is accomplished with the	 func‐
       tion.

       The  function  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.	 The function can  be  used  like  any
       other  YP  procedure,  to identify the map in the normal manner, and to
       supply the name of a function that will be called to process each  key-
       value  pair  within  the map.  Returns from the call to occur only when
       the transaction is completed (successfully or unsuccessfully), or  when
       the  function  decides  that it does not want to see any more key-value
       pairs.

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

       The function is called
       foreach(instatus, inkey, inkeylen, inval, invallen, indata);
       int instatus;
       char *inkey;
       int inkeylen;
       char *inval;
       int invallen;
       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 that converts	a  YP  protocol	 error
       code to a ypclnt layer error code.)

       The key and value parameters are somewhat different than defined in the
       syntax section above.  First, the memory pointed to by  the  inkey  and
       inval parameters is private to the function and is overwritten with the
       arrival of each new key-value pair.  It is the  responsibility  of  the
       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 function look exactly as they do in the server's map — if they were
       not newline-terminated or null-terminated in the map, they will not  be
       here either.

       The  indata  parameter  is the contents of the incallback->data element
       passed to The data element of the callback structure  may  be  used  to
       share  state  information  between  the function and the mainline code.
       Its use is optional, and no part of the YP client package inspects  its
       contents.

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

       The function returns the order number for a map.

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

       The function returns a pointer to an error message string that is null-
       terminated but contains no period or new line.

       The  function  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

Diagnostics
       All integer functions return 0 if the requested operation  is  success‐
       ful, 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 */

Files
       /usr/include/rpcsvc/ypclnt.h
       /usr/include/rpcsvc/yp_prot.h

See Also
       ypfiles(5yp), ypserv(8yp)

								   ypclnt(3yp)
[top]

List of man pages available for Ultrix

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