view release on metacpan or  search on metacpan

libcares/ares_init_options.3  view on Meta::CPAN

.B void *\fIsock_state_cb_data\fP;
.br
A callback function to be invoked when a socket changes state.
.I socket_fd
will be passed the socket whose state has changed;
.I readable
will be set to true if the socket should listen for read events, and
.I writable
will be set to true if the socket should listen for write events.
The value of
.I sock_state_cb_data
will be passed as the
.I data
argument.
.TP 18
.B ARES_OPT_SORTLIST
.B struct apattern *\fIsortlist\fP;
.br
.B int \fInsort\fP;
.br
A list of IP address ranges that specifies the order of preference that
results from \fIares_gethostbyname\fP should be returned in.  Note that
this can only be used with a sortlist retrieved via
\fBares_save_options(3)\fP (because
.B struct apattern
is opaque); to set a fresh sort list, use \fBares_set_sortlist(3)\fP.
.TP 18
.B ARES_OPT_SOCK_SNDBUF
.B int \fIsocket_send_buffer_size\fP;
.br
The send buffer size to set for the socket.
.TP 18
.B ARES_OPT_SOCK_RCVBUF
.B int \fIsocket_receive_buffer_size\fP;
.br
The receive buffer size to set for the socket.
.TP 18
.B ARES_OPT_EDNSPSZ
.B int \fIednspsz\fP;
.br
.TP 18
.B ARES_OPT_RESOLVCONF
.B char *\fIresolvconf_path\fP;
The path to use for reading the resolv.conf file. The
.I resolvconf_path
should be set to a path string, and will be honoured on *nix like systems. The
default is
.B /etc/resolv.conf
.br
The message size to be advertized in EDNS; only takes effect if the
.B ARES_FLAG_EDNS
flag is set.
.br
.PP
The \fIoptmask\fP parameter also includes options without a corresponding
field in the
.B ares_options
structure, as follows:
.TP 23
.B ARES_OPT_ROTATE
Perform round-robin selection of the nameservers configured for the channel
for each resolution.
.TP 23
.B ARES_OPT_NOROTATE
Do not perform round-robin nameserver selection; always use the list of
nameservers in the same order.
.PP
The
.I flags
field should be the bitwise or of some subset of the following values:
.TP 23
.B ARES_FLAG_USEVC
Always use TCP queries (the "virtual circuit") instead of UDP
queries.  Normally, TCP is only used if a UDP query yields a truncated
result.
.TP 23
.B ARES_FLAG_PRIMARY
Only query the first server in the list of servers to query.
.TP 23
.B ARES_FLAG_IGNTC
If a truncated response to a UDP query is received, do not fall back
to TCP; simply continue on with the truncated response.
.TP 23
.B ARES_FLAG_NORECURSE
Do not set the "recursion desired" bit on outgoing queries, so that the name
server being contacted will not try to fetch the answer from other servers if
it doesn't know the answer locally. Be aware that ares will not do the
recursion for you.  Recursion must be handled by the application calling ares
if \fIARES_FLAG_NORECURSE\fP is set.
.TP 23
.B ARES_FLAG_STAYOPEN
Do not close communications sockets when the number of active queries
drops to zero.
.TP 23
.B ARES_FLAG_NOSEARCH
Do not use the default search domains; only query hostnames as-is or
as aliases.
.TP 23
.B ARES_FLAG_NOALIASES
Do not honor the HOSTALIASES environment variable, which normally
specifies a file of hostname translations.
.TP 23
.B ARES_FLAG_NOCHECKRESP
Do not discard responses with the SERVFAIL, NOTIMP, or REFUSED
response code or responses whose questions don't match the questions
in the request.  Primarily useful for writing clients which might be
used to test or debug name servers.
.TP 23
.B ARES_FLAG_EDNS
Include an EDNS pseudo-resource record (RFC 2671) in generated requests.
.SH RETURN VALUES
\fBares_init_options(3)\fP can return any of the following values:
.TP 14
.B ARES_SUCCESS
Initialization succeeded.
.TP 14
.B ARES_EFILE
A configuration file could not be read.
.TP 14
.B ARES_ENOMEM
The process's available memory was exhausted.
.TP 14
.B ARES_ENOTINITIALIZED
c-ares library initialization not yet performed.
.SH NOTES