231 lines
6.2 KiB
Groff
231 lines
6.2 KiB
Groff
.TH arlib 3
|
|
.SH NAME
|
|
ar_answer, ar_close, ar_delete, ar_gethostbyname, ar_gethostbyaddr,
|
|
ar_init, ar_open, ar_timeout - Asynchronous DNS library routines
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include "arlib.h"
|
|
|
|
.B struct hostent *ar_answer(dataptr, size)
|
|
.B char *dataptr;
|
|
.B int size;
|
|
|
|
.B void ar_close();
|
|
|
|
.B int ar_delete(dataptr, size)
|
|
.B char *dataptr;
|
|
.B int size;
|
|
|
|
.B int ar_gethostbyname(name, dataptr, size)
|
|
.B char *name;
|
|
.B char *dataptr;
|
|
.B int size;
|
|
|
|
.B int ar_gethostbyaddr(name, dataptr, size)
|
|
.B char *name;
|
|
.B char *dataptr;
|
|
.B int size;
|
|
|
|
.B int ar_init(flags)
|
|
.B int flags;
|
|
|
|
.B int ar_open();
|
|
|
|
.B long ar_timeout(time, dataptr, size)
|
|
.B long time;
|
|
.B char *dataptr;
|
|
.B int size;
|
|
.fi
|
|
.SH DESCRIPTION
|
|
|
|
.PP
|
|
This small library of DNS routines is intended to provide an
|
|
asynchronous interface to performing hostname and IP number lookups.
|
|
Only lookups of Internet domain are handled as yet. To use this
|
|
set of routines properly, the presence of the
|
|
.B "BIND 4.8"
|
|
resolve
|
|
libraries is required (or any library derived from it).
|
|
.PP
|
|
This library should be used in conjunction with
|
|
.B select(2)
|
|
to wait for
|
|
the name server's reply to arrive or the lookup to timeout.
|
|
.PP
|
|
To open a fd for talking to the name server, either
|
|
.B ar_open()
|
|
or
|
|
ar_init()
|
|
must be used.
|
|
.B ar_open()
|
|
will open either a datagram socket
|
|
or a virtual circuit with the name server, depending on the flags
|
|
set in the _res structure (see
|
|
.B resolv(5)
|
|
). In both cases, if the socket
|
|
|
|
> i
|
|
.B ar_init()
|
|
is
|
|
used to both open the socket (as in
|
|
.B ar_open()
|
|
) and initialize the
|
|
queues used by this library. The values recognized as parameters to
|
|
.B ar_init()
|
|
are:
|
|
|
|
.RS
|
|
#define ARES_INITLIST 1
|
|
.RE
|
|
.RS
|
|
#define ARES_CALLINIT 2
|
|
.RE
|
|
.RS
|
|
#define ARES_INITSOCK 4
|
|
.RE
|
|
.RS
|
|
#define ARES_INITDEBG 8
|
|
.RE
|
|
|
|
ARES_INITLIST initializes the list of queries waiting for replies.
|
|
ARES_CALLINIT is a flag which when set causes
|
|
.B res_init()
|
|
to be called.
|
|
ARES_INITSOCK will close the current socket if it is open and call
|
|
.B ar_open()
|
|
to open a new one, returning the fd for that socket.
|
|
ARES_INITDEBG sets the RES_DEBUG flag of the
|
|
.B _res
|
|
structure.
|
|
ARES_INITCACH is as yet, unused and is for future use where the library
|
|
keeps its own cache of replies.
|
|
|
|
To send a query about either a hostname or an IP number,
|
|
.B ar_gethostbyname()
|
|
and
|
|
.B ar_gethostbyaddr()
|
|
must be used. Each takes
|
|
either a pointer to the hostname or the IP number respectively for use
|
|
when making the query. In addition to this, both (optionally) can be
|
|
passed a pointer to data, dataptr, with the size also passed which can
|
|
be used for identifying individual queries. A copy of the area pointed
|
|
to is made if dataptr is non NULL and size is non zero. These functions
|
|
will always return NULL unless the answer to the query is found in
|
|
internal caches. A new flag, RES_CHECKPTR is checked during the
|
|
processing of answers for
|
|
.B ar_gethostbyname()
|
|
which will automatically
|
|
cause a reverse lookup to be queued, causing a failure if that reply
|
|
differs from the original.
|
|
|
|
To check for a query,
|
|
.B ar_answer()
|
|
is called with a pointer to an area
|
|
of memory which is sufficient to hold what was originally passed via
|
|
.B ar_gethostbyname()
|
|
or
|
|
.B ar_gethostbyaddr()
|
|
through dataptr. If an answer
|
|
is found, a pointer to the host information is returned and the data
|
|
segment copied if dataptr is non NULL and it was originally passed. The
|
|
size of the copied data is the smaller of the passed size and that of
|
|
original data stored.
|
|
|
|
To expire old queries,
|
|
.B ar_timeout()
|
|
is called with the 'current' time
|
|
(or the time for which you want to do timeouts for). If a queue entry
|
|
is too old, it will be expired when it has exhausted all available avenues
|
|
for lookups and the data segment for the expired query copied into
|
|
dataptr. The size of the copied data is the smaller of the passed size
|
|
and that of the original stored data. Only 1 entry is thus expired with
|
|
each call, requiring that it be called immediately after an expiration
|
|
to check for others. In addition to expiring lookups,
|
|
.B ar_timeout()
|
|
also
|
|
triggers resends of queries and the searching of the domain tree for the
|
|
host, the latter works from the
|
|
.B _res
|
|
structure of
|
|
.B resolv(5).
|
|
|
|
To delete entries from the queue,
|
|
.B ar_delete()
|
|
can be used and by
|
|
passing the pointer and size of the data segment, all queries have their
|
|
data segments checked (if present) for an exact match, being deleted if
|
|
and only if there is a match. A NULL pointer passed to ar_deleted()
|
|
matches all queries which were called with a NULL dataptr parameter.
|
|
The amount of data compared is the smaller of the size passed and that
|
|
of the data stored for the queue entry being compared.
|
|
|
|
To close a socket opened by
|
|
.B ar_open()
|
|
,
|
|
.B ar_close()
|
|
should be used so
|
|
that it is closed and also marked closed within this library.
|
|
|
|
|
|
.SH DIAGNOSIS
|
|
|
|
.B ar_open()
|
|
returns -1 if a socket isn't open and could not be opened;
|
|
otherwise returns the current fd open or the fd it opened.
|
|
|
|
.B ar_init()
|
|
returns -1 for any errors, the value returned by
|
|
.B res_init()
|
|
if
|
|
.B res_init()
|
|
was called, the return value for
|
|
.B ar_open()
|
|
if that was
|
|
called or the current socket open if 0 is passed and a socket is open.
|
|
If neither
|
|
.B res_init()
|
|
or
|
|
.B ar_open()
|
|
are called and the flags are non-zero, -2 is returned.
|
|
|
|
.B ar_gethostbyaddr()
|
|
and
|
|
.B ar_gethostbyname()
|
|
will always return NULL in this version but may return a pointer to a hostent
|
|
structure if a cache is being used and the answer is found in the cache.
|
|
|
|
.B ar_answer()
|
|
returns NULL if the answer is either not found or the
|
|
query returned an error and another attempt at a lookup is attempted.
|
|
If an answer was found, it returned a pointer to this structure and
|
|
the contents of the data segment copied over.
|
|
|
|
.B ar_timeout()
|
|
returns the time when it should be called next or 0 if
|
|
there are no queries in the queue to be checked later. If any queries
|
|
are expired, the data segment is copied over if dataptr is non NULL.
|
|
|
|
.B ar_delete()
|
|
returns the number of entries that were found to match
|
|
and consequently deleted.
|
|
|
|
.SH SEE ALSO
|
|
|
|
gethostbyaddr(3), gethostbyname(3), resolv(5)
|
|
|
|
.SH FILES
|
|
.nf
|
|
arlib.h
|
|
/usr/include/resolv.h
|
|
/usr/include/arpa/nameser.h
|
|
/etc/resolv.conf
|
|
|
|
.SH BUGS
|
|
|
|
The results of a successful call to ar_answer() destroy the structure
|
|
for any previous calls.
|
|
|
|
.SH AUTHOR
|
|
|
|
Darren Reed. Email address: avalon@coombs.anu.edu.au
|