- Jakub Hrozek fixed more function prototypes in man pages to sync them

with the ones declared in ares.h
2009-11-23 00:57:50 +00:00 · 2009-11-23 00:57:50 +00:00 · f6114f2ec4
commit f6114f2ec4
parent f9e55c9908
10 changed files with 48 additions and 21 deletions
--- a/ares/CHANGES
+++ b/ares/CHANGES
@ -1,5 +1,13 @@
  Changelog for the c-ares project

+* November 22, 2009 (Yang Tse)
+- Jakub Hrozek fixed more function prototypes in man pages to sync them
+  with the ones declared in ares.h
+
+* November 20, 2009 (Yang Tse)
+- Fixed several function prototypes in man pages that were out of sync
+  with the ones declared in ares.h
+
 * November 10, 2009 (Yang Tse)
 - Updated MSVC 6.0 project files to match settings from Makefile.msvc.

--- a/ares/RELEASE-NOTES
+++ b/ares/RELEASE-NOTES
@ -22,6 +22,7 @@ Fixed:
 o fix \Device\TCP handle leaks triggered by buggy iphlpapi.dll
 o init without internet gone no longer fails
 o out of bounds memory overwrite triggered with malformed /etc/hosts file
+ o function prototypes in man pages out of sync with ares.h

 Thanks go to these friendly people for their efforts and contributions:

--- a/ares/ares_cancel.3
+++ b/ares/ares_cancel.3
@ -21,7 +21,7 @@ ares_cancel \- Cancel a resolve
 .nf
 .B #include <ares.h>
 .PP
-.B int ares_cancel(ares_channel \fIchannel\fP)
+.B void ares_cancel(ares_channel \fIchannel\fP)
 .fi
 .SH DESCRIPTION
 The \fBares_cancel\fP function cancels all lookups/requests made on the the
--- a/ares/ares_dup.3
+++ b/ares/ares_dup.3
@ -21,12 +21,12 @@ ares_dup \- Duplicate a resolver channel
 .nf
 .B #include <ares.h>
 .PP
-.B int ares_dup(ares_channel *\fIchannel\fP, ares_channel \fIsource\fP)
+.B int ares_dup(ares_channel *\fIdest\fP, ares_channel \fIsource\fP)
 .fi
 .SH DESCRIPTION
 The \fBares_dup(3)\fP function duplicates an existing communications channel
 for name service lookups.  If it returns successfully, \fBares_dup(3)\fP will
-set the variable pointed to by \fIchannel\fP to a handle used to identify the
+set the variable pointed to by \fIdest\fP to a handle used to identify the
 name service channel.  The caller should invoke \fIares_destroy(3)\fP on the
 handle when the channel is no longer needed.

--- a/ares/ares_gethostbyname_file.3
+++ b/ares/ares_gethostbyname_file.3
@ -21,7 +21,7 @@ ares_gethostbyname_file \- Lookup a name in the system's hosts file
 .nf
 .B #include <ares.h>
 .PP
