2 .TH bres 3 "1 October 1999" "Straylight/Edgeware" "mLib utilities library"
4 bres \- background name resolver
12 .B "#include <mLib/bres.h>"
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 );
22 .BI "void bres_abort(bres_client *" rc );
23 .BI "void bres_exec(const char *" file );
24 .BI "void bres_init(sel_state *" sel );
29 header file declares types and functions for doing translation between
30 host names and IP addresses in the background.
32 The system must be initialized before use by a call to
34 passing it the address of an I/O multiplexor (see
37 A resolver task is stored in an object of type
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
45 Each function is passed the following arguments:
47 .BI "bres_client *" rc
48 Pointer to the client block to initialize and store the resolver job's
51 .BI "struct in_addr " addr "\fR (\fBbres_byaddr\fR)"
54 .BI "const char *" name "\fR (\fBbres_byname\fR)"
55 The IP address or hostname to resolve.
57 .BI "void (*" func ")(struct hostent *" h ", void *" p )
58 A handler function to call when the resolver job is complete.
61 A pointer argument to pass to the handler function.
65 block must not be discarded until either the job is complete (i.e., the
66 handler function has been called) or
70 The handler function is passed either the address of a
72 structure describing the resolved host, or a null pointer indicating
75 structure is as returned by the standard
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
87 cancels a running resolver job. When it returns, the client structure
90 There are two versions of
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.
99 By default, servers are started simply by calling
101 This can cause undesirably high memory usage in large programs. The
104 requests the resolver system to
106 a small dedicated server program to perform name lookups to reduce
107 memory consumption. The argument to
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).
112 The other implementation of
116 library to do asynchronous resolution. It can cope with many more
117 simultaneous resolver jobs, and doesn't use up external processes. If
122 function does nothing at all.
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.
128 .BR gethostbyname (3),
129 .BR gethostbyaddr (3),
133 Mark Wooding, <mdw@distorted.org.uk>