There is important information about booting non-ack images in docs/UPDATING. ack/aout-format images can't be built any more, and booting clang/ELF-format ones is a little different. Updating to the new boot monitor is recommended. Changes in this commit: . drop boot monitor -> allowing dropping ack support . facility to copy ELF boot files to /boot so that old boot monitor can still boot fairly easily, see UPDATING . no more ack-format libraries -> single-case libraries . some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases . drop several ack toolchain commands, but not all support commands (e.g. aal is gone but acksize is not yet). . a few libc files moved to netbsd libc dir . new /bin/date as minix date used code in libc/ . test compile fix . harmonize includes . /usr/lib is no longer special: without ack, /usr/lib plays no kind of special bootstrapping role any more and bootstrapping is done exclusively through packages, so releases depend even less on the state of the machine making them now. . rename nbsd_lib* to lib* . reduce mtree
410 lines
11 KiB
Groff
410 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
|