diff options
Diffstat (limited to 'arlib/arlib.3')
| -rw-r--r-- | arlib/arlib.3 | 230 |
1 files changed, 0 insertions, 230 deletions
diff --git a/arlib/arlib.3 b/arlib/arlib.3 deleted file mode 100644 index afdc02f4d5bd..000000000000 --- a/arlib/arlib.3 +++ /dev/null @@ -1,230 +0,0 @@ -.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 |