83856dde |
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> |