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.
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:
.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
.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.
.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
.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
.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.
.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
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
.in +4n
.nf
struct ares_srv_reply {
+ struct ares_srv_reply *next;
unsigned short weight;
unsigned short priority;
unsigned short port;
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
.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
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
.in +4n
.nf
struct ares_txt_reply {
+ struct ares_txt_reply *next;
unsigned int length;
unsigned char *txt;
};
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
.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
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
.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
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
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)