chiark / gitweb /
cleanup: All the whitespace fixes, all at once.
[mLib] / man / bres.3
1 .\" -*-nroff-*-
2 .TH bres 3 "1 October 1999" "Straylight/Edgeware" "mLib utilities library"
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 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.
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
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
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@distorted.org.uk>