b6cbf7203b
This patch imports the unmodified current version of NetBSD libc. The NetBSD includes are in /nbsd_include, while the libc code itself is split between lib/nbsd_libc and common/lib/libc.
411 lines
11 KiB
Groff
411 lines
11 KiB
Groff
.\" $NetBSD: ypclnt.3,v 1.24 2010/03/22 19:30:55 joerg Exp $
|
|
.\"
|
|
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Jason R. Thorpe.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd May 21, 1997
|
|
.Dt YPCLNT 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm yp_all ,
|
|
.Nm yp_bind ,
|
|
.Nm yp_first ,
|
|
.Nm yp_get_default_domain ,
|
|
.Nm yp_master ,
|
|
.Nm yp_match ,
|
|
.Nm yp_next ,
|
|
.Nm yp_order ,
|
|
.Nm yp_unbind ,
|
|
.Nm yperr_string ,
|
|
.Nm ypprot_err
|
|
.Nd Interface to the YP subsystem
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In rpc/rpc.h
|
|
.In rpcsvc/ypclnt.h
|
|
.In rpcsvc/yp_prot.h
|
|
.Ft int
|
|
.Fn yp_all "const char *indomain" "const char *inmap" "struct ypall_callback *incallback"
|
|
.Ft int
|
|
.Fn yp_bind "const char *dom"
|
|
.Ft int
|
|
.Fn yp_first "const char *indomain" "const char *inmap" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen"
|
|
.Ft int
|
|
.Fn yp_get_default_domain "char **outdomain"
|
|
.Ft int
|
|
.Fn yp_master "const char *indomain" "const char *inmap" "char **outname"
|
|
.Ft int
|
|
.Fn yp_match "const char *indomain" "const char *inmap" "const char *inkey" "int inkeylen" "char **outval" "int *outvallen"
|
|
.Ft int
|
|
.Fn yp_next "const char *indomain" "const char *inmap" "const char *inkey" "int inkeylen" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen"
|
|
.Ft int
|
|
.Fn yp_order "const char *indomain" "const char *inmap" "int *outorder"
|
|
.Ft void
|
|
.Fn yp_unbind "const char *dom"
|
|
.Ft char *
|
|
.Fn yperr_string "int incode"
|
|
.Ft int
|
|
.Fn ypprot_err "unsigned int incode"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm ypclnt
|
|
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
|
|
.Pa in
|
|
and output values begin with
|
|
.Pa out .
|
|
.Pp
|
|
Any output values of type
|
|
.Em char **
|
|
should be the addresses of uninitialized character pointers.
|
|
These values will be reset to the null pointer (unless the address
|
|
itself is the null pointer, in which case the error
|
|
.Er YPERR_BADARGS
|
|
will be returned).
|
|
If necessary,
|
|
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
|
|
.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.
|
|
For
|
|
.Pa outkey
|
|
and
|
|
.Pa outval ,
|
|
two extra bytes of memory are allocated for a
|
|
.Ql \en
|
|
and
|
|
.Ql \e0 ,
|
|
which are not
|
|
reflected in the values of
|
|
.Pa outkeylen
|
|
or
|
|
.Pa outvallen .
|
|
.Pp
|
|
All occurrences of
|
|
.Pa indomain
|
|
and
|
|
.Pa inmap
|
|
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
|
|
.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
|
|
.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
|
|
.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
|
|
.Tn YP
|
|
calls.
|
|
.Pp
|
|
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
|
|
.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
|
|
.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
|
|
.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
|
|
.Nm ypclnt
|
|
suite provides the following functionality:
|
|
.Bl -tag -width yp_match()xx
|
|
.It Fn yp_match
|
|
Provides the value associated with the given key.
|
|
.It Fn yp_first
|
|
Provides the first key-value pair from the given map in the named domain.
|
|
.It Fn yp_next
|
|
Provides the next key-value pair in the given map.
|
|
To obtain the second pair,
|
|
the
|
|
.Pa inkey
|
|
value should be the
|
|
.Pa outkey
|
|
value provided by the initial call to
|
|
.Fn yp_first .
|
|
In the general case, the next key-value pair may be obtained by using the
|
|
.Pa outkey
|
|
value from the previous call to
|
|
.Fn yp_next
|
|
as the value for
|
|
.Pa inkey .
|
|
.Pp
|
|
Of course, the notions of
|
|
.Dq first
|
|
and
|
|
.Dq next
|
|
are particular to the
|
|
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
|
|
.Fn yp_next ,
|
|
providing that the same map on the same server is polled repeatedly until
|
|
.Fn 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.
|
|
.Pp
|
|
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
|
|
.Fn yp_all
|
|
provides a better solution for reading all of the entries in a particular map.
|
|
.It Fn 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
|
|
.Nm ypclnt
|
|
suite, 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.
|
|
.Fn yp_all
|
|
returns after the entire transaction is complete, or the
|
|
.Pa foreach
|
|
function decides that it does not want any more key-value pairs.
|
|
The third argument to
|
|
.Fn yp_all
|
|
is:
|
|
.Bd -literal -offset indent
|
|
struct ypall_callback *incallback {
|
|
int (*foreach)();
|
|
char *data;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Em char *data
|
|
argument is an opaque pointer for use by the callback function.
|
|
The
|
|
.Pa foreach
|
|
function should return non-zero when it no longer wishes to process
|
|
key-value pairs, at which time
|
|
.Fn yp_all
|
|
returns a value of 0, and is called with the following arguments:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
int foreach (
|
|
int instatus,
|
|
char *inkey,
|
|
int inkeylen,
|
|
char *inval,
|
|
int invallen,
|
|
char *indata
|
|
);
|
|
.Ed
|
|
.Pp
|
|
Where:
|
|
.Bl -tag -width "inkey, inval"
|
|
.It Fa instatus
|
|
Holds one of the return status values described in
|
|
.In rpcsvc/yp_prot.h :
|
|
see
|
|
.Fn ypprot_err
|
|
below for a function that will translate
|
|
.Tn YP
|
|
protocol errors into a
|
|
.Nm ypclnt
|
|
layer error code as described in
|
|
.In rpcsvc/ypclnt.h .
|
|
.It Fa inkey, inval
|
|
The key and value arguments are somewhat different here than described
|
|
above.
|
|
In this case, the memory pointed to by
|
|
.Fa inkey
|
|
and
|
|
.Fa inval
|
|
is private to
|
|
.Fn yp_all ,
|
|
and is overwritten with each subsequent key-value pair, thus the
|
|
.Pa 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
|
|
.Ql \en
|
|
or
|
|
.Ql \e0
|
|
in the map, then they will not be terminated as such when given to the
|
|
.Pa foreach
|
|
function, either.
|
|
.It Fa indata
|
|
This is the contents of the
|
|
.Pa incallback-\*[Gt]data
|
|
element of the callback structure.
|
|
It is provided as a means to share state between the
|
|
.Pa foreach
|
|
function and the user code.
|
|
Its use is completely optional: cast it to
|
|
something useful or simply ignore it.
|
|
.El
|
|
.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
|
|
.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
|
|
.Ql \&.
|
|
or
|
|
.Ql \en .
|
|
.It Fn ypprot_err
|
|
Converts a
|
|
.Tn YP
|
|
protocol error code to a
|
|
.Nm ypclnt
|
|
error code suitable for
|
|
.Fn yperr_string .
|
|
.El
|
|
.Sh RETURN VALUES
|
|
All functions in the
|
|
.Nm ypclnt
|
|
suite which are of type
|
|
.Em int
|
|
return 0 upon success or one of the following error codes upon failure:
|
|
.Bl -tag -width "YPERR_BADARGS "
|
|
.It Bq Er YPERR_BADARGS
|
|
The passed arguments to the function are invalid.
|
|
.It Bq Er YPERR_BADDB
|
|
The
|
|
.Tn YP
|
|
map that was polled is defective.
|
|
.It Bq Er YPERR_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
|
|
.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
|
|
Cannot communicate with portmapper (see
|
|
.Xr rpcbind 8 ) .
|
|
.It Bq Er YPERR_RESRC
|
|
A resource allocation failure occurred.
|
|
.It Bq Er YPERR_RPC
|
|
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
|
|
.Tn YP
|
|
protocol,
|
|
.Fn yp_all
|
|
functionality does not exist.
|
|
.It Bq Er YPERR_BIND
|
|
Cannot communicate with
|
|
.Xr ypbind 8 .
|
|
.It Bq Er YPERR_YPERR
|
|
An internal server or client error has occurred.
|
|
.It Bq Er YPERR_YPSERV
|
|
The client cannot communicate with the
|
|
.Tn YP
|
|
server process.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr malloc 3 ,
|
|
.Xr yp 8 ,
|
|
.Xr ypbind 8 ,
|
|
.Xr ypserv 8
|
|
.Sh AUTHORS
|
|
.An Theo De Raadt
|