unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

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  -  NIS
       client interface

SYNOPSIS AND DESCRIPTION
       This package of functions provides an interface to the Network Informa-
       tion Service (NIS).  The  package  can  be  loaded  from  the  standard
       library,  /usr/lib/libc.a.   Refer  to  ypfiles(5) and ypserv(8) for an
       overview of the NIS name service, including the definitions of map  and
       domain,  and  a description of the various servers, databases, and com-
       mands that comprise the NIS services.

       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.  Memory is allocated  by  the  NIS  client
       package using malloc(3V), and may be freed if the user code has no con-
       tinuing need for it.  For each outkey and outval, two  extra  bytes  of
       memory are allocated at the end that contain NEWLINE and the null char-
       acter, respectively, but these two bytes are not reflected in outkeylen
       or outvallen.  indomain and inmap strings must not be empty and must be
       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-ter-
       minated.

       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.

       yp_bind (indomain);
       char *indomain;

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

       void
       yp_unbind (indomain)
       char *indomain;

              Each  binding  allocates  (uses  up)  one  client process socket
              descriptor; each bound domain costs one socket descriptor.  How-
              ever,  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  cannot 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 fail-
              ure), the ypclnt layer will return control  to  the  user  code,
              either with an error code, or a success code and any results.

       yp_get_default_domain (outdomain);
       char **outdomain;

              The  NIS  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 succes-
              sive NIS calls.

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

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

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

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

       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_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 particu-
              lar  to  the structure of the NIS map being processing; there is
              no relation in retrieval  order  to  either  the  lexical  order
              within  any  original  (non-NIS)  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() func-
              tion is called on a particular map, and then the yp_next() func-
              tion  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 oth-
              erwise  be  returned  in the midst of the enumeration.  The next
              paragraph describes a better solution to enumerating all entries
              in a map.

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

              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 NIS 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 does not 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 invallen;
                 char *indata;

              The instatus parameter will hold one of the return status values
              defined in <&lt;rpcsvc/yp_prot.h>&gt; --  either  YP_TRUE  or  an  error
              code.   See ypprot_err(), below, for a function which converts a
              NIS 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()  func-
              tion,  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 will not be here either.

              The  indata  parameter  is  the contents of the incallback->&gt;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 NIS 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(indomain, inmap, outorder);
       char *indomain;
       char *inmap;
       int *outorder;

              yp_order() returns the order number for a map.

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

              yp_master() returns the machine name of the  master  NIS  server
              for a map.

       char *yperr_string(incode)
       int incode;

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

       ypprot_err (incode)
       unsigned int incode;

              ypprot_err() takes a NIS  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
       <&lt;rpcsvc/ypclnt.h>&gt;
       <&lt;rpcsvc/yp_prot.h>&gt;
       /usr/lib/libc.a

SEE ALSO
       malloc(3V), ypupdate(3N), ypfiles(5), ypserv(8)

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 */

              #define   YPERR_BADDBfR
                      13   /* yp database is bad */

              #define   YPERR_VERSfR
                      14   /* yp version mismatch */

              #define   YPERR_ACCESS
                      15   /* access violation */

              #define   YPERR_BUSY
                      16   /* database busy */

NOTES
       The  Network Information Service (NIS) was formerly known as Sun Yellow
       Pages (YP).  The functionality of the two remains the  same;  only  the
       name  has  changed.  The name Yellow Pages is a registered trademark in
       the United Kingdom of British Telecommunications plc, and  may  not  be
       used without permission.



                                22 January 1988                     YPCLNT(3N)