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