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