summaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
authorlukem <lukem@NetBSD.org>1998-01-23 13:49:10 +0000
committerlukem <lukem@NetBSD.org>1998-01-23 13:49:10 +0000
commitf5d4256de8bfac56e4c669cdfd0dd5a0574edef7 (patch)
tree86de1a5295da27642b59ab0d2fc48b805519cf25 /lib
parent8bfd252c8301de393f17fa46313c9c7e0da5e2d4 (diff)
use .Tn YP instead of YP
Diffstat (limited to 'lib')
-rw-r--r--lib/libc/yp/ypclnt.396
1 files changed, 72 insertions, 24 deletions
diff --git a/lib/libc/yp/ypclnt.3 b/lib/libc/yp/ypclnt.3
index 6f89023b5b6..ff21f470f6a 100644
--- a/lib/libc/yp/ypclnt.3
+++ b/lib/libc/yp/ypclnt.3
@@ -1,4 +1,4 @@
-.\" $NetBSD: ypclnt.3,v 1.10 1997/10/09 07:33:30 jtc Exp $
+.\" $NetBSD: ypclnt.3,v 1.11 1998/01/23 13:49:10 lukem Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -79,8 +79,12 @@
.Sh DESCRIPTION
The
.Nm ypclnt
-suite provides an interface to the YP subsystem. For a general description
-of the YP subsystem, see
+suite provides an interface to the
+.Tn YP
+subsystem. For a general description
+of the
+.Tn YP
+subsystem, see
.Xr yp 8 .
.Pp
For all functions, input values begin with
@@ -96,10 +100,14 @@ itself is the null pointer, in which case the error
.Er YPERR_BADARGS
will be returned).
If necessary,
-memory will be allocated by the YP client routines using
+memory will be allocated by the
+.Tn YP
+client routines using
.Fn malloc ,
and the result will be stored in the appropriate output value.
-If the invocation of a YP client routine doesn't return an error,
+If the invocation of a
+.Tn YP
+client routine doesn't return an error,
and an output value is not the null pointer, then this memory
should be freed by the user when there is no additional need for
the data stored there.
@@ -125,43 +133,65 @@ must be non-null, NUL-terminated strings. All input strings which also have
a corresponding length parameter cannot be the null pointer unless the
corresponding length value is zero. Such strings need not be NUL-terminated.
.Pp
-All YP lookup calls (the functions
+All
+.Tn YP
+lookup calls (the functions
.Fn yp_all ,
.Fn yp_first ,
.Fn yp_master ,
.Fn yp_match ,
.Fn yp_next ,
.Fn yp_order )
-require a YP domain name and a YP map name. The default domain name may be
+require a
+.Tn YP
+domain name and a
+.Tn YP
+map name. The default domain name may be
obtained by calling
.Fn yp_get_default_domain ,
-and should thus be used before all other YP calls in a client program.
+and should thus be used before all other
+.Tn YP
+calls in a client program.
The value it places
.Pa outdomain
is suitable for use as the
.Pa indomain
-parameter to all subsequent YP calls.
+parameter to all subsequent
+.Tn YP
+calls.
.Pp
-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
+In order for
+.Tn YP
+lookup calls to succeed, the client process must be bound
+to a
+.Tn YP
+server process. The client process need not explicitly bind to
the server, as it happens automatically whenever a lookup occurs.
The function
.Fn yp_bind
-is provided for a backup strategy, e.g. a local file, when a YP server process
+is provided for a backup strategy, e.g. a local file, when a
+.Tn YP
+server process
is not available. Each binding uses one socket descriptor on the client
process, which may be explicitly freed using
.Fn yp_unbind ,
which frees all per-process and per-node resources to bind the domain and
marks the domain unbound.
.Pp
-If, during a YP lookup, an RPC failure occurs, the domain used in the lookup
+If, during a
+.Tn YP
+lookup, an RPC failure occurs, the domain used in the lookup
is automatically marked unbound and the
.Nm ypclnt
layer retries the lookup as long as
.Xr 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
+specified in the lookup, or RPC requests to the
+.Tn YP
+server process fail.
+If an error is not RPC-related, one of the
+.Tn YP
+error codes described below
is returned and control given back to the user code.
.Pp
The
@@ -192,7 +222,9 @@ Of course, the notions of
and
.Dq next
are particular to the
-type of YP map being accessed, and thus there is no guarantee of lexical
+type of
+.Tn YP
+map being accessed, and thus there is no guarantee of lexical
order. The only guarantees provided with
.Fn yp_first
and
@@ -261,7 +293,9 @@ Holds one of the return status values described in
.Nm <rpcsvc/yp_prot.h> :
see
.Fn ypprot_err
-below for a function that will translate YP protocol errors into a
+below for a function that will translate
+.Tn YP
+protocol errors into a
.Nm ypclnt
layer error code as described in
.Nm <rpcsvc/ypclnt.h> .
@@ -295,7 +329,9 @@ something useful or simply ignore it.
.It Fn yp_order
Returns the order number for a map.
.It Fn yp_master
-Returns the hostname for the machine on which the master YP server process for
+Returns the hostname for the machine on which the master
+.Tn YP
+server process for
a map is running.
.It Fn yperr_string
Returns a pointer to a NUL-terminated error string that does not contain a
@@ -303,7 +339,9 @@ Returns a pointer to a NUL-terminated error string that does not contain a
or
.Ql \en .
.It Fn ypprot_err
-Converts a YP protocol error code to a
+Converts a
+.Tn YP
+protocol error code to a
.Nm ypclnt
error code suitable for
.Fn yperr_string .
@@ -318,15 +356,21 @@ return 0 upon success or one of the following error codes upon failure:
.It Bq Er YPERR_BADARGS
The passed arguments to the function are invalid
.It Bq Er YPERR_BADDB
-The YP map that was polled is defective.
+The
+.Tn YP
+map that was polled is defective.
.It Bq Er YPERR_DOMAIN
-Client process cannot bind to server on this YP domain.
+Client process cannot bind to server on this
+.Tn YP
+domain.
.It Bq Er YPERR_KEY
The key passed does not exist.
.It Bq Er YPERR_MAP
There is no such map in the server's domain.
.It Bq Er YPERR_DOM
-The local YP domain is not set.
+The local
+.Tn YP
+domain is not set.
.It Bq Er YPERR_NOMORE
There are no more records in the queried map.
.It Bq Er YPERR_PMAP
@@ -337,7 +381,9 @@ A resource allocation failure occurred.
An RPC failure has occurred. The domain has been marked unbound.
.It Bq Er YPERR_VERS
Client/server version mismatch. If the server is running version 1
-of the YP protocol,
+of the
+.Tn YP
+protocol,
.Fn yp_all
functionality does not exist.
.It Bq Er YPERR_BIND
@@ -346,7 +392,9 @@ Cannot communicate with
.It Bq Er YPERR_YPERR
An internal server or client error has occurred.
.It Bq Er YPERR_YPSERV
-The client cannot communicate with the YP server process.
+The client cannot communicate with the
+.Tn YP
+server process.
.El
.Sh SEE ALSO
.Xr malloc 3 ,