83856dde |
1 | .\" -*-nroff-*- |
fbf20b5b |
2 | .TH bres 3 "1 October 1999" "Straylight/Edgeware" "mLib utilities library" |
83856dde |
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 |
14d7100d |
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. |
83856dde |
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 |
14d7100d |
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 |
83856dde |
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> |