@@@ much mess, mostly manpages

[mLib] / sel / bres.3.in

.\" -*-nroff-*-
.\"
.\" Manual for background name resolution
.\"
.\" (c) 1999, 2001, 2003, 2005, 2007, 2009, 2023, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH bres 3mLib "1 October 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @bres_abort
.\" @bres_byname
.\" @bres_byaddr
.\" @bres_exec
.\" @bres_init
.
.\"--------------------------------------------------------------------------
.SH NAME
bres \- background name resolver
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/bres.h>"
.PP
.B "typedef struct { ...\& } bres_client;"
.PP
.ta \w'\fBvoid bres_byname('u
.BI "void bres_byname(bres_client *" rc ", const char *" name ,
.BI "	void (*" func ")(struct hostent *" h ", void *" p ),
.BI "	void *" p );
.ta \w'\fBvoid bres_byaddr('u
.BI "void bres_byaddr(res_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
.BR "struct in_addr " \fIaddr ""  " (" bres_byaddr )
.ie t .sp -0.4v
.el .sp -1v
.TP
.BR "const char *" \fIname ""  " (" bres_byname )
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>
.
.\"----- That's all, folks --------------------------------------------------