*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> yp_master (3)              



NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

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

     yp_all(char *indomain, char  *inmap,  struct  ypall_callback

     yp_bind(char *dom);

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

     yp_get_default_domain(char **domp);

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

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

     yp_next(char   *indomain,  char  *inmap,  char  *inkey,  int
             char **outkey, int *outkeylen,  char  **outval,  int

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

     yp_unbind(char *dom);

     char *
     yperr_string(int incode);

     ypprot_err(unsigned int incode);

DESCRIPTION    [Toc]    [Back]

     The  ypclnt suite provides an interface to the YP subsystem.
For a general
 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
     uninitialized character pointers.  Memory will be  allocated
by the YP
     client  routines  using  malloc().  This memory can later be
freed by the
     user if there is no additional  need  for  the  data  stored
there.  For
     outkey  and  outval, two extra bytes of memory are allocated
for a `0 and
     ` ', which are not reflected in the values of  outkeylen  or
     All occurrences of indomain and inmap must be non-null, NULterminated
     strings.  All input strings which also have a  corresponding
length parameter
 cannot be null 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_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 cannot
 bind to a server for the domain specified in the lookup,
or RPC requests
  to  the  YP server process fail.  If an error is not
     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

     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
                     obtain the  second  pair,  the  inkey  value
should be the
                     outkey value provided by the initial call to
                     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(),
                     that the same map  on  the  same  server  is
polled repeatedly
                     until  yp_next()  returns  YPERR_NOMORE, are
that all keyvalue
 pairs in that map will be accessed exactly once,
                     and if the entire procedure 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  rebinds, the retrieval
  rules  will break: some entries may
be seen twice,
                     and others not at all.  For this reason, the
                     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  requestresponse.  The
                     third  argument  to this function provides a
way to supply
                     the name of a function to process each  keyvalue pair in
                     the  map.  yp_all() returns after the entire
                     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 keyvalue
  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 described
 in <rpcsvc/yp_prot.h>:
                                   ypprot_err() below for a function that will
                                   translate  YP  protocol errors
into a ypclnt
                                   layer error code as  described

                     inkey,  inval   The  key and value arguments
are somewhat
                                   different here than  described
above.  In
                                   this  case, the memory pointed
to by inkey
                                   and  inval   is   private   to
yp_all(), and is
                                   overwritten  with  each subsequent key-value
                                   pair; therefore,  the  foreach
                                   should   do  something  useful
with the contents
 of  that  memory  during
each iteration.
                                   If the key-value pairs are not
                                   with either `0 or ` '  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
                                   optional: cast it to something
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.

     yperr_string()   Returns a pointer to a NUL-terminated error
string that
                     does not contain a `.' or `0.

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

RETURN VALUES    [Toc]    [Back]

     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

     [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

     [YPERR_PMAP]      Cannot communicate with portmap.

     [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 running
  version  1  of  the   YP   protocol,
yp_all() functionality
 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 process.

SEE ALSO    [Toc]    [Back]

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

AUTHORS    [Toc]    [Back]

     Theo De Raadt

OpenBSD      3.6                         October     26,     1994
[ Back ]
 Similar pages
Name OS Title
diag0 HP-UX diagnostic interface to HP-PB I/O subsystem
diag1 HP-UX diagnostic interface to the PCI I/O subsystem
dxaudit Tru64 Motif Interface for the Audit Subsystem
auditconfig Tru64 Audit subsystem configuration graphical interface (Enhanced Security)
audit_setup Tru64 Audit subsystem configuration graphical interface (Enhanced Security)
scsi FreeBSD CAM SCSI subsystem
sys_attrs_ppp Tru64 ppp subsystem attributes
sys_attrs_psm Tru64 psm subsystem attributes
sys_attrs_pts Tru64 pts subsystem attributes
sys_attrs_rt Tru64 rt subsystem attributes
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service