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

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