-.B void ares_gethostbyname_file(ares_channel \fIchannel\fP, const char *\fIname\fP,
+.B int ares_gethostbyname_file(ares_channel \fIchannel\fP, const char *\fIname\fP,
 .B 	int \fIfamily\fP, struct hostent **host)
 .fi
 .SH DESCRIPTION
--- a/ares/ares_init.3
+++ b/ares/ares_init.3
@ -22,8 +22,8 @@ ares_init, ares_init_options \- Initialize a resolver channel
 .nf
 .B #include <ares.h>
 .PP
-.B int ares_init(ares_channel *\fIchannel\fP)
-.B int ares_init_options(ares_channel *\fIchannel\fP,
+.B int ares_init(ares_channel *\fIchannelptr\fP)
+.B int ares_init_options(ares_channel *\fIchannelptr\fP,
 .B 	struct ares_options *\fIoptions\fP, int \fIoptmask\fP)
 .PP
 .B cc file.c -lcares
@ -31,7 +31,7 @@ ares_init, ares_init_options \- Initialize a resolver channel
 .SH DESCRIPTION
 The \fBares_init\fP function initializes a communications channel for name
 service lookups.  If it returns successfully, \fBares_init\fP will set the
-variable pointed to by \fIchannel\fP to a handle used to identify the name
+variable pointed to by \fIchannelptr\fP to a handle used to identify the name
 service channel.  The caller should invoke
 .BR ares_destroy (3)
 on the handle when the channel is no longer needed.
--- a/ares/ares_parse_srv_reply.3
+++ b/ares/ares_parse_srv_reply.3
@ -21,12 +21,13 @@ ares_parse_srv_reply \- Parse a reply to a DNS query of type SRV
 .B #include <ares.h>
 .PP
 .B int ares_parse_srv_reply(const unsigned char* \fIabuf\fP, int \fIalen\fP,
-.B                          struct ares_srv_reply** \fIsrv_out\fP, int *\fInsrvreply\fP);
+.B                          struct ares_srv_reply** \fIsrv_out\fP);
 .fi
 .SH DESCRIPTION
 The
 .B ares_parse_srv_reply
 function parses the response to a query of type SRV into a
+linked list of
 .I struct ares_srv_reply 
 The parameters
 .I abuf
@ -35,11 +36,10 @@ and
 give the contents of the response.  The result is stored in allocated
 memory and a pointer to it stored into the variable pointed to by
 .IR srv_out .
-The number of responses is stored into the variable pointed to by
-.IR nsrvreply .
 It is the caller's responsibility to free the resulting
 .IR srv_out
-structure when it is no longer needed.
+structure when it is no longer needed using the function
+.B ares_free_data
 .PP
 The structure 
 .I ares_srv_reply
@ -48,6 +48,7 @@ contains the following fields:
 .in +4n
 .nf
 struct ares_srv_reply {
+    struct ares_srv_reply  *next;
    unsigned short weight;
    unsigned short priority;
    unsigned short port;
@ -73,5 +74,6 @@ The response did not contain an answer to the query.
 Memory was exhausted.
 .SH SEE ALSO
 .BR ares_query (3)
+.BR ares_free_data (3)
 .SH AUTHOR
 Written by Jakub Hrozek <jhrozek@redhat.com>, on behalf of Red Hat, Inc http://www.redhat.com
--- a/ares/ares_parse_txt_reply.3
+++ b/ares/ares_parse_txt_reply.3
@ -21,12 +21,13 @@ ares_parse_txt_reply \- Parse a reply to a DNS query of type TXT
 .B #include <ares.h>
 .PP
 .B int ares_parse_txt_reply(const unsigned char* \fIabuf\fP, int \fIalen\fP,
-.B                         struct ares_txt_reply **\fItxt_out\fP, int *\fIntxtreply\fP);
+.B                         struct ares_txt_reply **\fItxt_out\fP);
 .fi
 .SH DESCRIPTION
 The
 .B ares_parse_txt_reply
 function parses the response to a query of type TXT into a
+linked list of
 .I struct ares_txt_reply 
 The parameters
 .I abuf
@ -35,11 +36,10 @@ and
 give the contents of the response.  The result is stored in allocated
 memory and a pointer to it stored into the variable pointed to by
 .IR txt_out .
-The number of responses is stored into the variable pointed to by
-.IR ntxtreply .
 It is the caller's responsibility to free the resulting
 .IR txt_out
-structure when it is no longer needed.
+structure when it is no longer needed using the function
+.B ares_free_data
 .PP
 The structure 
 .I ares_txt_reply
@ -48,6 +48,7 @@ contains the following fields:
 .in +4n
 .nf
 struct ares_txt_reply {
+  struct ares_txt_reply  *next;
  unsigned int  length;
  unsigned char *txt;
 };
@ -71,6 +72,7 @@ The response did not contain an answer to the query.
 Memory was exhausted.
 .SH SEE ALSO
 .BR ares_query (3)
+.BR ares_free_data (3)
 .SH AUTHOR
 Written by Jakub Hrozek <jhrozek@redhat.com>, on behalf of Red Hat, Inc http://www.redhat.com

--- a/ares/ares_save_options.3
+++ b/ares/ares_save_options.3
@ -21,7 +21,7 @@ ares_save_options \- Save configuration values obtained from initialized ares_ch
 .nf
 .B #include <ares.h>
 .PP
-.B void ares_save_options(ares_channel \fIchannel\fP, struct ares_options *\fIoptions\fP, int *\fIoptmask\fP)
+.B int ares_save_options(ares_channel \fIchannel\fP, struct ares_options *\fIoptions\fP, int *\fIoptmask\fP)
 .fi
 .SH DESCRIPTION
 The \fBares_save_options(3)\fP function saves the channel data identified by
@ -36,6 +36,20 @@ The resultant options and optmask are then able to be
 passed directly to ares_init_options.  When the options
 are no longer needed, ares_destroy_options should be called
 to free any associated memory.
+.SH RETURN VALUES
+.B ares_save_options(3)
+can return any of the following values:
+.TP 15
+.B ARES_SUCCESS
+The channel data was successfuly stored
+.TP 15
+.B ARES_ENOMEM
+The memory was exhausted
+.TP 15
+.B ARES_ENODATA
+The channel data identified by 
+.IR channel
+were invalid.
 .SH NOTE
 Since c-ares 1.6.0 the ares_options struct has been "locked" meaning that it
 won't be extended to cover new funtions. This function will remain
--- a/ares/ares_timeout.3
+++ b/ares/ares_timeout.3
@ -22,7 +22,7 @@ ares_fds \- Get file descriptors to select on for name service
 .B #include <ares.h>
 .PP
 .B struct timeval *ares_timeout(ares_channel \fIchannel\fP,
-.B	struct timeval *\fImaxtv\fP, struct timeval *\fItvbuf\fP)
+.B	struct timeval *\fImaxtv\fP, struct timeval *\fItv\fP)
 .fi
 .SH DESCRIPTION
 The
@ -33,13 +33,13 @@ invoking \fIares_process(3)\fP to process timeouts.  The parameter
 specifies a existing maximum timeout, or
 .B NULL
 if the caller does not wish to apply a maximum timeout.  The parameter
-.I tvbuf
+.I tv
 must point to a writable buffer of type
 .BR "struct timeval" .
 It is valid for
 .I maxtv
 and
-.I tvbuf
+.I tv
 to have the same value.
 .PP
 If no queries have timeouts pending sooner than the given maximum
@ -50,9 +50,9 @@ returns the value of
 otherwise
 .B ares_timeout
 stores the appropriate timeout value into the buffer pointed to by
-.I tvbuf
+.I tv
 and returns the value of
-.IR tvbuf .
+.IR tv .
 .SH SEE ALSO
 .BR ares_fds (3),
 .BR ares_process (3)