chiark - git - mdw - mLib/blob - sel/bres.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for background name resolution
   4 .\"
   5 .\" (c) 1999, 2001, 2003, 2005, 2007, 2009, 2023, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH bres 3mLib "1 October 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @bres_abort
  33 .\" @bres_byname
  34 .\" @bres_byaddr
  35 .\" @bres_exec
  36 .\" @bres_init
  37 .
  38 .\"--------------------------------------------------------------------------
  39 .SH NAME
  40 bres \- background name resolver
  41 .
  42 .\"--------------------------------------------------------------------------
  43 .SH SYNOPSIS
  44 .
  45 .nf
  46 .B "#include <mLib/bres.h>"
  47 .PP
  48 .B "typedef struct { ...\& } bres_client;"
  49 .PP
  50 .ta \w'\fBvoid bres_byname('u
  51 .BI "void bres_byname(bres_client *" rc ", const char *" name ,
  52 .BI "   void (*" func ")(struct hostent *" h ", void *" p ),
  53 .BI "   void *" p );
  54 .ta \w'\fBvoid bres_byaddr('u
  55 .BI "void bres_byaddr(res_client *" rc ", struct inaddr " addr ,
  56 .BI "   void (*" func ")(struct hostent *" h ", void *" p ),
  57 .BI "   void *" p );
  58 .BI "void bres_abort(bres_client *" rc );
  59 .BI "void bres_exec(const char *" file );
  60 .BI "void bres_init(sel_state *" sel );
  61 .fi
  62 .
  63 .\"--------------------------------------------------------------------------
  64 .SH DESCRIPTION
  65 .
  66 The
  67 .B bres.h
  68 header file declares types and functions for doing translation between
  69 host names and IP addresses in the background.
  70 .PP
  71 The system must be initialized before use by a call to
  72 .BR bres_init ,
  73 passing it the address of an I/O multiplexor (see
  74 .BR sel (3)).
  75 .PP
  76 A resolver task is stored in an object of type
  77 .BR bres_client ,
  78 the storage for which is allocated by the caller.  The object is a
  79 structure, and its contents are unspecified.  The object is initialized
  80 by one of the name resolution functions
  81 .B bres_byname
  82 and
  83 .BR bres_byaddr .
  84 Each function is passed the following arguments:
  85 .TP
  86 .BI "bres_client *" rc
  87 Pointer to the client block to initialize and store the resolver job's
  88 state.
  89 .TP
  90 .BR "struct in_addr " \fIaddr ""  " (" bres_byaddr )
  91 .ie t .sp -0.4v
  92 .el .sp -1v
  93 .TP
  94 .BR "const char *" \fIname ""  " (" bres_byname )
  95 The IP address or hostname to resolve.
  96 .TP
  97 .BI "void (*" func ")(struct hostent *" h ", void *" p )
  98 A handler function to call when the resolver job is complete.
  99 .TP
 100 .BI "void *" p
 101 A pointer argument to pass to the handler function.
 102 .PP
 103 The
 104 .B bres_client
 105 block must not be discarded until either the job is complete (i.e., the
 106 handler function has been called) or
 107 .B bres_abort
 108 is called on it.
 109 .PP
 110 The handler function is passed either the address of a
 111 .B "struct hostent"
 112 structure describing the resolved host, or a null pointer indicating
 113 failure.  The
 114 .B hostent
 115 structure is as returned by the standard
 116 .BR gethostbyname (3)
 117 and
 118 .BR gethostbyaddr (3)
 119 functions.  This isn't the most convenient format for the results, but
 120 it does have the benefit of being standard.  Similarly, errors are
 121 reported through the global
 122 .B h_errno
 123 variable.
 124 .PP
 125 The function
 126 .B bres_abort
 127 cancels a running resolver job.  When it returns, the client structure
 128 is safe to discard.
 129 .PP
 130 There are two versions of
 131 .BR bres .
 132 The standard one uses a pool of server processes.  Incoming resolver
 133 jobs are passed to an available server, or a new server is started if
 134 all are busy.  There is a maximum number of servers, and jobs are queued
 135 once this limit is reached.  Old servers which have been idle for a
 136 period of time are killed off.  Servers are also killed if they start
 137 misbehaving or their jobs are aborted.
 138 .PP
 139 By default, servers are started simply by calling
 140 .BR fork (2).
 141 This can cause undesirably high memory usage in large programs.  The
 142 function
 143 .B bres_exec
 144 requests the resolver system to
 145 .BR exec (2)
 146 a small dedicated server program to perform name lookups to reduce
 147 memory consumption.  The argument to
 148 .B bres_exec
 149 is the full pathname of the server program, or null to accept the
 150 default set at library configuration time (which is usually correct).
 151 .PP
 152 The other implementation of
 153 .B bres
 154 uses the
 155 .B adns
 156 library to do asynchronous resolution.  It can cope with many more
 157 simultaneous resolver jobs, and doesn't use up external processes.  If
 158 you're using the
 159 .BR adns -based
 160 resolver, then the
 161 .B bres_exec
 162 function does nothing at all.
 163 .PP
 164 For security reasons, when an address is resolved, the hostname received
 165 is verified by performing a forward lookup.  If the forward lookup fails
 166 to return the expected IP address, an error is reported.
 167 .
 168 .\"--------------------------------------------------------------------------
 169 .SH "SEE ALSO"
 170 .
 171 .BR gethostbyname (3),
 172 .BR gethostbyaddr (3),
 173 .BR sel (3),
 174 .BR mLib (3).
 175 .
 176 .\"--------------------------------------------------------------------------
 177 .SH "AUTHOR"
 178 .
 179 Mark Wooding, <mdw@distorted.org.uk>
 180 .
 181 .\"----- That's all, folks --------------------------------------------------