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

   1 .\" -*-nroff-*-
   2 .TH bres 3 "1 October 1999" "Straylight/Edgeware" "mLib utilities library"
   3 .SH NAME
   4 bres \- background name resolver
   5 .\" @bres_abort
   6 .\" @bres_byname
   7 .\" @bres_byaddr
   8 .\" @bres_exec
   9 .\" @bres_init
  10 .SH SYNOPSIS
  11 .nf
  12 .B "#include <mLib/bres.h>"
  13
  14 .B "typedef struct { ...\& } bres_client;"
  15
  16 .ds mT \fBvoid bres_byname(
  17 .BI "\*(mTbres_client *" rc ", const char *" name ,
  18 .BI "\h'\w'\*(mT'u'void (*" func ")(struct hostent *" h ", void *" p ),
  19 .BI "\h'\w'\*(mT'u'void *" p );
  20 .ds mT \fBvoid bres_byaddr(
  21 .BI "\*(mTbres_client *" rc ", struct inaddr " addr ,
  22 .BI "\h'\w'\*(mT'u'void (*" func ")(struct hostent *" h ", void *" p ),
  23 .BI "\h'\w'\*(mT'u'void *" p );
  24 .BI "void bres_abort(bres_client *" rc );
  25 .BI "void bres_exec(const char *" file );
  26 .BI "void bres_init(sel_state *" sel );
  27 .fi
  28 .SH DESCRIPTION
  29 The
  30 .B bres.h
  31 header file declares types and functions for doing translation between
  32 host names and IP addresses in the background.
  33 .PP
  34 The system must be initialized before use by a call to
  35 .BR bres_init ,
  36 passing it the address of an I/O multiplexor (see
  37 .BR sel (3)).
  38 .PP
  39 A resolver task is stored in an object of type
  40 .BR bres_client ,
  41 the storage for which is allocated by the caller.  The object is a
  42 structure, and its contents are unspecified.  The object is initialized
  43 by one of the name resolution functions
  44 .B bres_byname
  45 and
  46 .BR bres_byaddr .
  47 Each function is passed the following arguments:
  48 .TP
  49 .BI "bres_client *" rc
  50 Pointer to the client block to initialize and store the resolver job's
  51 state.
  52 .TP
  53 .BI "struct in_addr " addr "\fR (\fBbres_byaddr\fR)"
  54 .sp -1
  55 .TP
  56 .BI "const char *" name "\fR (\fBbres_byname\fR)"
  57 The IP address or hostname to resolve.
  58 .TP
  59 .BI "void (*" func ")(struct hostent *" h ", void *" p )
  60 A handler function to call when the resolver job is complete.
  61 .TP
  62 .BI "void *" p
  63 A pointer argument to pass to the handler function.
  64 .PP
  65 The
  66 .B bres_client
  67 block must not be discarded until either the job is complete (i.e., the
  68 handler function has been called) or
  69 .B bres_abort
  70 is called on it.
  71 .PP
  72 The handler function is passed either the address of a
  73 .B "struct hostent"
  74 structure describing the resolved host, or a null pointer indicating
  75 failure.  The
  76 .B hostent
  77 structure is as returned by the standard
  78 .BR gethostbyname (3)
  79 and
  80 .BR gethostbyaddr (3)
  81 functions.  This isn't the most convenient format for the results, but
  82 it does have the benefit of being standard.  Similarly, errors are
  83 reported through the global
  84 .B h_errno
  85 variable.
  86 .PP
  87 The function
  88 .B bres_abort
  89 cancels a running resolver job.  When it returns, the client structure
  90 is safe to discard.
  91 .PP
  92 There are two versions of
  93 .BR bres .
  94 The standard one uses a pool of server processes.  Incoming resolver
  95 jobs are passed to an available server, or a new server is started if
  96 all are busy.  There is a maximum number of servers, and jobs are queued
  97 once this limit is reached.  Old servers which have been idle for a
  98 period of time are killed off.  Servers are also killed if they start
  99 misbehaving or their jobs are aborted.
 100 .PP
 101 By default, servers are started simply by calling
 102 .BR fork (2).
 103 This can cause undesirably high memory usage in large programs.  The
 104 function
 105 .B bres_exec
 106 requests the resolver system to
 107 .BR exec (2)
 108 a small dedicated server program to perform name lookups to reduce
 109 memory consumption.  The argument to
 110 .B bres_exec
 111 is the full pathname of the server program, or null to accept the
 112 default set at library configuration time (which is usually correct).
 113 .PP
 114 The other implementation of
 115 .B bres
 116 uses the
 117 .B adns
 118 library to do asynchronous resolution.  It can cope with many more
 119 simultaneous resolver jobs, and doesn't use up external processes.  If
 120 you're using the
 121 .BR adns -based
 122 resolver, then the
 123 .B bres_exec
 124 function does nothing at all.
 125 .PP
 126 For security reasons, when an address is resolved, the hostname received
 127 is verified by performing a forward lookup.  If the forward lookup fails
 128 to return the expected IP address, an error is reported.
 129 .SH "SEE ALSO"
 130 .BR gethostbyname (3),
 131 .BR gethostbyaddr (3),
 132 .BR sel (3),
 133 .BR mLib (3).
 134 .SH "AUTHOR"
 135 Mark Wooding, <mdw@distorted.org.uk>