X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib/blobdiff_plain/dd3c57bc8cac59e0d657ee665ce462988d27d714..18c831dcd0ae4d660c70ccac69d27ed2a97851be:/sel/bres.3

diff --git a/sel/bres.3 b/sel/bres.3
new file mode 100644
index 0000000..ca58165
--- /dev/null
+++ b/sel/bres.3
@@ -0,0 +1,131 @@
+.\" -*-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>