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

  man pages->Tru64 Unix man pages -> yp_next (3)              



NAME    [Toc]    [Back]

       yp_get_default_domain,   yp_bind,   yp_unbind,   yp_match,
       yp_first,   yp_next,    yp_all,    yp_order,    yp_master,
       yperr_string,  ypprot_err  -  Network  Information Service
       (NIS) client package

SYNOPSIS    [Toc]    [Back]

       #include <rpcsvc/ypclnt.h>

       int yp_get_default_domain(
               char **outdomain ); int ypbind(
               char *indomain ); int yp_unbind(
               char *indomain ); int yp_match(
               char *indomain,
               char *inmap,
               char *inkey,
               int inkeylen,
               char **outval,
               int *outvallen ); int yp_first(
               char *indomain,
               char *inmap,
               char **outkey,
               int *outkeylen,
               char **outval,
               int *outvallen ); int yp_next(
               char *indomain,
               char *inmap,
               char *inkey,
               int inkeylen,
               char **outkey,
               int *outkeylen,
               char **outval,
               int *outvallen ); int yp_all(
               char *indomain,
               char *inmap,
               struct ypcallback incallback ); int yp_order(
               char *indomain,
               char *inmap,
               int *outorder ); int yp_master(
               char *indomain,
               char *inmap,
               char **outname ); char *yperr_string(
               int incode ); char ypprot_err(
               unsigned int incode );

DESCRIPTION    [Toc]    [Back]

       This package of functions provides  an  interface  to  the
       Network Information Service (NIS) database lookup service.
       The package can  be  loaded  from  the  standard  library,
       /lib/libc.a.  Refer  to  ypfiles(4)  and  ypserv(8) for an
       overview of NIS, including the definitions  of  "map"  and
       "domain",  and  for  a  description  of  the servers, data
       bases, and commands that constitute the NIS application.

       All input parameters names begin with "in". Output parameters
  begin  with "out". Output parameters of type char **
       should be addresses of uninitialized  character  pointers.
       The  NIS  client package allocates memory using malloc(3).
       This memory can be freed if the user code has no  continuing
  need  for  it.  The yp_get_default_domain() function,
       however, returns a pointer to thread-specific data. Therefore,
  the  memory  cannot  be  freed  by  user code. (The
       contents of that  memory  are  updated  with  the  current
       default domain on each call.)

       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  indomain  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 in the ERRORS section of this reference

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

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

       Each binding allocates one client process socket  descriptor;
  each bound domain in each thread requires one socket
       descriptor. Multiple requests to the same domain from  the
       same  thread  use  that  same  descriptor. The yp_unbind()
       function is available at the client interface for  threads
       that  explicitly  manage  their  socket  descriptors while
       accessing multiple domains.  The call to yp_unbind() makes
       the  domain unbound, and frees all per-thread and per-node
       resources used to bind it.

       If an RPC failure results upon  use  of  a  binding,  that
       domain  will  be unbound automatically for the thread that
       encountered the error. At that  point,  the  ypclnt  layer
       will  retry forever or until the operation succeeds.  This
       action occurs provided that ypbind is running, and  either
       the  client  thread  cannot  bind  a server for the proper
       domain, or RPC requests to the server fail.

       The ypbind -S option allows the  system  administrator  to
       lock  ypbind to a particular domain and set of servers. Up
       to four servers can be specified. An  example  of  the  -S
       option follows:

       /usr/sbin/ypbind                                        -S

       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 circumstances. For example,  control
       will  be  returned  to  the user code when an error is not
       RPC-related and also when the  ypbind()  function  is  not
       running.  An  additional  situation  that  will  cause the
       return of control is when a bound ypserv  process  returns
       any answer (success or failure).

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

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

       The yp_next() function 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

       The  concept  of  first  and  of next is particular to the
       structure of the NIS map  being  processed;  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()  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. Enumerating  all
       entries  in  a map is accomplished with the yp_all() function.

       The yp_all() 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 yp_all() function can be used  like  any
       other  NIS  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  yp_all()  occur  only  when  the
       transaction is completed (successfully or unsuccessfully),
       or when the foreach() function decides that  it  does  not
       want to see any more key-value pairs.

       The third parameter to yp_all() is as follows:

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

       The foreach() function is defined as follows: foreach(
               int instatus,
               char *inkey,
               int intkeylen,
               char *inval,
               int invallen,
               char *indata );

       The  instatus parameter will hold one of the return status
       values defined  in  the  rpcsvc/yp_prot.h  header  file  -
       either  YP_TRUE  or  an error code. (See the discussion of
       ypprot_err() for a function that converts a  NIS  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 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 will not 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 NIS
       client package inspects its contents.

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

       The  yp_order()  function  returns  the order number for a

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

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

       The  ypprot_err() function 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().

ERRORS    [Toc]    [Back]

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

       #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    [Toc]    [Back]

       Header  file  containing  ypclnt definitions.  Header file
       defining return status values.

SEE ALSO    [Toc]    [Back]

       Commands: ypserv(8)

       Files: ypfiles(4)

[ Back ]
 Similar pages
Name OS Title
nis_intro Tru64 Network Information Service (NIS) introductory information
nis HP-UX a new version of the network information name service
nis+ HP-UX a new version of the network information name service
NIS+ HP-UX a new version of the network information name service
nis IRIX Network Information Services Protocol (Client)
nis_manual_setup Tru64 Describes how to manually set up the Network Information Service (NIS)
setdomainna HP-UX get/set name of current Network Information Service domain
getaddrinfo Tru64 Get address information for a network node and service
ypset HP-UX bind to particular Network Information Service server
makedbm Tru64 Makes a Network Information Service (NIS) map file
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service