/contrib/ntp/arlib/arlib.3
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 230 lines · 198 code · 32 blank · 0 comment · 0 complexity · 4dd7016ff728a987ad1ccbcee830e55d MD5 · raw file
- .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