YP_BIND(3) | Library Functions Manual | YP_BIND(3)

# NAME

`yp_all`, `yp_bind`, `yp_first`, `yp_get_default_domain`, `yp_maplist`, `yp_master`, `yp_match`, `yp_next`, `yp_order`, `yp_unbind`, `yperr_string`, `ypprot_err` — Interface to the YP subsystem

# SYNOPSIS

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

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

int
`yp_bind`(char *dom);

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

int
`yp_get_default_domain`(char **domp);

int
`yp_maplist`(char *indomain, struct ypmaplist **outmaplist);

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

int
`yp_match`(char *indomain, char *inmap, const char *inkey, int inkeylen, 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_order`(char *indomain, char *inmap, char *outorder);

void
`yp_unbind`(char *dom);

char *
`yperr_string`(int incode);

int
`ypprot_err`(unsigned int incode);

# DESCRIPTION

This function 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. Only if a call succeeds will memory 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 ‘`\n`’ and ‘`\0`’, which are not reflected in the values of outkeylen or outvallen. All occurrences of indomain and inmap must be non-null, NUL-terminated 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_master`(), `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 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 RPC-related, one of the YP error codes described below is returned and control given back to the user code.

The suite provides the following functionality:

`yp_match`()
  Provides the value associated with the given key.
`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 `yp_first`(). 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`(), providing that the same map on the same server is polled repeatedly until `yp_next`() returns YPERR_NOMORE, are that all key-value 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 re-binds, the retrieval rules will break: some entries may be seen twice, and others not at all. For this reason, the function `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 method uses TCP, unlike all other functions which use UDP. The entire transaction occurs in a single RPC request-response. The third argument to this function provides a way to supply the name of a function to process each key-value pair in the map. `yp_all`() returns after the entire transaction 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 key-value pairs, at which time `yp_all`() returns a value of 0, and is called with the following arguments:

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

  Where:

  instatus
    Holds one of the return status values described in `<rpcsvc/yp_prot.h>`: see `ypprot_err`() below for a function that will translate YP protocol errors into a error code as described in `<rpcsvc/ypclnt.h>`.
  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`() function should do something useful with the contents of that memory during each iteration. If the key-value pairs are not terminated with either ‘`\n`’ or ‘`\0`’ in the map, then they will not be terminated as such when given to the `foreach`() function, either.
  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 completely 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.
`yp_maplist`()
  Returns a singly-linked list of the names of all the maps available in the named domain. The second argument to `yp_maplist`() is:

      struct ypmaplist {
      	char *map;
      	struct ypmaplist *next;
      };

`yperr_string`()
  Returns a pointer to a NUL-terminated error string that does not contain a ‘`.`’ or ‘`\n`’.
`ypprot_err`()
  Converts a YP protocol error code to an error code suitable for `yperr_string`().

# RETURN VALUES

All functions 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 invalid.
[`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_NODOM`]
  The local YP domain is not set.
[`YPERR_NOMORE`]
  There are no more records in the queried map.
[`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_YPBIND`]
  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

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

# AUTHORS

Theo de Raadt

December 3, 2020 | Debian