From 3aead6a988b9685b6ad484fa2798f81e2a76f2d8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 30 Sep 2016 11:05:50 +0200 Subject: [PATCH] man pages: minor formatting edits --- ares_cancel.3 | 6 ++-- ares_destroy.3 | 8 +++--- ares_fds.3 | 47 ++++++++++++-------------------- ares_init_options.3 | 21 ++++++++++++++ ares_library_cleanup.3 | 8 ++---- ares_process.3 | 62 +++++++++++++++++++----------------------- ares_timeout.3 | 49 ++++++++++++--------------------- ares_version.3 | 23 ++++++---------- 8 files changed, 102 insertions(+), 122 deletions(-) diff --git a/ares_cancel.3 b/ares_cancel.3 index e534e3f6..1a2d3f58 100644 --- a/ares_cancel.3 +++ b/ares_cancel.3 @@ -18,9 +18,9 @@ ares_cancel \- Cancel a resolve .SH SYNOPSIS .nf -.B #include -.PP -.B void ares_cancel(ares_channel \fIchannel\fP) +#include + +void ares_cancel(ares_channel \fIchannel\fP) .fi .SH DESCRIPTION The \fBares_cancel(3)\fP function cancels all lookups/requests made on the the diff --git a/ares_destroy.3 b/ares_destroy.3 index 7af7fe34..9cdee30a 100644 --- a/ares_destroy.3 +++ b/ares_destroy.3 @@ -18,9 +18,9 @@ ares_destroy \- Destroy a resolver channel .SH SYNOPSIS .nf -.B #include -.PP -.B void ares_destroy(ares_channel \fIchannel\fP) +#include + +void ares_destroy(ares_channel \fIchannel\fP) .fi .SH DESCRIPTION The \fBares_destroy(3)\fP function destroys the name service channel @@ -28,7 +28,7 @@ identified by \fIchannel\fP, freeing all memory and closing all sockets used by the channel. \fBares_destroy(3)\fP invokes the callbacks for each pending query on the -channel, passing a status of \IARES_EDESTRUCTION\fP. These calls give the +channel, passing a status of \fIARES_EDESTRUCTION\fP. These calls give the callbacks a chance to clean up any state which might have been stored in their arguments. A callback must not add new requests to a channel being destroyed. .SH SEE ALSO diff --git a/ares_fds.3 b/ares_fds.3 index 743e45e4..07063fb0 100644 --- a/ares_fds.3 +++ b/ares_fds.3 @@ -15,43 +15,30 @@ .\" .TH ARES_FDS 3 "23 July 1998" .SH NAME -ares_fds \- Get file descriptors to select on for name service +ares_fds \- return file descriptors to select on .SH SYNOPSIS .nf -.B #include -.PP -.B int ares_fds(ares_channel \fIchannel\fP, fd_set *\fIread_fds\fP, -.B fd_set *\fIwrite_fds\fP) +#include + +int ares_fds(ares_channel \fIchannel\fP, + fd_set *\fIread_fds\fP, + fd_set *\fIwrite_fds\fP) .fi .SH DESCRIPTION -The -.B ares_fds -function retrieves the set of file descriptors which the calling -application should select on for reading and writing for the +The \fBares_fds(3)\fP function retrieves the set of file descriptors which the +calling application should select on for reading and writing for the processing of name service queries pending on the name service channel -identified by -.IR channel . +identified by \fIchannel\fP. + File descriptors will be set in the file descriptor sets pointed to by -.I read_fds -and -.I write_fds -as appropriate. File descriptors already set in -.I read_fds -and -.I write_fds -will remain set; initialization of the file descriptor sets -(using -.BR FD_ZERO ) -is the responsibility of the caller. +\fIread_fds\fP and \fIwrite_fds\fP as appropriate. File descriptors already +set in \fIread_fds\fP and \fIwrite_fds\fP will remain set; initialization of +the file descriptor sets (using \fBFD_ZERO\fP) is the responsibility of the +caller. .SH RETURN VALUES -.B ares_fds -returns one greater than the number of the highest socket set in either -.I read_fds -or -.IR write_fds . -If no queries are active, -.B ares_fds -will return 0. +\fBares_fds(3)\fP returns a value that is one greater than the number of the +highest socket set in either \fIread_fds\fP or \fIwrite_fds\fP. If no queries +are active, \fBares_fds(3)\fP returns 0. .SH SEE ALSO .BR ares_timeout (3), .BR ares_process (3) diff --git a/ares_init_options.3 b/ares_init_options.3 index ff677c93..a287e490 100644 --- a/ares_init_options.3 +++ b/ares_init_options.3 @@ -21,6 +21,27 @@ ares_init_options \- Initialize a resolver channel .nf #include +struct ares_options { + int flags; + int timeout; /* in seconds or milliseconds, depending on options */ + int tries; + int ndots; + unsigned short udp_port; + unsigned short tcp_port; + int socket_send_buffer_size; + int socket_receive_buffer_size; + struct in_addr *servers; + int nservers; + char **domains; + int ndomains; + char *lookups; + ares_sock_state_cb sock_state_cb; + void *sock_state_cb_data; + struct apattern *sortlist; + int nsort; + int ednspsz; +}; + int ares_init_options(ares_channel *\fIchannelptr\fP, struct ares_options *\fIoptions\fP, int \fIoptmask\fP) diff --git a/ares_library_cleanup.3 b/ares_library_cleanup.3 index d60c3789..a1ffa6a9 100644 --- a/ares_library_cleanup.3 +++ b/ares_library_cleanup.3 @@ -19,11 +19,9 @@ ares_library_cleanup \- c-ares library deinitialization .SH SYNOPSIS .nf -.B #include -.PP -.B void ares_library_cleanup(void) -.PP -.B cc file.c -lcares +#include + +void ares_library_cleanup(void) .fi .SH DESCRIPTION .PP diff --git a/ares_process.3 b/ares_process.3 index 7fb83718..62836ad2 100644 --- a/ares_process.3 +++ b/ares_process.3 @@ -18,15 +18,15 @@ ares_process \- Process events for name resolution .SH SYNOPSIS .nf -.B #include -.PP -.B void ares_process(ares_channel \fIchannel\fP, fd_set *\fIread_fds\fP, -.B fd_set *\fIwrite_fds\fP) -.fi -.PP -.B void ares_process_fd(ares_channel \fIchannel\fP, -.B ares_socket_t \fIread_fd\fP, -.B ares_socket_t \fIwrite_fd\fP) +#include + +void ares_process(ares_channel \fIchannel\fP, + fd_set *\fIread_fds\fP, + fd_set *\fIwrite_fds\fP) + +void ares_process_fd(ares_channel \fIchannel\fP, + ares_socket_t \fIread_fd\fP, + ares_socket_t \fIwrite_fd\fP) .fi .SH DESCRIPTION The \fBares_process(3)\fP function handles input/output events and timeouts @@ -35,42 +35,36 @@ associated with queries pending on the name service channel identified by The file descriptor sets pointed to by \fIread_fds\fP and \fIwrite_fds\fP should have file descriptors set in them according to whether the file descriptors specified by \fIares_fds(3)\fP are ready for reading and writing. -(The easiest way to determine this information is to invoke -.B select -with a timeout no greater than the timeout given by \fIares_timeout(3)\fP ). -.PP -The -.B ares_process -function will invoke callbacks for pending queries if they complete -successfully or fail. +(The easiest way to determine this information is to invoke \fBselect(3)\fP +with a timeout no greater than the timeout given by \fIares_timeout(3)\fP). + +The \fBares_process(3)\fP function will invoke callbacks for pending queries +if they complete successfully or fail. \fBares_process_fd(3)\fP works the same way but acts and operates only on the specific file descriptors (sockets) you pass in to the function. Use -ARES_SOCKET_BAD for "no action". This function is of course provided to allow -users of c-ares to void select() in their applications and within c-ares. -.SS EXAMPLE +ARES_SOCKET_BAD for "no action". This function is provided to allow users of +c-ares to void \fIselect(3)\fP in their applications and within c-ares. +.SH EXAMPLE The following code fragment waits for all pending queries on a channel to complete: -.PP -.RS + .nf int nfds, count; fd_set readers, writers; struct timeval tv, *tvp; -while (1) - { - FD_ZERO(&readers); - FD_ZERO(&writers); - nfds = ares_fds(channel, &readers, &writers); - if (nfds == 0) - break; - tvp = ares_timeout(channel, NULL, &tv); - count = select(nfds, &readers, &writers, NULL, tvp); - ares_process(channel, &readers, &writers); - } +while (1) { + FD_ZERO(&readers); + FD_ZERO(&writers); + nfds = ares_fds(channel, &readers, &writers); + if (nfds == 0) + break; + tvp = ares_timeout(channel, NULL, &tv); + count = select(nfds, &readers, &writers, NULL, tvp); + ares_process(channel, &readers, &writers); +} .fi -.RE .SH SEE ALSO .BR ares_fds (3), .BR ares_timeout (3) diff --git a/ares_timeout.3 b/ares_timeout.3 index acf8f74b..c57685dc 100644 --- a/ares_timeout.3 +++ b/ares_timeout.3 @@ -18,43 +18,28 @@ ares_timeout \- return maximum time to wait .SH SYNOPSIS .nf -.B #include -.PP -.B struct timeval *ares_timeout(ares_channel \fIchannel\fP, -.B struct timeval *\fImaxtv\fP, struct timeval *\fItv\fP) +#include + +struct timeval *ares_timeout(ares_channel \fIchannel\fP, + struct timeval *\fImaxtv\fP, + struct timeval *\fItv\fP) .fi .SH DESCRIPTION -The -.B ares_timeout -function determines the maximum time for which the caller should wait before -invoking \fIares_process(3)\fP to process timeouts. The parameter -.I maxtv -specifies a existing maximum timeout, or -.B NULL +The \fBares_timeout(3)\fP function determines the maximum time for which the +caller should wait before invoking \fIares_process(3)\fP to process timeouts. +The parameter \fImaxtv\fP specifies a existing maximum timeout, or \fBNULL\fP if the caller does not wish to apply a maximum timeout. The parameter -.I tv -must point to a writable buffer of type -.BR "struct timeval" . -It is valid for -.I maxtv -and -.I tv -to have the same value. -.PP -If no queries have timeouts pending sooner than the given maximum -timeout, -.B ares_timeout -returns the value of -.IR maxtv; -otherwise -.B ares_timeout -stores the appropriate timeout value into the buffer pointed to by -.I tv -and returns the value of -.IR tv . +\fItv\fP must point to a writable buffer of type \fBstruct timeval\fP It is +valid for \fImaxtv\fP and \fItv\fP to have the same value. + +If no queries have timeouts pending sooner than the given maximum timeout, +\fBares_timeout(3)\fP returns the value of \fImaxtv\fP; otherwise +\fBares_timeout(3)\fP stores the appropriate timeout value into the buffer +pointed to by \fItv\fP and returns the value of \fItv\fP. .SH SEE ALSO .BR ares_fds (3), -.BR ares_process (3) +.BR ares_process (3), +.BR ares_process_fd (3) .SH AUTHOR Greg Hudson, MIT Information Systems .br diff --git a/ares_version.3 b/ares_version.3 index 49b13020..9ba7831f 100644 --- a/ares_version.3 +++ b/ares_version.3 @@ -18,23 +18,18 @@ ares_version \- Get the version number of the library .SH SYNOPSIS .nf -.B #include -.PP -.B const char *ares_version(int *\fIversion\fP) +#include + +const char *ares_version(int *\fIversion\fP) .fi .SH DESCRIPTION -The -.B ares_version -function gets the library version as a string and optionally as an integer -stored in the -.IR version , -argument. If you pass a NULL, no integer is attempted to be returned. +The \fBares_version(3)\fP function gets the library version as a string and +optionally as an integer stored in the \fIversion\fP argument. If you pass a +NULL, no integer is attempted to be returned. The integer is built up as 24bit number, with 8 separate bits used for major number, minor number and patch number. This makes a version string such as 1.2.3 will be returned as the hexadecimal number 0x010203 (decimal 66051). -.SH NOTES -This function is not compatible with ares. -.SH AUTHOR -Daniel Stenberg - +.SH "SEE ALSO" +.BR ares_init (3), +.BR ares_library_init (3)