ares_init man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

ARES_INIT(3)							  ARES_INIT(3)

NAME
       ares_init, ares_init_options - Initialize a resolver channel

SYNOPSIS
       #include <ares.h>

       int ares_init(ares_channel *channelptr)
       int ares_init_options(ares_channel *channelptr,
	    struct ares_options *options, int optmask)

       cc file.c -lcares

DESCRIPTION
       The  ares_init  function	 initializes a communications channel for name
       service lookups.	 If it returns successfully, ares_init	will  set  the
       variable pointed to by channelptr to a handle used to identify the name
       service channel.	 The caller should invoke ares_destroy(3) on the  han‐
       dle when the channel is no longer needed.

       The ares_init_options function also initializes a name service channel,
       with additional options useful for applications requiring more  control
       over  name service configuration. The optmask parameter specifies which
       fields in the structure pointed to by options are set, as follows:

       ARES_OPT_FLAGS	 int flags;
			 Flags controlling the behavior of the resolver.   See
			 below for a description of possible flag values.

       ARES_OPT_TIMEOUT	 int timeout;
			 The  number  of  seconds each name server is given to
			 respond to a query on	the  first  try.   (After  the
			 first try, the timeout algorithm becomes more compli‐
			 cated, but scales linearly with the  value  of	 time‐
			 out.)	 The  default  is five seconds. This option is
			 being deprecated by ARES_OPT_TIMEOUTMS starting in c-
			 ares 1.5.2.

       ARES_OPT_TIMEOUTMS
			 int timeout;
			 The  number of milliseconds each name server is given
			 to respond to a query on the first try.   (After  the
			 first try, the timeout algorithm becomes more compli‐
			 cated, but scales linearly with the  value  of	 time‐
			 out.)	 The  default  is five seconds. Note that this
			 option is specified with the same struct field as the
			 former	 ARES_OPT_TIMEOUT,  it	is but the option bits
			 that tell c-ares how to interpret  the	 number.  This
			 option was added in c-ares 1.5.2.

       ARES_OPT_TRIES	 int tries;
			 The  number of tries the resolver will try contacting
			 each name server before giving up.   The  default  is
			 four tries.

       ARES_OPT_NDOTS	 int ndots;
			 The  number of dots which must be present in a domain
			 name for it to be queried for "as is" prior to query‐
			 ing   for  it	with  the  default  domain  extensions
			 appended.  The default value is 1 unless  set	other‐
			 wise  by  resolv.conf	or the RES_OPTIONS environment
			 variable.

       ARES_OPT_PORT	 unsigned short port;
			 The port to use for queries (both TCP	and  UDP),  in
			 network byte order.  The default value is 53 (in net‐
			 work byte order), the standard name service port.

       ARES_OPT_SERVERS	 struct in_addr *servers;
			 int nservers;
			 The list of IPv4 servers to contact, instead  of  the
			 servers  specified in resolv.conf or the local named.
			 In order to allow specification  of  either  IPv4  or
			 IPv6  name  servers, the ares_set_servers(3) function
			 must be used instead.

       ARES_OPT_DOMAINS	 char **domains;
			 int ndomains;
			 The domains to search, instead of the domains	speci‐
			 fied  in  resolv.conf	or the domain derived from the
			 kernel hostname variable.

       ARES_OPT_LOOKUPS	 char *lookups;
			 The lookups to perform	 for  host  queries.   lookups
			 should	 be  set  to a string of the characters "b" or
			 "f", where "b" indicates a DNS lookup and  "f"	 indi‐
			 cates a lookup in the hosts file.

       ARES_OPT_SOCK_STATE_CB
			 void  (*sock_state_cb)(void  *data,  int s, int read,
			 int write);
			 void *sock_state_cb_data;
			 A callback function  to  be  invoked  when  a	socket
			 changes  state.   s  will  be passed the socket whose
			 state has changed; read will be set to	 true  if  the
			 socket	 should listen for read events, and write will
			 be set to true if the socket should listen for	 write
			 events.   The	value  of  sock_state_cb_data  will be
			 passed as the data argument.

       The flags field should be the bitwise or of some subset of the  follow‐
       ing values:

       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.

       ARES_FLAG_PRIMARY      Only  query  the	first  server  in  the list of
			      servers to query.

       ARES_FLAG_IGNTC	      If a  truncated  response	 to  a	UDP  query  is
			      received,	 do  not fall back to TCP; simply con‐
			      tinue on with the truncated response.

       ARES_FLAG_NORECURSE    Do not set the "recursion desired" bit on outgo‐
			      ing  queries, so that the name server being con‐
			      tacted 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  ARES_FLAG_NORE‐
			      CURSE is set.

       ARES_FLAG_STAYOPEN     Do  not  close  communications  sockets when the
			      number of active queries drops to zero.

       ARES_FLAG_NOSEARCH     Do not use  the  default	search	domains;  only
			      query hostnames as-is or as aliases.

       ARES_FLAG_NOALIASES    Do  not  honor the HOSTALIASES environment vari‐
			      able, which normally specifies a file  of	 host‐
			      name translations.

       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.

RETURN VALUES
       ares_init or ares_init_options can return any of the following values:

       ARES_SUCCESS  Initialization succeeded.

       ARES_EFILE    A configuration file could not be read.

       ARES_ENOMEM   The process's available memory was exhausted.

       ARES_ENOTINITIALIZED
		     c-ares library initialization not yet performed.

NOTES
       When initializing from /etc/resolv.conf, ares_init(3) reads the	domain
       and  search  directives to allow lookups of short names relative to the
       domains specified.  The	domain	and  search  directives	 override  one
       another.	 If  more  that one instance of either domain or search direc‐
       tives is specified, the last  occurence	wins.  For  more  information,
       please see the resolv.conf(5) manual page.

SEE ALSO
       ares_destroy(3), ares_dup(3), ares_library_init(3), ares_set_servers(3)

AUTHOR
       Greg Hudson, MIT Information Systems
       Copyright 1998 by the Massachusetts Institute of Technology.
       Copyright (C) 2004-2010 by Daniel Stenberg.

				 5 March 2010			  ARES_INIT(3)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net