--- /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