| 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 | .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 | There are two versions of |
| 89 | .BR bres . |
| 90 | The standard one uses a pool of server processes. Incoming resolver |
| 91 | jobs are passed to an available server, or a new server is started if |
| 92 | all are busy. There is a maximum number of servers, and jobs are queued |
| 93 | once this limit is reached. Old servers which have been idle for a |
| 94 | period of time are killed off. Servers are also killed if they start |
| 95 | misbehaving or their jobs are aborted. |
| 96 | .PP |
| 97 | By default, servers are started simply by calling |
| 98 | .BR fork (2). |
| 99 | This can cause undesirably high memory usage in large programs. The |
| 100 | function |
| 101 | .B bres_exec |
| 102 | requests the resolver system to |
| 103 | .BR exec (2) |
| 104 | a small dedicated server program to perform name lookups to reduce |
| 105 | memory consumption. The argument to |
| 106 | .B bres_exec |
| 107 | is the full pathname of the server program, or null to accept the |
| 108 | default set at library configuration time (which is usually correct). |
| 109 | .PP |
| 110 | The other implementation of |
| 111 | .B bres |
| 112 | uses the |
| 113 | .B adns |
| 114 | library to do asynchronous resolution. It can cope with many more |
| 115 | simultaneous resolver jobs, and doesn't use up external processes. If |
| 116 | you're using the |
| 117 | .BR adns -based |
| 118 | resolver, then the |
| 119 | .B bres_exec |
| 120 | function does nothing at all. |
| 121 | .PP |
| 122 | For security reasons, when an address is resolved, the hostname received |
| 123 | is verified by performing a forward lookup. If the forward lookup fails |
| 124 | to return the expected IP address, an error is reported. |
| 125 | .SH "SEE ALSO" |
| 126 | .BR gethostbyname (3), |
| 127 | .BR gethostbyaddr (3), |
| 128 | .BR sel (3), |
| 129 | .BR mLib (3). |
| 130 | .SH "AUTHOR" |
| 131 | Mark Wooding, <mdw@nsict.org> |