Commit | Line | Data |
---|---|---|
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 | ||
4729aa69 MW |
14 | .B "typedef struct { ...\& } bres_client;" |
15 | ||
adec5584 MW |
16 | .ta \w'\fBvoid bres_byname('u |
17 | .BI "void bres_byname(bres_client *" rc ", const char *" name , | |
18 | .BI " void (*" func ")(struct hostent *" h ", void *" p ), | |
19 | .BI " void *" p ); | |
20 | .ta \w'\fBvoid bres_byaddr('u | |
21 | .BI "void bres_byaddr(res_client *" rc ", struct inaddr " addr , | |
22 | .BI " void (*" func ")(struct hostent *" h ", void *" p ), | |
23 | .BI " void *" p ); | |
83856dde | 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 | |
adec5584 MW |
53 | .BR "struct in_addr " \fIaddr "" " (" bres_byaddr ) |
54 | .ie t .sp -0.4v | |
55 | .el .sp -1v | |
83856dde | 56 | .TP |
adec5584 | 57 | .BR "const char *" \fIname "" " (" bres_byname ) |
83856dde | 58 | The IP address or hostname to resolve. |
59 | .TP | |
60 | .BI "void (*" func ")(struct hostent *" h ", void *" p ) | |
61 | A handler function to call when the resolver job is complete. | |
62 | .TP | |
63 | .BI "void *" p | |
64 | A pointer argument to pass to the handler function. | |
65 | .PP | |
66 | The | |
67 | .B bres_client | |
68 | block must not be discarded until either the job is complete (i.e., the | |
69 | handler function has been called) or | |
70 | .B bres_abort | |
71 | is called on it. | |
72 | .PP | |
73 | The handler function is passed either the address of a | |
74 | .B "struct hostent" | |
75 | structure describing the resolved host, or a null pointer indicating | |
76 | failure. The | |
77 | .B hostent | |
78 | structure is as returned by the standard | |
79 | .BR gethostbyname (3) | |
80 | and | |
81 | .BR gethostbyaddr (3) | |
82 | functions. This isn't the most convenient format for the results, but | |
83 | it does have the benefit of being standard. Similarly, errors are | |
84 | reported through the global | |
85 | .B h_errno | |
86 | variable. | |
87 | .PP | |
88 | The function | |
89 | .B bres_abort | |
90 | cancels a running resolver job. When it returns, the client structure | |
91 | is safe to discard. | |
92 | .PP | |
d4efbcd9 | 93 | There are two versions of |
14d7100d | 94 | .BR bres . |
95 | The standard one uses a pool of server processes. Incoming resolver | |
96 | jobs are passed to an available server, or a new server is started if | |
97 | all are busy. There is a maximum number of servers, and jobs are queued | |
98 | once this limit is reached. Old servers which have been idle for a | |
99 | period of time are killed off. Servers are also killed if they start | |
100 | misbehaving or their jobs are aborted. | |
83856dde | 101 | .PP |
102 | By default, servers are started simply by calling | |
103 | .BR fork (2). | |
104 | This can cause undesirably high memory usage in large programs. The | |
105 | function | |
106 | .B bres_exec | |
107 | requests the resolver system to | |
108 | .BR exec (2) | |
109 | a small dedicated server program to perform name lookups to reduce | |
110 | memory consumption. The argument to | |
111 | .B bres_exec | |
112 | is the full pathname of the server program, or null to accept the | |
113 | default set at library configuration time (which is usually correct). | |
114 | .PP | |
14d7100d | 115 | The other implementation of |
116 | .B bres | |
117 | uses the | |
118 | .B adns | |
119 | library to do asynchronous resolution. It can cope with many more | |
120 | simultaneous resolver jobs, and doesn't use up external processes. If | |
121 | you're using the | |
122 | .BR adns -based | |
123 | resolver, then the | |
124 | .B bres_exec | |
125 | function does nothing at all. | |
126 | .PP | |
83856dde | 127 | For security reasons, when an address is resolved, the hostname received |
128 | is verified by performing a forward lookup. If the forward lookup fails | |
129 | to return the expected IP address, an error is reported. | |
130 | .SH "SEE ALSO" | |
131 | .BR gethostbyname (3), | |
132 | .BR gethostbyaddr (3), | |
133 | .BR sel (3), | |
134 | .BR mLib (3). | |
135 | .SH "AUTHOR" | |
9b5ac6ff | 136 | Mark Wooding, <mdw@distorted.org.uk> |