+++ /dev/null
-.\" -*-nroff-*-
-.TH bres 3 "1 October 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-bres \- background name resolver
-.\" @bres_abort
-.\" @bres_byname
-.\" @bres_byaddr
-.\" @bres_exec
-.\" @bres_init
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/bres.h>"
-
-.BI "void bres_byname(bres_client *" rc ", const char *" name ,
-.BI " void (*" func ")(struct hostent *" h ", void *" p ),
-.BI " void *" p );
-.BI "void bres_byaddr(bres_client *" rc ", struct inaddr " addr ,
-.BI " void (*" func ")(struct hostent *" h ", void *" p ),
-.BI " void *" p );
-.BI "void bres_abort(bres_client *" rc );
-.BI "void bres_exec(const char *" file );
-.BI "void bres_init(sel_state *" sel );
-.fi
-.SH DESCRIPTION
-The
-.B bres.h
-header file declares types and functions for doing translation between
-host names and IP addresses in the background.
-.PP
-The system must be initialized before use by a call to
-.BR bres_init ,
-passing it the address of an I/O multiplexor (see
-.BR sel (3)).
-.PP
-A resolver task is stored in an object of type
-.BR bres_client ,
-the storage for which is allocated by the caller. The object is a
-structure, and its contents are unspecified. The object is initialized
-by one of the name resolution functions
-.B bres_byname
-and
-.BR bres_byaddr .
-Each function is passed the following arguments:
-.TP
-.BI "bres_client *" rc
-Pointer to the client block to initialize and store the resolver job's
-state.
-.TP
-.BI "struct in_addr " addr "\fR (\fBbres_byaddr\fR)"
-.sp -1
-.TP
-.BI "const char *" name "\fR (\fBbres_byname\fR)"
-The IP address or hostname to resolve.
-.TP
-.BI "void (*" func ")(struct hostent *" h ", void *" p )
-A handler function to call when the resolver job is complete.
-.TP
-.BI "void *" p
-A pointer argument to pass to the handler function.
-.PP
-The
-.B bres_client
-block must not be discarded until either the job is complete (i.e., the
-handler function has been called) or
-.B bres_abort
-is called on it.
-.PP
-The handler function is passed either the address of a
-.B "struct hostent"
-structure describing the resolved host, or a null pointer indicating
-failure. The
-.B hostent
-structure is as returned by the standard
-.BR gethostbyname (3)
-and
-.BR gethostbyaddr (3)
-functions. This isn't the most convenient format for the results, but
-it does have the benefit of being standard. Similarly, errors are
-reported through the global
-.B h_errno
-variable.
-.PP
-The function
-.B bres_abort
-cancels a running resolver job. When it returns, the client structure
-is safe to discard.
-.PP
-There are two versions of
-.BR bres .
-The standard one uses a pool of server processes. Incoming resolver
-jobs are passed to an available server, or a new server is started if
-all are busy. There is a maximum number of servers, and jobs are queued
-once this limit is reached. Old servers which have been idle for a
-period of time are killed off. Servers are also killed if they start
-misbehaving or their jobs are aborted.
-.PP
-By default, servers are started simply by calling
-.BR fork (2).
-This can cause undesirably high memory usage in large programs. The
-function
-.B bres_exec
-requests the resolver system to
-.BR exec (2)
-a small dedicated server program to perform name lookups to reduce
-memory consumption. The argument to
-.B bres_exec
-is the full pathname of the server program, or null to accept the
-default set at library configuration time (which is usually correct).
-.PP
-The other implementation of
-.B bres
-uses the
-.B adns
-library to do asynchronous resolution. It can cope with many more
-simultaneous resolver jobs, and doesn't use up external processes. If
-you're using the
-.BR adns -based
-resolver, then the
-.B bres_exec
-function does nothing at all.
-.PP
-For security reasons, when an address is resolved, the hostname received
-is verified by performing a forward lookup. If the forward lookup fails
-to return the expected IP address, an error is reported.
-.SH "SEE ALSO"
-.BR gethostbyname (3),
-.BR gethostbyaddr (3),
-.BR sel (3),
-.BR mLib (3).
-.SH "AUTHOR"
-Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blobdiff