diff options
Diffstat (limited to 'docs')
65 files changed, 5337 insertions, 0 deletions
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt new file mode 100644 index 0000000..5b91d31 --- /dev/null +++ b/docs/CMakeLists.txt @@ -0,0 +1,17 @@ +# Headers and Man Pages installation target +IF (CARES_INSTALL) + # ManPages + FILE (GLOB DevelManPages "." "*.3") + INSTALL (FILES ${DevelManPages} + DESTINATION ${CMAKE_INSTALL_MANDIR}/man3 + COMPONENT Devel + ) + + IF (CARES_BUILD_TOOLS) + FILE (GLOB ToolManPages "." "*.1") + INSTALL (FILES ${ToolManPages} + DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 + COMPONENT Tools + ) + ENDIF () +ENDIF () diff --git a/docs/Makefile.am b/docs/Makefile.am new file mode 100644 index 0000000..289445c --- /dev/null +++ b/docs/Makefile.am @@ -0,0 +1,11 @@ +#*************************************************************************** + +########################################################################### + +AUTOMAKE_OPTIONS = foreign subdir-objects no-dependencies + +include Makefile.inc + +man_MANS = $(MANPAGES) + +EXTRA_DIST = $(MANPAGES) ahost.1 adig.1 acountry.1 Makefile.inc CMakeLists.txt diff --git a/docs/Makefile.in b/docs/Makefile.in new file mode 100644 index 0000000..9ceca3a --- /dev/null +++ b/docs/Makefile.in @@ -0,0 +1,625 @@ +# Makefile.in generated by automake 1.16.2 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2020 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +#*************************************************************************** + +########################################################################### +VPATH = @srcdir@ +am__is_gnu_make = { \ + if test -z '$(MAKELEVEL)'; then \ + false; \ + elif test -n '$(MAKE_HOST)'; then \ + true; \ + elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \ + true; \ + else \ + false; \ + fi; \ +} +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +subdir = docs +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/ax_code_coverage.m4 \ + $(top_srcdir)/m4/ax_cxx_compile_stdcxx_11.m4 \ + $(top_srcdir)/m4/cares-compilers.m4 \ + $(top_srcdir)/m4/cares-confopts.m4 \ + $(top_srcdir)/m4/cares-functions.m4 \ + $(top_srcdir)/m4/cares-override.m4 \ + $(top_srcdir)/m4/cares-reentrant.m4 \ + $(top_srcdir)/m4/libtool.m4 $(top_srcdir)/m4/ltoptions.m4 \ + $(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \ + $(top_srcdir)/m4/lt~obsolete.m4 \ + $(top_srcdir)/m4/xc-am-iface.m4 \ + $(top_srcdir)/m4/xc-cc-check.m4 \ + $(top_srcdir)/m4/xc-lt-iface.m4 \ + $(top_srcdir)/m4/xc-translit.m4 \ + $(top_srcdir)/m4/xc-val-flgs.m4 \ + $(top_srcdir)/m4/zz40-xc-ovr.m4 \ + $(top_srcdir)/m4/zz50-xc-ovr.m4 \ + $(top_srcdir)/m4/zz60-xc-ovr.m4 $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +DIST_COMMON = $(srcdir)/Makefile.am $(am__DIST_COMMON) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/src/lib/ares_config.h \ + $(top_builddir)/include/ares_build.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +depcomp = +am__maybe_remake_depfiles = +SOURCES = +DIST_SOURCES = +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' +am__uninstall_files_from_dir = { \ + test -z "$$files" \ + || { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \ + || { echo " ( cd '$$dir' && rm -f" $$files ")"; \ + $(am__cd) "$$dir" && rm -f $$files; }; \ + } +man3dir = $(mandir)/man3 +am__installdirs = "$(DESTDIR)$(man3dir)" +NROFF = nroff +MANS = $(man_MANS) +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +am__DIST_COMMON = $(srcdir)/Makefile.in $(srcdir)/Makefile.inc +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +AR = @AR@ +AS = @AS@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +BUILD_SUBDIRS = @BUILD_SUBDIRS@ +CARES_CFLAG_EXTRAS = @CARES_CFLAG_EXTRAS@ +CARES_PRIVATE_LIBS = @CARES_PRIVATE_LIBS@ +CARES_VERSION_INFO = @CARES_VERSION_INFO@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CFLAG_CARES_SYMBOL_HIDING = @CFLAG_CARES_SYMBOL_HIDING@ +CODE_COVERAGE_CFLAGS = @CODE_COVERAGE_CFLAGS@ +CODE_COVERAGE_ENABLED = @CODE_COVERAGE_ENABLED@ +CODE_COVERAGE_LDFLAGS = @CODE_COVERAGE_LDFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CPPFLAG_CARES_STATICLIB = @CPPFLAG_CARES_STATICLIB@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +FGREP = @FGREP@ +GCOV = @GCOV@ +GENHTML = @GENHTML@ +GREP = @GREP@ +HAVE_CXX11 = @HAVE_CXX11@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LCOV = @LCOV@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MKDIR_P = @MKDIR_P@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +RANDOM_FILE = @RANDOM_FILE@ +RANLIB = @RANLIB@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +runstatedir = @runstatedir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +subdirs = @subdirs@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +AUTOMAKE_OPTIONS = foreign subdir-objects no-dependencies +MANPAGES = ares_cancel.3 \ + ares_create_query.3 \ + ares_destroy.3 \ + ares_destroy_options.3 \ + ares_dup.3 \ + ares_expand_name.3 \ + ares_expand_string.3 \ + ares_fds.3 \ + ares_free_data.3 \ + ares_free_hostent.3 \ + ares_free_string.3 \ + ares_freeaddrinfo.3 \ + ares_get_servers.3 \ + ares_get_servers_ports.3 \ + ares_getaddrinfo.3 \ + ares_gethostbyaddr.3 \ + ares_gethostbyname.3 \ + ares_gethostbyname_file.3 \ + ares_getnameinfo.3 \ + ares_getsock.3 \ + ares_inet_ntop.3 \ + ares_inet_pton.3 \ + ares_init.3 \ + ares_init_options.3 \ + ares_library_cleanup.3 \ + ares_library_init.3 \ + ares_library_init_android.3 \ + ares_library_initialized.3 \ + ares_mkquery.3 \ + ares_parse_a_reply.3 \ + ares_parse_aaaa_reply.3 \ + ares_parse_caa_reply.3 \ + ares_parse_mx_reply.3 \ + ares_parse_naptr_reply.3 \ + ares_parse_ns_reply.3 \ + ares_parse_ptr_reply.3 \ + ares_parse_soa_reply.3 \ + ares_parse_srv_reply.3 \ + ares_parse_txt_reply.3 \ + ares_process.3 \ + ares_query.3 \ + ares_save_options.3 \ + ares_search.3 \ + ares_send.3 \ + ares_set_local_dev.3 \ + ares_set_local_ip4.3 \ + ares_set_local_ip6.3 \ + ares_set_servers.3 \ + ares_set_servers_csv.3 \ + ares_set_servers_ports.3 \ + ares_set_servers_ports_csv.3 \ + ares_set_socket_callback.3 \ + ares_set_socket_configure_callback.3 \ + ares_set_socket_functions.3 \ + ares_set_sortlist.3 \ + ares_strerror.3 \ + ares_timeout.3 \ + ares_version.3 + +man_MANS = $(MANPAGES) +EXTRA_DIST = $(MANPAGES) ahost.1 adig.1 acountry.1 Makefile.inc CMakeLists.txt +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(srcdir)/Makefile.inc $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign docs/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign docs/Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__maybe_remake_depfiles);; \ + esac; +$(srcdir)/Makefile.inc $(am__empty): + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +install-man3: $(man_MANS) + @$(NORMAL_INSTALL) + @list1=''; \ + list2='$(man_MANS)'; \ + test -n "$(man3dir)" \ + && test -n "`echo $$list1$$list2`" \ + || exit 0; \ + echo " $(MKDIR_P) '$(DESTDIR)$(man3dir)'"; \ + $(MKDIR_P) "$(DESTDIR)$(man3dir)" || exit 1; \ + { for i in $$list1; do echo "$$i"; done; \ + if test -n "$$list2"; then \ + for i in $$list2; do echo "$$i"; done \ + | sed -n '/\.3[a-z]*$$/p'; \ + fi; \ + } | while read p; do \ + if test -f $$p; then d=; else d="$(srcdir)/"; fi; \ + echo "$$d$$p"; echo "$$p"; \ + done | \ + sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^3][0-9a-z]*$$,3,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \ + sed 'N;N;s,\n, ,g' | { \ + list=; while read file base inst; do \ + if test "$$base" = "$$inst"; then list="$$list $$file"; else \ + echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man3dir)/$$inst'"; \ + $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man3dir)/$$inst" || exit $$?; \ + fi; \ + done; \ + for i in $$list; do echo "$$i"; done | $(am__base_list) | \ + while read files; do \ + test -z "$$files" || { \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man3dir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(man3dir)" || exit $$?; }; \ + done; } + +uninstall-man3: + @$(NORMAL_UNINSTALL) + @list=''; test -n "$(man3dir)" || exit 0; \ + files=`{ for i in $$list; do echo "$$i"; done; \ + l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \ + sed -n '/\.3[a-z]*$$/p'; \ + } | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^3][0-9a-z]*$$,3,;x' \ + -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \ + dir='$(DESTDIR)$(man3dir)'; $(am__uninstall_files_from_dir) +tags TAGS: + +ctags CTAGS: + +cscope cscopelist: + + +distdir: $(BUILT_SOURCES) + $(MAKE) $(AM_MAKEFLAGS) distdir-am + +distdir-am: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(MANS) +installdirs: + for dir in "$(DESTDIR)$(man3dir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: install-man + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: install-man3 + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-man + +uninstall-man: uninstall-man3 + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + cscopelist-am ctags-am distclean distclean-generic \ + distclean-libtool distdir dvi dvi-am html html-am info info-am \ + install install-am install-data install-data-am install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-man3 install-pdf install-pdf-am install-ps \ + install-ps-am install-strip installcheck installcheck-am \ + installdirs maintainer-clean maintainer-clean-generic \ + mostlyclean mostlyclean-generic mostlyclean-libtool pdf pdf-am \ + ps ps-am tags-am uninstall uninstall-am uninstall-man \ + uninstall-man3 + +.PRECIOUS: Makefile + + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/docs/Makefile.inc b/docs/Makefile.inc new file mode 100644 index 0000000..fbd7492 --- /dev/null +++ b/docs/Makefile.inc @@ -0,0 +1,58 @@ +MANPAGES = ares_cancel.3 \ + ares_create_query.3 \ + ares_destroy.3 \ + ares_destroy_options.3 \ + ares_dup.3 \ + ares_expand_name.3 \ + ares_expand_string.3 \ + ares_fds.3 \ + ares_free_data.3 \ + ares_free_hostent.3 \ + ares_free_string.3 \ + ares_freeaddrinfo.3 \ + ares_get_servers.3 \ + ares_get_servers_ports.3 \ + ares_getaddrinfo.3 \ + ares_gethostbyaddr.3 \ + ares_gethostbyname.3 \ + ares_gethostbyname_file.3 \ + ares_getnameinfo.3 \ + ares_getsock.3 \ + ares_inet_ntop.3 \ + ares_inet_pton.3 \ + ares_init.3 \ + ares_init_options.3 \ + ares_library_cleanup.3 \ + ares_library_init.3 \ + ares_library_init_android.3 \ + ares_library_initialized.3 \ + ares_mkquery.3 \ + ares_parse_a_reply.3 \ + ares_parse_aaaa_reply.3 \ + ares_parse_caa_reply.3 \ + ares_parse_mx_reply.3 \ + ares_parse_naptr_reply.3 \ + ares_parse_ns_reply.3 \ + ares_parse_ptr_reply.3 \ + ares_parse_soa_reply.3 \ + ares_parse_srv_reply.3 \ + ares_parse_txt_reply.3 \ + ares_process.3 \ + ares_query.3 \ + ares_save_options.3 \ + ares_search.3 \ + ares_send.3 \ + ares_set_local_dev.3 \ + ares_set_local_ip4.3 \ + ares_set_local_ip6.3 \ + ares_set_servers.3 \ + ares_set_servers_csv.3 \ + ares_set_servers_ports.3 \ + ares_set_servers_ports_csv.3 \ + ares_set_socket_callback.3 \ + ares_set_socket_configure_callback.3 \ + ares_set_socket_functions.3 \ + ares_set_sortlist.3 \ + ares_strerror.3 \ + ares_timeout.3 \ + ares_version.3 diff --git a/docs/acountry.1 b/docs/acountry.1 new file mode 100644 index 0000000..269ae1f --- /dev/null +++ b/docs/acountry.1 @@ -0,0 +1,54 @@ +.TH ACOUNTRY "1" "April 2011" "c-ares utilities" +.SH NAME +acountry \- print the country where an IPv4 address or host is located +.SH SYNOPSIS +.B acountry +[\fIOPTION\fR]... \fIHOST\fR... +.SH DESCRIPTION +.PP +.\" Add any additional description here +.PP +Print the country where HOST (an IPv4 address or hostname) is located, +using the countries.nerd.dk DNS domain to identify the country. +.PP +This utility comes with the \fBc\-ares\fR asynchronous resolver library. +.SH OPTIONS +.TP +\fB\-d\fR +Print some extra debugging output. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display this help and exit. +.TP +\fB\-v\fR +Be more verbose. Print extra information. +.SH "REPORTING BUGS" +Report bugs to the c-ares mailing list: +.br +\fBhttps://cool.haxx.se/mailman/listinfo/c-ares\fR +.SH "SEE ALSO" +.PP +adig(1), ahost(1). +.PP +The DNSBL countries.nerd.dk +.br +\fBhttp://countries.nerd.dk/\fR +.SH COPYRIGHT +This utility is based on code/ideas contained in sofware written by Greg Hudson (ares) +carrying the following notice: +.br +Copyright 1998 by the Massachusetts Institute of Technology. +.br +Permission to use, copy, modify, and distribute this software and its +documentation for any purpose and without fee is hereby granted, +provided that the above copyright notice appear in all copies and that +both that copyright notice and this permission notice appear in +supporting documentation, and that the name of M.I.T. not be used in +advertising or publicity pertaining to distribution of the software +without specific, written prior permission. M.I.T. makes no +representations about the suitability of this software for any +purpose. It is provided "as is" without express or implied warranty. +.br +No further copyright claims are being made by the author(s) of this utility. +.SH AUTHOR +Gisle Vanem diff --git a/docs/adig.1 b/docs/adig.1 new file mode 100644 index 0000000..fa5c766 --- /dev/null +++ b/docs/adig.1 @@ -0,0 +1,85 @@ +.TH ADIG "1" "April 2011" "c-ares utilities" +.SH NAME +adig \- print information collected from Domain Name System (DNS) servers +.SH SYNOPSIS +.B adig +[\fIOPTION\fR]... \fINAME\fR... +.SH DESCRIPTION +.PP +.\" Add any additional description here +.PP +Send queries to DNS servers about \fINAME\fR and print received +information, where \fINAME\fR is a valid DNS name (e.g. www.example.com, +1.2.3.10.in-addr.arpa). +.PP +This utility comes with the \fBc\-ares\fR asynchronous resolver library. +.SH OPTIONS +.TP +\fB\-c\fR class +Set the query class. +Possible values for class are +NY, CHAOS, HS, IN (default). +.TP +\fB\-d\fR +Print some extra debugging output. +.TP +\fB\-f\fR flag +Add a flag. +Possible values for flag are +igntc, noaliases, norecurse, primary, stayopen, usevc. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display this help and exit. +.TP +\fB\-T\fR port +Use specified TCP port to connect to DNS server. +.TP +\fB\-s\fR server +Connect to specified DNS server, instead of the system's default one(s). +.TP +\fB\-t\fR type +Query records of specified type. +Possible values for type are +A (default), AAAA, AFSDB, ANY, AXFR, CNAME, GPOS, HINFO, ISDN, KEY, LOC, MAILA, +MAILB, MB, MD, MF, MG, MINFO, MR, MX, NAPTR, NS, NSAP, NSAP_PTR, NULL, +PTR, PX, RP, RT, SIG, SOA, SRV, TXT, WKS, X25, +.TP +\fB\-U\fR port +Use specified UDP port to connect to DNS server. +.TP +\fB\-x\fR +For an IPv4 \fB-t PTR a.b.c.d\fR lookup, query for +.br +\fBd.c.b.a.in-addr.arpa.\fR +This more often gives correct names in the \fBANSWER\fR. +.br +For an IPv6 \fB-t PTR addr\fR lookup, query for \fBa.b.c....z.IP6.ARPA.\fR +.TP +\fB\-xx\fR +As for \fB-x\fR and an IPv6 address, compact \fBa.b.c....z.IP6.ARPA.\fR into a RFC-2673 bit-string. +This compacted \fBbit-string\fR form is not supported by many DNS-servers. + +.SH "REPORTING BUGS" +Report bugs to the c-ares mailing list: +.br +\fBhttps://cool.haxx.se/mailman/listinfo/c-ares\fR +.SH "SEE ALSO" +.PP +acountry(1), ahost(1). +.SH COPYRIGHT +This utility is based on code/ideas contained in sofware written by Greg Hudson (ares) +carrying the following notice: +.br +Copyright 1998 by the Massachusetts Institute of Technology. +.br +Permission to use, copy, modify, and distribute this software and its +documentation for any purpose and without fee is hereby granted, +provided that the above copyright notice appear in all copies and that +both that copyright notice and this permission notice appear in +supporting documentation, and that the name of M.I.T. not be used in +advertising or publicity pertaining to distribution of the software +without specific, written prior permission. M.I.T. makes no +representations about the suitability of this software for any +purpose. It is provided "as is" without express or implied warranty. +.br +No further copyright claims are being made by the author(s) of this utility. diff --git a/docs/ahost.1 b/docs/ahost.1 new file mode 100644 index 0000000..89a3920 --- /dev/null +++ b/docs/ahost.1 @@ -0,0 +1,59 @@ +.TH AHOST "1" "April 2011" "c-ares utilities" +.SH NAME +ahost \- print the A or AAAA record associated with a hostname or IP address +.SH SYNOPSIS +.B ahost +[\fIOPTION\fR]... \fIHOST\fR... +.SH DESCRIPTION +.PP +.\" Add any additional description here +.PP +Look up the DNS A or AAAA record associated with HOST (a hostname or an +IP address). +.PP +This utility comes with the \fBc\-ares\fR asynchronous resolver library. +.SH OPTIONS +.TP +\fB\-d\fR +Print some extra debugging output. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display this help and exit. +.TP +\fB\-t\fR type +If type is "a", print the A record (default). +If type is "aaaa", print the AAAA record. +If type is "u", look for either AAAA or A record (in that order). +.TP +\fB\-s\fR \fIdomain\fP +Specify the \fIdomain\fP to search instead of using the default values from +.br +/etc/resolv.conf. This option only has an effect on platforms that use +.br +/etc/resolv.conf +for DNS configuration; it has no effect on other platforms (such as Win32 +or Android). +.SH "REPORTING BUGS" +Report bugs to the c-ares mailing list: +.br +\fBhttps://cool.haxx.se/mailman/listinfo/c-ares\fR +.SH "SEE ALSO" +.PP +acountry(1), adig(1). +.SH COPYRIGHT +This utility is based on code/ideas contained in sofware written by Greg Hudson (ares) +carrying the following notice: +.br +Copyright 1998 by the Massachusetts Institute of Technology. +.br +Permission to use, copy, modify, and distribute this software and its +documentation for any purpose and without fee is hereby granted, +provided that the above copyright notice appear in all copies and that +both that copyright notice and this permission notice appear in +supporting documentation, and that the name of M.I.T. not be used in +advertising or publicity pertaining to distribution of the software +without specific, written prior permission. M.I.T. makes no +representations about the suitability of this software for any +purpose. It is provided "as is" without express or implied warranty. +.br +No further copyright claims are being made by the author(s) of this utility. diff --git a/docs/ares_cancel.3 b/docs/ares_cancel.3 new file mode 100644 index 0000000..1a2d3f5 --- /dev/null +++ b/docs/ares_cancel.3 @@ -0,0 +1,46 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_CANCEL 3 "31 March 2004" +.SH NAME +ares_cancel \- Cancel a resolve +.SH SYNOPSIS +.nf +#include <ares.h> + +void ares_cancel(ares_channel \fIchannel\fP) +.fi +.SH DESCRIPTION +The \fBares_cancel(3)\fP function cancels all lookups/requests made on the the +name service channel identified by \fIchannel\fP. \fBares_cancel(3)\fP +invokes the callbacks for each pending query on the channel, passing a status +of +.BR ARES_ECANCELLED . +These calls give the callbacks a chance to clean up any state which might have +been stored in their arguments. If such a callback invocation adds a new +request to the channel, that request will \fInot\fP be cancelled by the +current invocation of \fBares_cancel(3)\fP. +.SH SEE ALSO +.BR ares_init (3) +.BR ares_destroy (3) +.SH NOTES +This function was added in c-ares 1.2.0 + +c-ares 1.6.0 and earlier pass a status of +.BR ARES_ETIMEOUT +instead of +.BR ARES_ECANCELLED . +.SH AUTHOR +Dirk Manske diff --git a/docs/ares_create_query.3 b/docs/ares_create_query.3 new file mode 100644 index 0000000..1ab0624 --- /dev/null +++ b/docs/ares_create_query.3 @@ -0,0 +1,83 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_CREATE_QUERY 3 "17 Aug 2012" +.SH NAME +ares_create_query \- Compose a single-question DNS query buffer +.SH SYNOPSIS +.nf +#include <ares.h> + +int ares_create_query(const char *\fIname\fP, + int \fIdnsclass\fP, + int \fItype\fP, + unsigned short \fIid\fP, + int \fIrd\fP, + unsigned char **\fIbuf\fP, + int *\fIbuflen\fP, + int \fImax_udp_size\fP) +.fi +.SH DESCRIPTION +The \fIares_create_query(3)\fP function composes a DNS query with a single +question. The parameter \fIname\fP gives the query name as a NUL-terminated C +string of period-separated labels optionally ending with a period; periods and +backslashes within a label must be escaped with a backlash. + +The parameters \fIdnsclass\fP and \fItype\fP give the class and type of the +query using the values defined in \fB<arpa/nameser.h>\fP. + +The parameter \fIid\fP gives a 16-bit identifier for the query. + +The parameter \fIrd\fP should be nonzero if recursion is desired, zero if not. + +The query will be placed in an allocated buffer, a pointer to which will be +stored in the variable pointed to by \fIbuf\fP, and the length of which will +be stored in the variable pointed to by \fIbuflen\fP. + +It is the caller's responsibility to free this buffer using +\fIares_free_string(3)\fP when it is no longer needed. The parameter +\fImax_udp_size\fP should be nonzero to activate EDNS. Usage of +\fIares_create_query(3)\fP\ with \fImax_udp_size\fP set to zero is equivalent +to using \fIares_mkquery(3)\fP. +.SH RETURN VALUES +.B ares_create_query +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +Construction of the DNS query succeeded. +.TP 15 +.B ARES_ENOTFOUND +The query name +.I name +refers to a +.I .onion +domain name. See RFC 7686. +.TP 15 +.B ARES_EBADNAME +The query name +.I name +could not be encoded as a domain name, either because it contained a +zero-length label or because it contained a label of more than 63 +characters. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH AVAILABILITY +Added in c-ares 1.10.0 +.SH SEE ALSO +.BR ares_expand_name (3), +.BR ares_free_string (3), +.BR ares_mkquery (3) +.SH AUTHOR diff --git a/docs/ares_destroy.3 b/docs/ares_destroy.3 new file mode 100644 index 0000000..9cdee30 --- /dev/null +++ b/docs/ares_destroy.3 @@ -0,0 +1,40 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_DESTROY 3 "7 December 2004" +.SH NAME +ares_destroy \- Destroy a resolver channel +.SH SYNOPSIS +.nf +#include <ares.h> + +void ares_destroy(ares_channel \fIchannel\fP) +.fi +.SH DESCRIPTION +The \fBares_destroy(3)\fP function destroys the name service channel +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 \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 +.BR ares_init (3), +.BR ares_cancel (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_destroy_options.3 b/docs/ares_destroy_options.3 new file mode 100644 index 0000000..31e346b --- /dev/null +++ b/docs/ares_destroy_options.3 @@ -0,0 +1,35 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_DESTROY_OPTIONS 3 "1 June 2007" +.SH NAME +ares_destroy_options \- Destroy options initialized with ares_save_options +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B void ares_destroy_options(struct ares_options *\fIoptions\fP) +.fi +.SH DESCRIPTION +The \fBares_destroy_options(3)\fP function destroys the options struct +identified by \Ioptions\fP, freeing all memory allocated by +\fBares_save_options(3)\fP. +.SH SEE ALSO +.BR ares_save_options (3), +.BR ares_init_options (3) +.SH AUTHOR +Brad House +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_dup.3 b/docs/ares_dup.3 new file mode 100644 index 0000000..e64c104 --- /dev/null +++ b/docs/ares_dup.3 @@ -0,0 +1,39 @@ +.\" +.\" Copyright (C) 2004-2009 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_DUP 3 "26 May 2009" +.SH NAME +ares_dup \- Duplicate a resolver channel +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.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 \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. +.SH SEE ALSO +.BR ares_destroy(3), +.BR ares_init(3), +.BR ares_library_init(3) +.SH AVAILABILITY +\fIares_dup(3)\fP was added in c-ares 1.6.0 +.SH AUTHOR +Daniel Stenberg + diff --git a/docs/ares_expand_name.3 b/docs/ares_expand_name.3 new file mode 100644 index 0000000..fc18df3 --- /dev/null +++ b/docs/ares_expand_name.3 @@ -0,0 +1,65 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_EXPAND_NAME 3 "20 Nov 2009" +.SH NAME +ares_expand_name \- Expand a DNS-encoded domain name +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_expand_name(const unsigned char *\fIencoded\fP, +.B const unsigned char *\fIabuf\fP, int \fIalen\fP, char **\fIs\fP, +.B long *\fIenclen\fP) +.fi +.SH DESCRIPTION +The +.B ares_expand_name +function converts a DNS-encoded domain name to a dot-separated C +string. The argument +.I encoded +gives the beginning of the encoded domain name, and the arguments +.I abuf +and +.I alen +give the containing message buffer (necessary for the processing of +indirection pointers within the encoded domain name). The result is +placed in a NUL-terminated allocated buffer, a pointer to which is +stored in the variable pointed to by +.IR s . +The length of the encoded name is stored in the variable pointed to by +.I enclen +so that the caller can advance past the encoded domain name to read +further data in the message. + +Use \fIares_free_string(3)\fP to free the allocated hostname. +.SH RETURN VALUES +.B ares_expand_name +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +Expansion of the encoded name succeeded. +.TP 15 +.B ARES_EBADNAME +The encoded domain name was malformed and could not be expanded. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH SEE ALSO +.BR ares_mkquery (3), ares_free_string (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_expand_string.3 b/docs/ares_expand_string.3 new file mode 100644 index 0000000..33dd7bd --- /dev/null +++ b/docs/ares_expand_string.3 @@ -0,0 +1,61 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_EXPAND_NAME 3 "20 Nov 2009" +.SH NAME +ares_expand_string \- Expand a length encoded string +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_expand_string(const unsigned char *\fIencoded\fP, +.B const unsigned char *\fIabuf\fP, int \fIalen\fP, unsigned char **\fIs\fP, +.B long *\fIenclen\fP) +.fi +.SH DESCRIPTION +The +.B ares_expand_string +function converts a length encoded string to a NUL-terminated C +string. The argument +.I encoded +gives the beginning of the encoded string, and the arguments +.I abuf +and +.I alen +give the containing message buffer (necessary for the processing of +indirection pointers within the encoded domain name). The result is +placed in a NUL-terminated allocated buffer, a pointer to which is +stored in the variable pointed to by +.IR s . +The length of the encoded string is stored in the variable pointed to by +.I enclen +so that the caller can advance past the encoded string to read +further data in the message. +.SH RETURN VALUES +.B ares_expand_string +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +Expansion of the encoded string succeeded. +.TP 15 +.B ARES_EBADSTR +The encoded string was malformed and could not be expanded. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH SEE ALSO +.BR ares_free_string (3) +.SH AUTHOR +Dominick Meglio diff --git a/docs/ares_fds.3 b/docs/ares_fds.3 new file mode 100644 index 0000000..07063fb --- /dev/null +++ b/docs/ares_fds.3 @@ -0,0 +1,48 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_FDS 3 "23 July 1998" +.SH NAME +ares_fds \- return file descriptors to select on +.SH SYNOPSIS +.nf +#include <ares.h> + +int ares_fds(ares_channel \fIchannel\fP, + fd_set *\fIread_fds\fP, + fd_set *\fIwrite_fds\fP) +.fi +.SH DESCRIPTION +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 \fIchannel\fP. + +File descriptors will be set in the file descriptor sets pointed to by +\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 +\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) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_free_data.3 b/docs/ares_free_data.3 new file mode 100644 index 0000000..f8a65b9 --- /dev/null +++ b/docs/ares_free_data.3 @@ -0,0 +1,78 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" Copyright (C) 2004-2010 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_FREE_DATA 3 "5 March 2010" +.SH NAME +ares_free_data \- Free data allocated by several c-ares functions +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B void ares_free_data(void *\fIdataptr\fP) +.PP +.B cc file.c -lcares +.fi +.SH DESCRIPTION +.PP +The +.B ares_free_data(3) +function frees one or more data structures allocated and returned +by several c-ares functions. Specifically the data returned by the +following list of functions must be deallocated using this function. +.TP 5 +.B ares_get_servers(3) +When used to free the data returned by ares_get_servers(3) this +will free the whole linked list of ares_addr_node structures returned +by ares_get_servers(3). +.TP +.B ares_parse_srv_reply(3) +When used to free the data returned by ares_parse_srv_reply(3) this +will free the whole linked list of ares_srv_reply structures returned +by ares_parse_srv_reply(3), along with any additional storage +associated with those structures. +.TP +.B ares_parse_mx_reply(3) +When used to free the data returned by ares_parse_mx_reply(3) this +will free the whole linked list of ares_mx_reply structures returned +by ares_parse_mx_reply(3), along with any additional storage +associated with those structures. +.TP +.B ares_parse_txt_reply(3) +When used to free the data returned by ares_parse_txt_reply(3) this +will free the whole linked list of ares_txt_reply structures returned +by ares_parse_txt_reply(3), along with any additional storage +associated with those structures. +.TP +.B ares_parse_soa_reply(3) +When used to free the data returned by ares_parse_soa_reply(3) this +will free the ares_soa_reply structure, along with any additional storage +associated with those structure. +.SH RETURN VALUE +The ares_free_data() function does not return a value. +.SH AVAILABILITY +This function was first introduced in c-ares version 1.7.0. +.SH SEE ALSO +.BR ares_get_servers(3), +.BR ares_parse_srv_reply(3), +.BR ares_parse_mx_reply(3), +.BR ares_parse_txt_reply(3), +.BR ares_parse_soa_reply(3) +.SH AUTHOR +Yang Tse +.PP +Copyright 1998 by the Massachusetts Institute of Technology. +.br +Copyright (C) 2004-2010 by Daniel Stenberg. diff --git a/docs/ares_free_hostent.3 b/docs/ares_free_hostent.3 new file mode 100644 index 0000000..d692801 --- /dev/null +++ b/docs/ares_free_hostent.3 @@ -0,0 +1,45 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_FREE_HOSTENT 3 "23 July 1998" +.SH NAME +ares_free_hostent \- Free host structure allocated by ares functions +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B void ares_free_hostent(struct hostent *\fIhost\fP) +.fi +.SH DESCRIPTION +The +.I ares_free_hostent +function frees a +.B struct hostent +allocated by one of the functions \fIares_parse_a_reply(3)\fP, +\fIares_parse_aaaa_reply(3)\fP, or \fIares_parse_ptr_reply(3)\fP. +.SH NOTES +It is not necessary (and is not correct) to free the host structure passed to +the callback functions for \fIares_gethostbyname(3)\fP or +\fIares_gethostbyaddr(3)\fP. c-ares will automatically free such host +structures when the callback returns. +.SH SEE ALSO +.BR ares_parse_a_reply (3), +.BR ares_parse_aaaa_reply (3), +.BR ares_parse_ptr_reply (3), +.BR ares_parse_ns_reply (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_free_string.3 b/docs/ares_free_string.3 new file mode 100644 index 0000000..61d88aa --- /dev/null +++ b/docs/ares_free_string.3 @@ -0,0 +1,34 @@ +.\" +.\" Copyright 2000 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_FREE_STRING 3 "4 February 2004" +.SH NAME +ares_free_string \- Free strings allocated by ares functions +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B void ares_free_string(void *\fIstr\fP) +.fi +.SH DESCRIPTION +The \fIares_free_string(3)\fP function frees a string allocated by an ares +function. +.SH SEE ALSO +.BR ares_mkquery (3) +.BR ares_expand_string (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 2000 by the Massachusetts Institute of Technology. diff --git a/docs/ares_freeaddrinfo.3 b/docs/ares_freeaddrinfo.3 new file mode 100644 index 0000000..8a8ad59 --- /dev/null +++ b/docs/ares_freeaddrinfo.3 @@ -0,0 +1,37 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_FREEADDRINFO 3 "31 October 2018" +.SH NAME +ares_freeaddrinfo \- Free addrinfo structure allocated by ares functions +.SH SYNOPSIS +.nf +#include <ares.h> + +void ares_freeaddrinfo(struct ares_addrinfo *\fIai\fP) +.fi +.SH DESCRIPTION +The +.B ares_freeaddrinfo +function frees a +.B struct ares_addrinfo +returned in \fIresult\fP of +.B ares_addrinfo_callback +.SH SEE ALSO +.BR ares_getaddrinfo (3), +.SH AUTHOR +Christian Ammer +.BR +Andrew Selivanov <andrew.selivanov@gmail.com> diff --git a/docs/ares_get_servers.3 b/docs/ares_get_servers.3 new file mode 100644 index 0000000..d606428 --- /dev/null +++ b/docs/ares_get_servers.3 @@ -0,0 +1,84 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" Copyright (C) 2008-2010 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_GET_SERVERS 3 "5 March 2010" +.SH NAME +ares_get_servers, ares_get_servers_ports \- Retrieve name servers from an initialized ares_channel +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_get_servers(ares_channel \fIchannel\fP, struct ares_addr_node **\fIservers\fP) +.B int ares_get_servers_ports(ares_channel \fIchannel\fP, struct ares_addr_port_node **\fIservers\fP) +.fi +.SH DESCRIPTION +The \fBares_get_servers(3)\fP function retrieves name servers configuration +from the +channel data identified by +.IR channel , +as a linked list of ares_addr_node structs storing a pointer to the first +node at the address specified by +.IR servers . + +The \fBares_get_servers_ports(3)\fP function also retrieves any per-server +port information that may have been previously configured, returning a linked +list of ares_addr_port structures. + +Function caller may traverse the returned name server linked list, or may use +it directly as suitable input for the \fBares_set_servers(3)\fP / +\fBares_set_servers_ports(3)\fP functions, but +shall not shrink or extend the list on its own. + +Each node of the name server linked list is stored in memory dynamically +allocated and managed by c-ares. It is the caller's responsibility to free +the resulting linked list, using \fBares_free_data(3)\fP , once the caller +does not need it any longer. + +This function is capable of handling IPv4 and IPv6 name server +addresses simultaneously, rendering \fBares_save_options(3)\fP with +optmask \fBARES_OPT_SERVERS\fP functionally obsolete except for +IPv4-only name server usage. + +.SH RETURN VALUES +This function may return any of the following values: +.TP 15 +.B ARES_SUCCESS +The name servers configuration was successfully retrieved +.TP 15 +.B ARES_ENOMEM +The memory was exhausted +.TP 15 +.B ARES_ENODATA +The channel data identified by +.IR channel +was invalid. +.SH SEE ALSO +.BR ares_set_servers (3), +.BR ares_init_options (3), +.BR ares_save_options(3) +.SH AVAILABILITY +\fBares_get_servers(3)\fP was added in c-ares 1.7.1; +\fBares_get_servers_ports(3)\fP was added in c-ares 1.11.0. +.SH AUTHOR +Implementation of this function and associated library internals are based +on code, comments and feedback provided in November and December of 2008 by +Daniel Stenberg, Gregor Jasny, Phil Blundell and Yang Tse, December 2009 +by Cedric Bail, February 2010 by Jakub Hrozek. On March 2010 Yang Tse +shuffled all the bits and this function popped out. +.br +Copyright 1998 by the Massachusetts Institute of Technology. +.br +Copyright (C) 2008-2010 by Daniel Stenberg diff --git a/docs/ares_get_servers_ports.3 b/docs/ares_get_servers_ports.3 new file mode 100644 index 0000000..1f5d1f7 --- /dev/null +++ b/docs/ares_get_servers_ports.3 @@ -0,0 +1 @@ +.so man3/ares_get_servers.3 diff --git a/docs/ares_getaddrinfo.3 b/docs/ares_getaddrinfo.3 new file mode 100644 index 0000000..6cae0ff --- /dev/null +++ b/docs/ares_getaddrinfo.3 @@ -0,0 +1,195 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_GETADDRINFO 3 "4 November 2018" +.SH NAME +ares_getaddrinfo \- Initiate a host query by name and service +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B typedef void (*ares_addrinfo_callback)(void *\fIarg\fP, int \fIstatus\fP, +.B int \fItimeouts\fP, struct ares_addrinfo *\fIresult\fP) +.PP +.B void ares_getaddrinfo(ares_channel \fIchannel\fP, const char *\fIname\fP, +.B const char* \fIservice\fP, const struct ares_addrinfo_hints *\fIhints\fP, +.B ares_addrinfo_callback \fIcallback\fP, void *\fIarg\fP) +.fi +.SH DESCRIPTION +The +.B ares_getaddrinfo +function initiates a host query by name on the name service channel +identified by +.IR channel . +The +.I name +and +.I service +parameters give the hostname and service as NULL-terminated C strings. +The +.I hints +parameter is an +.BR ares_addrinfo_hints +structure: +.PP +.RS +.EX +struct ares_addrinfo_hints { + int ai_flags; + int ai_family; + int ai_socktype; + int ai_protocol; +}; +.EE +.RE +.TP +.I ai_family +Specifies desired address family. AF_UNSPEC means return both AF_INET and AF_INET6. +.TP +.I ai_socktype +Specifies desired socket type, for example SOCK_STREAM or SOCK_DGRAM. +Setting this to 0 means any type. +.TP +.I ai_protocol +Setting this to 0 means any protocol. +.TP +.I ai_flags +Specifies additional options, see below. +.PP +.TP 19 +.B ARES_AI_NUMERICSERV +If this option is set +.I service +field will be treated as a numeric value. +.TP 19 +.B ARES_AI_CANONNAME +The ares_addrinfo structure will return a canonical names list. +.TP 19 +.B ARES_AI_NOSORT +Result addresses will not be sorted and no connections to resolved addresses will be attempted. +.TP 19 +.B ARES_AI_ENVHOSTS +Read hosts file path from the environment variable +.I CARES_HOSTS . +.PP +When the query is complete or has failed, the ares library will invoke \fIcallback\fP. +Completion or failure of the query may happen immediately, or may happen +during a later call to \fIares_process(3)\fP, \fIares_destroy(3)\fP or +\fIares_cancel(3)\fP. +.PP +The callback argument +.I arg +is copied from the +.B ares_getaddrinfo +argument +.IR arg . +The callback argument +.I status +indicates whether the query succeeded and, if not, how it failed. It +may have any of the following values: +.TP 19 +.B ARES_SUCCESS +The host lookup completed successfully. +.TP 19 +.B ARES_ENOTIMP +The ares library does not know how to find addresses of type +.IR family . +.TP 19 +.B ARES_ENOTFOUND +The +.I name +was not found. +.TP 19 +.B ARES_ENOMEM +Memory was exhausted. +.TP 19 +.B ARES_ECANCELLED +The query was cancelled. +.TP 19 +.B ARES_EDESTRUCTION +The name service channel +.I channel +is being destroyed; the query will not be completed. +.PP +On successful completion of the query, the callback argument +.I result +points to a +.B struct ares_addrinfo +which contains two linked lists, one with resolved addresses and another with canonical names. +.PP +.RS +.EX +struct ares_addrinfo { + struct ares_addrinfo_cname *cnames; + struct ares_addrinfo_node *nodes; +}; +.EE +.RE +.PP +.I ares_addrinfo_node +structure is similar to RFC3493 addrinfo, but without canonname and with extra ttl field. +.RS +.PP +.EX +struct ares_addrinfo_node { + int ai_ttl; + int ai_flags; + int ai_family; + int ai_socktype; + int ai_protocol; + ares_socklen_t ai_addrlen; + struct sockaddr *ai_addr; + struct ares_addrinfo_node *ai_next; +}; +.EE +.RE +.PP +.I ares_addrinfo_cname +structure is a linked list of CNAME records where +.I ttl +is a time to live +.I alias +is a label of the resource record and +.I name +is a value (canonical name) of the resource record. +See RFC2181 10.1.1. CNAME terminology. +.RS +.PP +.EX +struct ares_addrinfo_cname { + int ttl; + char *alias; + char *name; + struct ares_addrinfo_cname *next; +}; +.EE +.RE +.PP +The reserved memory has to be deleted by +.B ares_freeaddrinfo. + +The result is sorted according to RFC6724 except: + - Rule 3 (Avoid deprecated addresses) + - Rule 4 (Prefer home addresses) + - Rule 7 (Prefer native transport) + +Please note that the function will attempt a connection +on each of the resolved addresses as per RFC6724. +.SH SEE ALSO +.BR ares_freeaddrinfo (3) +.SH AUTHOR +Christian Ammer +.br +Andrew Selivanov <andrew.selivanov@gmail.com> diff --git a/docs/ares_gethostbyaddr.3 b/docs/ares_gethostbyaddr.3 new file mode 100644 index 0000000..7727307 --- /dev/null +++ b/docs/ares_gethostbyaddr.3 @@ -0,0 +1,104 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_GETHOSTBYADDR 3 "24 July 1998" +.SH NAME +ares_gethostbyaddr \- Initiate a host query by address +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B typedef void (*ares_host_callback)(void *\fIarg\fP, int \fIstatus\fP, +.B int \fItimeouts\fP, struct hostent *\fIhostent\fP) +.PP +.B void ares_gethostbyaddr(ares_channel \fIchannel\fP, const void *\fIaddr\fP, +.B int \fIaddrlen\fP, int \fIfamily\fP, ares_host_callback \fIcallback\fP, +.B void *\fIarg\fP) +.fi +.SH DESCRIPTION +The +.B ares_gethostbyaddr +function initiates a host query by address on the name service channel +identified by +.IR channel . +The parameters +.I addr +and +.I addrlen +give the address as a series of bytes, and +.I family +gives the type of address. When the query is complete or has failed, the ares +library will invoke \fIcallback\fP. Completion or failure of the query may +happen immediately, or may happen during a later call to +\fIares_process(3)\fP, \fIares_destroy(3)\fP or \fIares_cancel(3)\fP. +.PP +The callback argument +.I arg +is copied from the +.B ares_gethostbyaddr +argument +.IR arg . +The callback argument +.I status +indicates whether the query succeeded and, if not, how it failed. It +may have any of the following values: +.TP 19 +.B ARES_SUCCESS +The host lookup completed successfully. +.TP 19 +.B ARES_ENOTIMP +The ares library does not know how to look up addresses of type +.IR family . +.TP 19 +.B ARES_ENOTFOUND +The address +.I addr +was not found. +.TP 19 +.B ARES_ENOMEM +Memory was exhausted. +.TP 19 +.B ARES_ECANCELLED +The query was cancelled. +.TP 19 +.B ARES_EDESTRUCTION +The name service channel +.I channel +is being destroyed; the query will not be completed. +.PP +The callback argument +.I timeouts +reports how many times a query timed out during the execution of the +given request. +.PP +On successful completion of the query, the callback argument +.I hostent +points to a +.B struct hostent +containing the name of the host returned by the query. The callback +need not and should not attempt to free the memory pointed to by +.IR hostent ; +the ares library will free it when the callback returns. If the query +did not complete successfully, +.I hostent +will be +.BR NULL . +.SH SEE ALSO +.BR ares_process (3), +.BR ares_gethostbyname (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_gethostbyname.3 b/docs/ares_gethostbyname.3 new file mode 100644 index 0000000..cfd6a0a --- /dev/null +++ b/docs/ares_gethostbyname.3 @@ -0,0 +1,111 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_GETHOSTBYNAME 3 "25 July 1998" +.SH NAME +ares_gethostbyname \- Initiate a host query by name +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B typedef void (*ares_host_callback)(void *\fIarg\fP, int \fIstatus\fP, +.B int \fItimeouts\fP, struct hostent *\fIhostent\fP) +.PP +.B void ares_gethostbyname(ares_channel \fIchannel\fP, const char *\fIname\fP, +.B int \fIfamily\fP, ares_host_callback \fIcallback\fP, void *\fIarg\fP) +.fi +.SH DESCRIPTION +The +.B ares_gethostbyname +function initiates a host query by name on the name service channel +identified by +.IR channel . +The parameter +.I name +gives the hostname as a NUL-terminated C string, and +.I family +gives the desired type of address for the resulting host entry. When the +query is complete or has failed, the ares library will invoke \fIcallback\fP. +Completion or failure of the query may happen immediately, or may happen +during a later call to \fIares_process(3)\fP, \fIares_destroy(3)\fP or +\fIares_cancel(3)\fP. +.PP +The callback argument +.I arg +is copied from the +.B ares_gethostbyname +argument +.IR arg . +The callback argument +.I status +indicates whether the query succeeded and, if not, how it failed. It +may have any of the following values: +.TP 19 +.B ARES_SUCCESS +The host lookup completed successfully. +.TP 19 +.B ARES_ENOTIMP +The ares library does not know how to find addresses of type +.IR family . +.TP 19 +.B ARES_EBADNAME +The hostname +.B name +is composed entirely of numbers and periods, but is not a valid +representation of an Internet address. +.TP 19 +.B ARES_ENODATA +There was no data returned to extract a result from. +.TP 19 +.B ARES_ENOTFOUND +The name +.I name +was not found. +.TP 19 +.B ARES_ENOMEM +Memory was exhausted. +.TP 19 +.B ARES_ECANCELLED +The query was cancelled. +.TP 19 +.B ARES_EDESTRUCTION +The name service channel +.I channel +is being destroyed; the query will not be completed. +.PP +The callback argument +.I timeouts +reports how many times a query timed out during the execution of the +given request. +.PP +On successful completion of the query, the callback argument +.I hostent +points to a +.B struct hostent +containing the name of the host returned by the query. The callback +need not and should not attempt to free the memory pointed to by +.IR hostent ; +the ares library will free it when the callback returns. If the query +did not complete successfully, +.I hostent +will be +.BR NULL . +.SH SEE ALSO +.BR ares_process (3), +.BR ares_gethostbyaddr (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_gethostbyname_file.3 b/docs/ares_gethostbyname_file.3 new file mode 100644 index 0000000..8f59b41 --- /dev/null +++ b/docs/ares_gethostbyname_file.3 @@ -0,0 +1,83 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_GETHOSTBYNAME 3 "25 July 1998" +.SH NAME +ares_gethostbyname_file \- Lookup a name in the system's hosts file +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_gethostbyname_file(ares_channel \fIchannel\fP, const char *\fIname\fP, +.B int \fIfamily\fP, struct hostent **host) +.fi +.SH DESCRIPTION +The +.B ares_gethostbyname_file +function performs a host lookup by name against the system's hosts file (or equivalent local hostname database). +The +.IR channel +parameter is required, but no asynchronous queries are performed. Instead, the +lookup is done via the same mechanism used to perform 'f' lookups +(see the +.I lookups +options field in \fIares_init_options(3)\fP). +The parameter +.I name +gives the hostname as a NUL-terminated C string, and +.I family +gives the desired type of address for the resulting host entry. +.PP +The return value indicates whether the query succeeded and, if not, how it +failed. It may have any of the following values: +.TP 19 +.B ARES_SUCCESS +The host lookup completed successfully and +.I host +now points to the result (and must be freed with \fIares_free_hostent(3)\fP). +.TP 19 +.B ARES_ENOTFOUND +The hostname +.I name +was not found. +.TP 19 +.B ARES_EFILE +There was a file I/O error while performing the lookup. +.TP 19 +.B ARES_ENOMEM +Memory was exhausted. +.PP +On successful completion of the query, the pointer pointed to by +.I host +points to a +.B struct hostent +containing the address of the host returned by the lookup. The user must +free the memory pointed to by +.IR host +when finished with it by calling \fIares_free_hostent(3)\fP. If the lookup did +not complete successfully, +.I host +will be +.BR NULL . +.SH AVAILABILITY +Added in c-ares 1.5.4 +.SH SEE ALSO +.BR ares_gethostbyname (3), +.BR ares_free_hostent (3), +.BR ares_init_options (3) +.SH AUTHOR +Brad Spencer +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_getnameinfo.3 b/docs/ares_getnameinfo.3 new file mode 100644 index 0000000..1017432 --- /dev/null +++ b/docs/ares_getnameinfo.3 @@ -0,0 +1,151 @@ +.\" +.\" Copyright 2005 by Dominick Meglio. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_GETNAMEINFO 3 "1 May 2009" +.SH NAME +ares_getnameinfo \- Address-to-nodename translation in protocol-independent manner +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B typedef void (*ares_nameinfo_callback)(void *\fIarg\fP, int \fIstatus\fP, +.B int \fItimeouts\fP, char *\fInode\fP, char *\fIservice\fP) +.PP +.B void ares_getnameinfo(ares_channel \fIchannel\fP, const struct sockaddr *\fIsa\fP, +.B ares_socklen_t \fIsalen\fP, int \fIflags\fP, ares_nameinfo_callback \fIcallback\fP, +.B void *\fIarg\fP) +.fi +.SH DESCRIPTION +The +.B ares_getnameinfo +function is defined for protocol-independent address translation. The function +is a combination of \fIares_gethostbyaddr(3)\fP and \fIgetservbyport(3)\fP. The function will +translate the address either by executing a host query on the name service channel +identified by +.IR channel +or it will attempt to resolve it locally if possible. +The parameters +.I sa +and +.I len +give the address as a sockaddr structure, and +.I flags +gives the options that the function will use. Valid flags are listed below: +.TP 19 +.B ARES_NI_NOFQDN +Only the nodename portion of the FQDN is returned for local hosts. +.TP 19 +.B ARES_NI_NUMERICHOST +The numeric form of the hostname is returned rather than the name. +.TP 19 +.B ARES_NI_NAMEREQD +An error is returned if the hostname cannot be found in the DNS. +.TP 19 +.B ARES_NI_NUMERICSERV +The numeric form of the service is returned rather than the name. +.TP 19 +.B ARES_NI_TCP +The service name is to be looked up for the TCP protocol. +.TP 19 +.B ARES_NI_UDP +The service name is to be looked up for the UDP protocol. +.TP 19 +.B ARES_NI_SCTP +The service name is to be looked up for the SCTP protocol. +.TP 19 +.B ARES_NI_DCCP +The service name is to be looked up for the DCCP protocol. +.TP 19 +.B ARES_NI_NUMERICSCOPE +The numeric form of the scope ID is returned rather than the name. +.TP 19 +.B ARES_NI_LOOKUPHOST +A hostname lookup is being requested. +.TP 19 +.B ARES_NI_LOOKUPSERVICE +A service name lookup is being requested. +.PP +When the query +is complete or has +failed, the ares library will invoke \fIcallback\fP. Completion or failure of +the query may happen immediately, or may happen during a later call to +\fIares_process(3)\fP, \fIares_destroy(3)\fP or \fIares_cancel(3)\fP. +.PP +The callback argument +.I arg +is copied from the +.B ares_getnameinfo +argument +.IR arg . +The callback argument +.I status +indicates whether the query succeeded and, if not, how it failed. It +may have any of the following values: +.TP 19 +.B ARES_SUCCESS +The host lookup completed successfully. +.TP 19 +.B ARES_ENOTIMP +The ares library does not know how to look up addresses of type +.IR family . +.TP 19 +.B ARES_ENOTFOUND +The address +.I addr +was not found. +.TP 19 +.B ARES_ENOMEM +Memory was exhausted. +.TP 19 +.B ARES_ECANCELLED +The query was cancelled. +.TP 19 +.B ARES_EDESTRUCTION +The name service channel +.I channel +is being destroyed; the query will not be completed. +.TP 19 +.B ARES_EBADFLAGS +The +.I flags +parameter contains an illegal value. +.PP +The callback argument +.I timeouts +reports how many times a query timed out during the execution of the +given request. +.PP +On successful completion of the query, the callback argument +.I node +contains a string representing the hostname (assuming +.B ARES_NI_LOOKUPHOST +was specified). Additionally, +.I service +contains a string representing the service name (assuming +.B ARES_NI_LOOKUPSERVICE +was specified). +If the query did not complete successfully, or one of the values +was not requested, +.I node +or +.I service +will be +.BR NULL . +.SH SEE ALSO +.BR ares_process (3), +.SH AUTHOR +Dominick Meglio +.br +Copyright 2005 by Dominick Meglio. diff --git a/docs/ares_getsock.3 b/docs/ares_getsock.3 new file mode 100644 index 0000000..1373291 --- /dev/null +++ b/docs/ares_getsock.3 @@ -0,0 +1,57 @@ +.\" +.\" Copyright 1998 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_GETSOCK 3 "11 March 2010" +.SH NAME +ares_getsock \- get socket descriptors to wait on +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_getsock(ares_channel \fIchannel\fP, ares_socket_t *\fIsocks\fP, +.B int \fInumsocks\fP); +.fi +.SH DESCRIPTION +The +.B ares_getsock +function retrieves the set of socket descriptors which the calling +application should wait on for reading and/or writing for the +processing of name service queries pending on the name service channel +identified by +.IR channel . +Socket descriptors will be set in the socket descriptor array pointed to by +\fIsocks\fP. +\fInumsocks\fP is the size of the given array in number of ints. + +This function can only return information about up to 16 sockets. If more are +in use (however unlikely that is), they are simply not reported back. +.SH RETURN VALUES +\fBares_getsock\fP returns a bitmask for what actions to wait for on the +different sockets. The ares.h header file provides these convenience macros to +extract the information appropriately: + +.nf +#define ARES_GETSOCK_MAXNUM 16 /* ares_getsock() can return info about + this many sockets */ +#define ARES_GETSOCK_READABLE(bits,num) (bits & (1<< (num))) +#define ARES_GETSOCK_WRITABLE(bits,num) (bits & (1 << ((num) + \ + ARES_GETSOCK_MAXNUM))) +.fi +.SH NOTES +This function was added in c-ares 1.3.1 +.SH SEE ALSO +.BR ares_timeout (3), +.BR ares_fds (3), +.BR ares_process (3) diff --git a/docs/ares_inet_ntop.3 b/docs/ares_inet_ntop.3 new file mode 100644 index 0000000..93ee09c --- /dev/null +++ b/docs/ares_inet_ntop.3 @@ -0,0 +1,47 @@ +.\" +.\" Copyright (C) 2013 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_INET_NTOP 3 "17 Feb 2013" +.SH NAME +ares_inet_ntop \- convert a network format address to presentation format +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B const char * +.B ares_inet_ntop(int af, const void *src, char *dst, ares_socklen_t size); +.fi +.SH DESCRIPTION +This is a portable version with the identical functionality of the commonly +available \fIinet_ntop\fP. + +The ares_inet_ntop() function converts a numeric address into a text string +suitable for presentation. The \fBaf\fP argument shall specify the family of +the address. This can be AF_INET or AF_INET6. The \fBsrc\fP argument points +to a buffer holding an IPv4 address if the af argument is AF_INET, or an IPv6 +address if the af argument is AF_INET6; the address must be in network byte +order. The \fBdst\fP argument points to a buffer where the function stores the +resulting text string; it shall not be NULL. The \fBsize\fP argument specifies +the size of this buffer, which shall be large enough to hold the text string +(INET_ADDRSTRLEN (16) characters for IPv4, INET6_ADDRSTRLEN (46) characters +for IPv6). +.SH SEE ALSO +.BR ares_init(3), +.BR ares_inet_pton(3) +.SH AVAILABILITY +made properly publicly available in c-ares for real in version 1.10.0 +.SH AUTHOR +Daniel Stenberg + diff --git a/docs/ares_inet_pton.3 b/docs/ares_inet_pton.3 new file mode 100644 index 0000000..b7d86bb --- /dev/null +++ b/docs/ares_inet_pton.3 @@ -0,0 +1,43 @@ +.\" +.\" Copyright (C) 2013 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_INET_PTON 3 "17 Feb 2013" +.SH NAME +ares_inet_pton \- convert an IPv4 or IPv6 address from text to binary form +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B const char *ares_inet_pton(int af, const char *src, void *dst); +.fi +.SH DESCRIPTION +This is a portable version with the identical functionality of the commonly +available \fIinet_pton\fP. + +The ares_inet_pton() function converts the address in its standard text +presentation form into its numeric binary form. The \fBaf\fP argument shall +specify the family of the address. The AF_INET and AF_INET6 address families +shall be supported. The \fBsrc\fP argument points to the string being passed +in. The \fBdst\fP argument points to a buffer into which the function stores +the numeric address; this shall be large enough to hold the numeric address +(32 bits for AF_INET, 128 bits for AF_INET6). +.SH SEE ALSO +.BR ares_init(3), +.BR ares_inet_ntop(3) +.SH AVAILABILITY +made properly publicly available in c-ares for real in version 1.10.0 +.SH AUTHOR +Daniel Stenberg + diff --git a/docs/ares_init.3 b/docs/ares_init.3 new file mode 100644 index 0000000..0baf4b7 --- /dev/null +++ b/docs/ares_init.3 @@ -0,0 +1,81 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" Copyright (C) 2004-2010 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_INIT 3 "5 March 2010" +.SH NAME +ares_init \- Initialize a resolver channel +.SH SYNOPSIS +.nf +#include <ares.h> + +int ares_init(ares_channel *\fIchannelptr\fP) +.fi +.SH DESCRIPTION +The \fBares_init(3)\fP function initializes a communications channel for name +service lookups. If it returns successfully, \fBares_init(3)\fP will set the +variable pointed to by \fIchannelptr\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. + +The \fIares_init_options(3)\fP function is provide to offer more init +alternatives. +.SH RETURN VALUES +\fIares_init(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 +When initializing from +.B /etc/resolv.conf, +.BR ares_init (3) +reads the +.I domain +and +.I search +directives to allow lookups of short names relative to the domains +specified. The +.I domain +and +.I search +directives override one another. If more that one instance of either +.I domain +or +.I search +directives is specified, the last occurrence wins. For more information, +please see the +.BR resolv.conf (5) +manual page. +.SH SEE ALSO +.BR ares_init_options(3), +.BR ares_destroy(3), +.BR ares_dup(3), +.BR ares_library_init(3), +.BR ares_set_servers(3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. +.br +Copyright (C) 2004-2010 by Daniel Stenberg. diff --git a/docs/ares_init_options.3 b/docs/ares_init_options.3 new file mode 100644 index 0000000..b9d52a8 --- /dev/null +++ b/docs/ares_init_options.3 @@ -0,0 +1,295 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" Copyright (C) 2004-2010 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_INIT 3 "5 March 2010" +.SH NAME +ares_init_options \- Initialize a resolver channel +.SH SYNOPSIS +.nf +#include <ares.h> + +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; + char *resolvconf_path; +}; + +int ares_init_options(ares_channel *\fIchannelptr\fP, + struct ares_options *\fIoptions\fP, + int \fIoptmask\fP) +.fi +.SH DESCRIPTION +The \fBares_init_options(3)\fP function initializes a communications channel +for name service lookups. If it returns successfully, +\fBares_init_options(3)\fP will set the variable pointed to by +\fIchannelptr\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. + +The \fIoptmask\fP parameter generally specifies which fields in the structure pointed to +by \fIoptions\fP are set, as follows: +.TP 18 +.B ARES_OPT_FLAGS +.B int \fIflags\fP; +.br +Flags controlling the behavior of the resolver. See below for a +description of possible flag values. +.TP 18 +.B ARES_OPT_TIMEOUT +.B int \fItimeout\fP; +.br +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 +complicated, but scales linearly with the value of \fItimeout\fP.) The +default is five seconds. This option is being deprecated by +\fIARES_OPT_TIMEOUTMS\fP starting in c-ares 1.5.2. +.TP 18 +.B ARES_OPT_TIMEOUTMS +.B int \fItimeout\fP; +.br +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 +complicated, but scales linearly with the value of \fItimeout\fP.) The +default is five seconds. Note that this option is specified with the same +struct field as the former \fIARES_OPT_TIMEOUT\fP, 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. +.TP 18 +.B ARES_OPT_TRIES +.B int \fItries\fP; +.br +The number of tries the resolver will try contacting each name server +before giving up. The default is four tries. +.TP 18 +.B ARES_OPT_NDOTS +.B int \fIndots\fP; +.br +The number of dots which must be present in a domain name for it to be +queried for "as is" prior to querying for it with the default domain +extensions appended. The default value is 1 unless set otherwise by +resolv.conf or the RES_OPTIONS environment variable. +.TP 18 +.B ARES_OPT_UDP_PORT +.B unsigned short \fIudp_port\fP; +.br +The port to use for queries over UDP, in network byte order. +The default value is 53 (in network byte order), the standard name +service port. +.TP 18 +.B ARES_OPT_TCP_PORT +.B unsigned short \fItcp_port\fP; +.br +The port to use for queries over TCP, in network byte order. +The default value is 53 (in network byte order), the standard name +service port. +.TP 18 +.B ARES_OPT_SERVERS +.B struct in_addr *\fIservers\fP; +.br +.B int \fInservers\fP; +.br +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 +.BR ares_set_servers(3) +function must be used instead. +.TP 18 +.B ARES_OPT_DOMAINS +.B char **\fIdomains\fP; +.br +.B int \fIndomains\fP; +.br +The domains to search, instead of the domains specified in resolv.conf +or the domain derived from the kernel hostname variable. +.TP 18 +.B ARES_OPT_LOOKUPS +.B char *\fIlookups\fP; +.br +The lookups to perform for host queries. +.I lookups +should be set to a string of the characters "b" or "f", where "b" +indicates a DNS lookup and "f" indicates a lookup in the hosts file. +.TP 18 +.B ARES_OPT_SOCK_STATE_CB +.B void (*\fIsock_state_cb\fP)(void *data, ares_socket_t socket_fd, int readable, int writable); +.br +.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 +The message size to be advertized in EDNS; only takes effect if the +.B ARES_FLAG_EDNS +flag is set. +.TP 18 +.B ARES_OPT_RESOLVCONF +.B char *\fIresolvconf_path\fP; +.br +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 +.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 +When initializing from +.B /etc/resolv.conf, +(or, alternatively when specified by the +.I resolvconf_path +path location) +\fBares_init_options(3)\fP reads the \fIdomain\fP and \fIsearch\fP directives +to allow lookups of short names relative to the domains specified. The +\fIdomain\fP and \fIsearch\fP directives override one another. If more that +one instance of either \fIdomain\fP or \fIsearch\fP directives is specified, +the last occurrence wins. For more information, please see the +.BR resolv.conf (5) +manual page. +.SH SEE ALSO +.BR ares_init(3), +.BR ares_destroy(3), +.BR ares_dup(3), +.BR ares_library_init(3), +.BR ares_save_options(3), +.BR ares_set_servers(3), +.BR ares_set_sortlist(3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. +.br +Copyright (C) 2004-2010 by Daniel Stenberg. diff --git a/docs/ares_library_cleanup.3 b/docs/ares_library_cleanup.3 new file mode 100644 index 0000000..a1ffa6a --- /dev/null +++ b/docs/ares_library_cleanup.3 @@ -0,0 +1,84 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" Copyright (C) 2004-2009 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_LIBRARY_CLEANUP 3 "19 May 2009" +.SH NAME +ares_library_cleanup \- c-ares library deinitialization +.SH SYNOPSIS +.nf +#include <ares.h> + +void ares_library_cleanup(void) +.fi +.SH DESCRIPTION +.PP +The +.B ares_library_cleanup +function uninitializes the c-ares library, freeing all resources +previously acquired by \fIares_library_init(3)\fP when the library +was initialized, provided there was only one single previous call to +\fIares_library_init(3)\fP. If there was more than one previous call to +\fIares_library_init(3)\fP, this function uninitializes the c-ares +library only if it is the call matching the call to +\fIares_library_init(3)\fP which initialized the library +(usually the very first call to \fIares_library_init(3)\fP). +Other calls to \fIares_library_cleanup(3)\fP have no effect other than +decrementing an internal counter. +.PP +This function must be called when the program using c-ares will +no longer need any c-ares function. Once the program has called +\fIares_library_cleanup(3)\fP sufficiently often such that the +library is uninitialised, it shall not make any further call to any +c-ares function. +.PP +This function does not cancel any pending c-ares lookups or requests +previously done. Program must use \fIares_cancel(3)\fP for this purpose. +.PP +.B This function is not thread safe. +You have to call it once the program is about to terminate, but this call must +be done once the program has terminated every single thread that it could have +initiated. This is required to avoid potential race conditions in library +deinitialization, and also due to the fact that \fIares_library_cleanup(3)\fP +might call functions from other libraries that are thread unsafe, and could +conflict with any other thread that is already using these other libraries. +.PP +Win32/64 application DLLs shall not call \fIares_library_cleanup(3)\fP from +the DllMain function. Doing so will produce deadlocks and other problems. +.SH AVAILABILITY +This function was first introduced in c-ares version 1.7.0 along with the +definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_CLEANUP\fP as an +indication of the availability of this function. Reference counting in +\fIares_library_init()\fP and \fIares_library_cleanup()\fP, which requires +calls to the former function to match calls to the latter, is present since +c-ares version 1.10.0. +Earlier versions would deinitialize the library on the first call +to \fIares_library_cleanup()\fP. +.PP +Since the introduction of this function, it is absolutely mandatory to call it +for any Win32/64 program using c-ares. +.PP +Non-Win32/64 systems can still use c-ares version 1.7.0 without calling +\fIares_library_cleanup(3)\fP due to the fact that \fIcurrently\fP it is nearly +a do-nothing function on non-Win32/64 platforms. +.SH SEE ALSO +.BR ares_library_init(3), +.BR ares_cancel(3) +.SH AUTHOR +Yang Tse +.PP +Copyright 1998 by the Massachusetts Institute of Technology. +.br +Copyright (C) 2004-2009 by Daniel Stenberg. diff --git a/docs/ares_library_init.3 b/docs/ares_library_init.3 new file mode 100644 index 0000000..b38cf32 --- /dev/null +++ b/docs/ares_library_init.3 @@ -0,0 +1,114 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" Copyright (C) 2004-2009 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_LIBRARY_INIT 3 "19 May 2009" +.SH NAME +ares_library_init \- c-ares library initialization +.SH SYNOPSIS +.nf +#include <ares.h> + +int ares_library_init(int \fIflags\fP) + +int ares_library_init_mem(int \fIflags\fP, + void *(*\fIamalloc\fP)(size_t), + void (*\fIafree\fP)(void *ptr), + void (*\fIarealloc\fP)(void *ptr, size_t size)) +.fi +.SH DESCRIPTION +.PP +The +.B ares_library_init +function performs initializations internally required by the c-ares +library that must take place before any other function provided by +c-ares can be used in a program. +.PP +This function must be called at least once within the life of a program, +before the program actually executes any other c-ares library function. +Initializations done by this function remain effective until a number of +calls to \fIares_library_cleanup(3)\fP equal to the number of calls to +this function are performed. +.PP +Successive calls to this function do nothing further, only the first +call done when c-ares is in an uninitialized state is actually +effective. +.PP +The +.I flags +parameter is a bit pattern that tells c-ares exactly which features +should be initialized, as described below. Set the desired bits by +ORing the values together. In normal operation you should specify +\fIARES_LIB_INIT_ALL\fP. Don't use any other value unless you are +familiar with it and trying to control some internal c-ares feature. +.PP +The +.B ares_library_init_mem +function allows the caller to provide memory management functions that the +c-ares library will be use instead of \fImalloc(3)\fP, \fIfree(3)\fP and +\fIrealloc(3)\fP. +.PP +.B This function is not thread safe. +You have to call it once the program has started, but this call must be done +before the program starts any other thread. This is required to avoid +potential race conditions in library initialization, and also due to the fact +that \fIares_library_init(3)\fP might call functions from other libraries that +are thread unsafe, and could conflict with any other thread that is already +using these other libraries. +.PP +On Windows platforms, the library user should ensure that \fIWSAStartup()\fP +is called before the c-ares library is initialized and used. +.PP +Win32/64 application DLLs shall not call \fIares_library_init(3)\fP from the +DllMain function. Doing so will produce deadlocks and other problems. +.SH FLAGS +.TP 5 +.B ARES_LIB_INIT_ALL +Initialize everything possible. This sets all known bits. +.TP +.B ARES_LIB_INIT_WIN32 +Initialize Win32/64 specific libraries. +.TP +.B ARES_LIB_INIT_NONE +Initialize nothing extra. This sets no bit. +.SH RETURN VALUE +Upon successful completion, ares_library_init() will return 0. Otherwise, a +non-zero error number will be returned to indicate the error. Except for +\fIares_strerror(3)\fP, you shall not call any other c-ares function upon +\fIares_library_init(3)\fP failure. +.SH AVAILABILITY +This function was first introduced in c-ares version 1.7.0 along with the +definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_INIT\fP as an +indication of the availability of this function. Its recursive behavior, +which requires a matching number of calls to \fIares_library_cleanup()\fP +in order to deinitialize the library, is present since c-ares version +1.10.0. Earlier versions would deinitialize the library on the first call +to \fIares_library_cleanup()\fP. +.PP +Since the introduction of this function it is absolutely mandatory to +call it for any Win32/64 program using c-ares. +.PP +Non-Win32/64 systems can still use c-ares version 1.7.0 without calling +\fIares_library_init(3)\fP due to the fact that \fIcurrently\fP it is nearly +a do-nothing function on non-Win32/64 platforms at this point. +.SH SEE ALSO +.BR ares_library_cleanup(3), +.BR ares_strerror(3) +.SH AUTHOR +Yang Tse +.PP +Copyright 1998 by the Massachusetts Institute of Technology. +.br +Copyright (C) 2004-2009 by Daniel Stenberg. diff --git a/docs/ares_library_init_android.3 b/docs/ares_library_init_android.3 new file mode 100644 index 0000000..9e1ac4c --- /dev/null +++ b/docs/ares_library_init_android.3 @@ -0,0 +1,142 @@ +.\" +.\" Copyright (C) 2017 by John Schember +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_LIBRARY_INIT_ANDROID 3 "13 Sept 2017" +.SH NAME +ares_library_init_android \- c-ares library Android initialization +.SH SYNOPSIS +.nf +#include <ares.h> + +int ares_library_init_android(jobject \fIconnectivity_manager\fP) + +int ares_library_android_initialized(); + +void ares_library_init_jvm(JavaVM *\fIjvm\fP) + +.fi +.SH DESCRIPTION +The \fIares_library_init_android(3)\fP function performs initializations +internally required by the c-ares library when used on Android. This can take +place anytime after \fIares_library_init(3)\fP. It must take place after +\fIares_library_init_jvm\fP. ares_library_init_android must be called before +DNS resolution will work on Android 8 (Oreo) or newer when targetSdkVersion is +set to 26+. + +As of Android 8 (API level 26) getting DNS server information has +becomei more restrictive and can only be accessed using the +Connectivity Manager. It is necessary to pass the connectivity +manager to c-ares via JNI. Also, the ACCESS_NETWORK_STATE permission +must be present in the Android application. + +Android older than 8 do not need to to be initialized as they +are less restrictive. However, this is a run time not compile time +limitation. Proper Android initialization should take place regardless +of the targeted Android version. + +Deinitialization will take place though \fIares_library_cleanup(3)\fP. + +The \fBares_library_init_jvm\fP function allows the caller to register the JVM +with c-ares. It's meant to be called during JNI_OnLoad because you're +guaranteed to have the JVM in that function. The JVM is required in order to +use the Connectivty Manager registered using +\fIares_library_init_android(3)\fP. This must be call before +\fIares_library_init_android(3)\fP. + +The \fBares_library_android_initialized\fP function can be used to check +whether c-ares has been initialized for use with Android. +.SH RETURN VALUES +ARES_SUCCESS will be returned on success otherwise an error code will be +returned. +.SH THREAD SAFETY +.B These init functions are not thread safe. +You have to call it once the program has started, but this call must be done +before the program starts any other thread. This is required to avoid +potential race conditions in library initialization, and also due to the fact +these might call functions from other libraries that +are thread unsafe, and could conflict with any other thread that is already +using these other libraries. +.SH JNI +Accessing the Connectivity Manager though Java: + +Register the \fIares_library_android_init\fP. +.nf + static JNINativeMethod funcs[] = { + { "initialize_native", "(Landroid/net/ConnectivityManager;)I", + (void *)&ares_library_init_android} + }; + + JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) + { + JNIEnv *env = NULL; + jclass cls = NULL; + jint res; + + if ((*vm)->GetEnv(vm, (void **)&env, JNI_VERSION_1_6) != JNI_OK) + return -1; + + cls = (*env)->FindClass(env, JNIT_CLASS); + if (cls == NULL) + return -1; + + res = (*env)->RegisterNatives(env, cls, funcs, sizeof(funcs)/sizeof(funcs[0])); + if (res != 0) + return -1; + + ares_library_init_jvm(vm); + return JNI_VERSION_1_6; + } +.fi +Calling the registered function from Java: +.nf + public class MyObject { + static { + System.loadLibrary("cares"); + } + + private static native boolean initialize_native(ConnectivityManager + connectivity_manager); + + public static boolean initialize(Context context) { + initialize_native((ConnectivityManager)context.getSystemService(Context.CONNECTIVITY_SERVICE)); + } + } +.fi +Initializing the Connectivity Manager in JNI directly using an Android +Context. It is assumed the JVM has aleady been registered through +\fIJNI_OnLoad\fP. +.nf + void initialize(jobject android_context) + { + jclass obj_cls = jni_get_class(env, "android/content/Context"); + jmethodID obj_mid = jni_get_method_id(env, obj_cls, "getSystemService", "(Ljava/lang/String;)Ljava/lang/Object;"); + jfieldID fid = (*env)->GetStaticFieldID(env, obj_cls, "CONNECTIVITY_SERVICE", "Ljava/lang/String;"); + jstring str = (*env)->GetStaticObjectField(env, obj_cls, fid); + connectivity_manager = (*env)->CallObjectMethod(env, android_context, obj_mid, str); + if (connectivity_manager == NULL) + return; + ares_library_init_android(connectivity_manager); + } +.fi +.SH AVAILABILITY +This function was first introduced in c-ares version 1.15.0. +.SH SEE ALSO +.BR ares_library_init(3), +.BR ares_library_cleanup(3), +.SH AUTHOR +John Schember +.PP +Copyright (C) 2017 by John Schember + diff --git a/docs/ares_library_initialized.3 b/docs/ares_library_initialized.3 new file mode 100644 index 0000000..3e2727f --- /dev/null +++ b/docs/ares_library_initialized.3 @@ -0,0 +1,34 @@ +.\" +.\" Copyright (C) 2016 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_LIBRARY_INITIALIZED 3 "29 Sep 2016" +.SH NAME +ares_library_initialized \- get the initialization state +.SH SYNOPSIS +.nf +#include <ares.h> + +int ares_library_initialized(void) +.fi +.SH DESCRIPTION +Returns information if c-ares needs to get initialized. +.SH RETURN VALUE +\fIARES_ENOTINITIALIZED\fP if not initialized and \fIARES_SUCCESS\fP if no +initialization is needed. +.SH AVAILABILITY +This function was first introduced in c-ares version 1.11.0 +.SH SEE ALSO +.BR ares_library_init(3), +.BR ares_library_cleanup(3) diff --git a/docs/ares_mkquery.3 b/docs/ares_mkquery.3 new file mode 100644 index 0000000..c8afad8 --- /dev/null +++ b/docs/ares_mkquery.3 @@ -0,0 +1,89 @@ +.\" +.\" Copyright 1998, 2000 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_MKQUERY 3 "20 Nov 2009" +.SH NAME +ares_mkquery \- Compose a single-question DNS query buffer +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_mkquery(const char *\fIname\fP, int \fIdnsclass\fP, int \fItype\fP, +.B unsigned short \fIid\fP, int \fIrd\fP, unsigned char **\fIbuf\fP, +.B int *\fIbuflen\fP) +.fi +.SH DESCRIPTION +Deprecated function. See \fIares_create_query(3)\fP instead! + +The +.B ares_mkquery +function composes a DNS query with a single question. +The parameter +.I name +gives the query name as a NUL-terminated C string of period-separated +labels optionally ending with a period; periods and backslashes within +a label must be escaped with a backlash. The parameters +.I dnsclass +and +.I type +give the class and type of the query using the values defined in +.BR <arpa/nameser.h> . +The parameter +.I id +gives a 16-bit identifier for the query. The parameter +.I rd +should be nonzero if recursion is desired, zero if not. The query +will be placed in an allocated buffer, a pointer to which will be +stored in the variable pointed to by +.IR buf , +and the length of which will be stored in the variable pointed to by +.IR buflen . +It is the caller's responsibility to free this buffer using +\fIares_free_string(3)\fP when it is no longer needed. + +Usage of \fIares_mkquery(3)\fP is deprecated, whereas the function is +equivalent to \fIares_create_query(3)\fP with \fBmax_udp_size\fP set to +0. + +.SH RETURN VALUES +.B ares_mkquery +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +Construction of the DNS query succeeded. +.TP 15 +.B ARES_ENOTFOUND +The query name +.I name +refers to a +.I .onion +domain name. See RFC 7686. +.TP 15 +.B ARES_EBADNAME +The query name +.I name +could not be encoded as a domain name, either because it contained a +zero-length label or because it contained a label of more than 63 +characters. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH SEE ALSO +.BR ares_expand_name (3), +.BR ares_free_string (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998, 2000 by the Massachusetts Institute of Technology. diff --git a/docs/ares_parse_a_reply.3 b/docs/ares_parse_a_reply.3 new file mode 100644 index 0000000..8e4908a --- /dev/null +++ b/docs/ares_parse_a_reply.3 @@ -0,0 +1,80 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_PARSE_A_REPLY 3 "25 July 1998" +.SH NAME +ares_parse_a_reply \- Parse a reply to a DNS query of type A +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_parse_a_reply(const unsigned char *\fIabuf\fP, int \fIalen\fP, +.B struct hostent **\fIhost\fP, +.B struct ares_addrttl *\fIaddrttls\fP, int *\fInaddrttls\fP); +.fi +.SH DESCRIPTION +The +.B ares_parse_a_reply +function parses the response to a query of type A into a +.BR "struct hostent" +and/or an array of +.BR "struct ares_addrttls" . +The parameters +.I abuf +and +.I alen +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 host , +if host is nonnull. +It is the caller's responsibility to free the resulting host structure +using +.BR ares_free_hostent (3) +when it is no longer needed. +.PP +If +.IR addrttls +and +.IR naddrttls +are both nonnull, +then up to *naddrttls +.BR "struct ares_addrttl" +records are stored in the array pointed to by addrttls, +and then *naddrttls is set to the number of records so stored. +Note that the memory for these records is supplied by the caller. +.SH RETURN VALUES +.B ares_parse_a_reply +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +The response was successfully parsed. +.TP 15 +.B ARES_EBADRESP +The response was malformatted. +.TP 15 +.B ARES_ENODATA +The response did not contain an answer to the query. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH SEE ALSO +.BR ares_gethostbyname (3), +.BR ares_free_hostent (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Andrew Selivanov <andrew.selivanov@gmail.com> +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_parse_aaaa_reply.3 b/docs/ares_parse_aaaa_reply.3 new file mode 100644 index 0000000..674acc5 --- /dev/null +++ b/docs/ares_parse_aaaa_reply.3 @@ -0,0 +1,80 @@ +.\" +.\" Copyright 2005 by Dominick Meglio. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_PARSE_AAAA_REPLY 3 "20 Nov 2009" +.SH NAME +ares_parse_aaaa_reply \- Parse a reply to a DNS query of type AAAA +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_parse_aaaa_reply(const unsigned char *\fIabuf\fP, int \fIalen\fP, +.B struct hostent **\fIhost\fP, +.B struct ares_addr6ttl *\fIaddrttls\fP, int *\fInaddrttls\fP); +.fi +.SH DESCRIPTION +The +.B ares_parse_aaaa_reply +function parses the response to a query of type AAAA into a +.BR "struct hostent" +and/or an array of +.BR "struct ares_addr6ttl" . +The parameters +.I abuf +and +.I alen +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 host , +if host is nonnull. +It is the caller's responsibility to free the resulting host structure +using +.BR ares_free_hostent (3) +when it is no longer needed. +.PP +If +.IR addrttls +and +.IR naddrttls +are both nonnull, +then up to *naddrttls +.BR "struct ares_addr6ttl" +records are stored in the array pointed to by addrttls, +and then *naddrttls is set to the number of records so stored. +Note that the memory for these records is supplied by the caller. +.SH RETURN VALUES +.B ares_parse_aaaa_reply +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +The response was successfully parsed. +.TP 15 +.B ARES_EBADRESP +The response was malformatted. +.TP 15 +.B ARES_ENODATA +The response did not contain an answer to the query. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH SEE ALSO +.BR ares_gethostbyname (3), +.BR ares_free_hostent (3) +.SH AUTHOR +Dominick Meglio +.br +Copyright 2005 by Dominick Meglio. +.BR +Andrew Selivanov <andrew.selivanov@gmail.com> diff --git a/docs/ares_parse_caa_reply.3 b/docs/ares_parse_caa_reply.3 new file mode 100644 index 0000000..71bd6be --- /dev/null +++ b/docs/ares_parse_caa_reply.3 @@ -0,0 +1,171 @@ +.\" +.\" Copyright 2020 Danny Sonnenschein <my.card.god@web.de> +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_PARSE_CAA_REPLY 3 "16 September 2020" +.SH NAME +ares_parse_caa_reply \- Parse a reply to a DNS query of type CAA +.SH SYNOPSIS +.nf +#include <ares.h> + +int ares_parse_caa_reply(const unsigned char* \fIabuf\fP, int \fIalen\fP, + struct ares_caa_reply **\fIcaa_out\fP); +.fi +.SH DESCRIPTION +The +.BR "ares_parse_caa_reply" +function parses the response to a query of type CAA into a +linked list (one element per sub-string) of +.IR "struct ares_caa_reply" +The parameters +.I abuf +and +.I alen +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 caa_out . +It is the caller's responsibility to free the resulting +.IR caa_out +structure when it is no longer needed using the function +.B ares_free_data(3) +.PP +The structure +.I ares_caa_reply(3) +contains the following fields: +.sp +.in +4n +.nf +struct ares_caa_reply { + struct ares_caa_reply *next; + int critical; + unsigned char *property; + size_t plength; /* plength excludes null */ + unsigned char *value; + size_t length; /* length excludes null */ +}; +.fi +.in +.PP +.SH RETURN VALUES +.BR "ares_parse_caa_reply" +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +The response was successfully parsed. +.TP 15 +.B ARES_EBADRESP +The response was malformatted. +.TP 15 +.B ARES_ENODATA +The response did not contain an answer to the query. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH EXAMPLE +.nf +#include <arpa/inet.h> +#include <time.h> +#include <sys/time.h> +#include <netdb.h> + +#include <unistd.h> +#include <stdio.h> +#include <stdlib.h> + +#include "ares.h" + +static void dns_callback(void *arg, + int status, + int timeouts, + unsigned char *abuf, + int alen) + { + struct ares_caa_reply *caa_out; + int err; + + err = ares_parse_caa_reply (abuf, alen, &caa_out); + if (err == ARES_SUCCESS) + { + struct ares_caa_reply *caa_curr; + for (caa_curr=caa_out; caa_curr; caa_curr=caa_curr->next) + printf ("%s. CAA %i %s \\"%s\\"\\n", arg, + caa_curr->critical, + caa_curr->property, + caa_curr->value); + } + else + { + printf ("err=%i\\n", err); + } + ares_free_data (caa_out); + } + +static void main_loop(ares_channel *channel) + { + 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); + } + } + +int main(int argc, char **argv) + { + const char *sversion; + int iversion; + int err; + + sversion = ares_version (&iversion); + printf ("c-ares version %s\\n", sversion); + + char *domain = "wikipedia.org"; + if (argc > 1) + domain = argv[1]; + + ares_channel channel; + if ((err = ares_init (&channel)) != ARES_SUCCESS) + { + printf ("ares_init() failed (%i)\\n", err); + exit (EXIT_FAILURE); + } + + ares_query (channel, domain, + 1, /* ns_c_in */ + 257, /* T_CAA */ + dns_callback, domain); + + main_loop (&channel); + + ares_destroy (channel); + + exit (EXIT_SUCCESS); + } +.fi +.SH AVAILABILITY +This function was first introduced in c-ares version 1.17.0. +.SH SEE ALSO +.BR ares_query (3) +.BR ares_free_data (3) +.SH AUTHOR +Written by Danny Sonnenschein <my.card.god@web.de>, on behalf of platynum, https://platynum.ch diff --git a/docs/ares_parse_mx_reply.3 b/docs/ares_parse_mx_reply.3 new file mode 100644 index 0000000..87df459 --- /dev/null +++ b/docs/ares_parse_mx_reply.3 @@ -0,0 +1,79 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_PARSE_MX_REPLY 3 "4 August 2009" +.SH NAME +ares_parse_mx_reply \- Parse a reply to a DNS query of type MX +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_parse_mx_reply(const unsigned char* \fIabuf\fP, int \fIalen\fP, +.B struct ares_mx_reply** \fImx_out\fP); +.fi +.SH DESCRIPTION +The +.B ares_parse_mx_reply +function parses the response to a query of type MX into a +linked list of +.I struct ares_mx_reply +The parameters +.I abuf +and +.I alen +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 mx_out . +It is the caller's responsibility to free the resulting +.IR mx_out +structure when it is no longer needed using the function +.B ares_free_data +.PP +The structure +.I ares_mx_reply +contains the following fields: +.sp +.in +4n +.nf +struct ares_mx_reply { + struct ares_mx_reply *next; + char *host; + unsigned short priority; +}; +.fi +.in +.PP +.SH RETURN VALUES +.B ares_parse_mx_reply +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +The response was successfully parsed. +.TP 15 +.B ARES_EBADRESP +The response was malformatted. +.TP 15 +.B ARES_ENODATA +The response did not contain an answer to the query. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH AVAILABILITY +This function was first introduced in c-ares version 1.7.2. +.SH SEE ALSO +.BR ares_query (3) +.BR ares_free_data (3) +.SH AUTHOR +Written by Jeremy Lal <kapouer@melix.org> diff --git a/docs/ares_parse_naptr_reply.3 b/docs/ares_parse_naptr_reply.3 new file mode 100644 index 0000000..2a5f1e5 --- /dev/null +++ b/docs/ares_parse_naptr_reply.3 @@ -0,0 +1,83 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_PARSE_NAPTR_REPLY 3 "23 February 2012" +.SH NAME +ares_parse_naptr_reply \- Parse a reply to a DNS query of type NAPTR +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_parse_naptr_reply(const unsigned char* \fIabuf\fP, int \fIalen\fP, +.B struct ares_naptr_reply** \fInaptr_out\fP); +.fi +.SH DESCRIPTION +The +.B ares_parse_naptr_reply +function parses the response to a query of type NAPTR into a +linked list of +.I struct ares_naptr_reply +The parameters +.I abuf +and +.I alen +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 naptr_out . +It is the caller's responsibility to free the resulting +.IR naptr_out +structure when it is no longer needed using the function +.B ares_free_data +.PP +The structure +.I ares_naptr_reply +contains the following fields: +.sp +.in +4n +.nf +struct ares_naptr_reply { + struct ares_naptr_reply *next; + unsigned char *flags; + unsigned char *service; + unsigned char *regexp; + char *replacement; + unsigned short order; + unsigned short preference; +}; +.fi +.in +.PP +.SH RETURN VALUES +.B ares_parse_naptr_reply +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +The response was successfully parsed. +.TP 15 +.B ARES_EBADRESP +The response was malformatted. +.TP 15 +.B ARES_ENODATA +The response did not contain an answer to the query. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH AVAILABILITY +This function was first introduced in c-ares version 1.7.6. +.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 diff --git a/docs/ares_parse_ns_reply.3 b/docs/ares_parse_ns_reply.3 new file mode 100644 index 0000000..b6340ac --- /dev/null +++ b/docs/ares_parse_ns_reply.3 @@ -0,0 +1,66 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_PARSE_NS_REPLY 3 "10 February 2007" +.SH NAME +ares_parse_ns_reply \- Parse a reply to a DNS query of type NS into a hostent +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_parse_ns_reply(const unsigned char *\fIabuf\fP, int \fIalen\fP, +.B struct hostent **\fIhost\fP); +.fi +.SH DESCRIPTION +The +.B ares_parse_ns_reply +function parses the response to a query of type NS into a +.BR "struct hostent" . +The parameters +.I abuf +and +.I alen +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 host . +The nameservers are stored into the +.BR aliases +field of the +.IR host +structure. +It is the caller's responsibility to free the resulting host structure +using +.BR ares_free_hostent (3) +when it is no longer needed. +.SH RETURN VALUES +.B ares_parse_ns_reply +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +The response was successfully parsed. +.TP 15 +.B ARES_EBADRESP +The response was malformatted. +.TP 15 +.B ARES_ENODATA +The response did not contain an answer to the query. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH SEE ALSO +.BR ares_query (3), +.BR ares_free_hostent (3) +.SH AUTHOR +Written by Vlad Dinulescu <vlad.dinulescu@avira.com>, on behalf of AVIRA Gmbh http://www.avira.com diff --git a/docs/ares_parse_ptr_reply.3 b/docs/ares_parse_ptr_reply.3 new file mode 100644 index 0000000..1016a68 --- /dev/null +++ b/docs/ares_parse_ptr_reply.3 @@ -0,0 +1,74 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_PARSE_PTR_REPLY 3 "25 July 1998" +.SH NAME +ares_parse_ptr_reply \- Parse a reply to a DNS query of type PTR into a hostent +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_parse_ptr_reply(const unsigned char *\fIabuf\fP, int \fIalen\fP, +.B const void *\fIaddr\fP, int \fIaddrlen\fP, int \fIfamily\fP, +.B struct hostent **\fIhost\fP); +.fi +.SH DESCRIPTION +The +.B ares_parse_ptr_reply +function parses the response to a query of type PTR into a +.BR "struct hostent" . +The parameters +.I abuf +and +.I alen +give the contents of the response. The parameters +.IR addr , +.IR addrlen , +and +.I family +specify which address was queried for; they are not used to verify the +response, merely used to fill in the address of the +.BR "struct hostent" . +The resulting +.B struct hostent +is stored in allocated memory and a pointer to it stored into the +variable pointed to by +.IR host . +It is the caller's responsibility to free the resulting host structure +using +.BR ares_free_hostent (3) +when it is no longer needed. +.SH RETURN VALUES +.B ares_parse_ptr_reply +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +The response was successfully parsed. +.TP 15 +.B ARES_EBADRESP +The response was malformatted. +.TP 15 +.B ARES_ENODATA +The response did not contain an answer to the query. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH SEE ALSO +.BR ares_gethostbyaddr (3), +.BR ares_free_hostent (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_parse_soa_reply.3 b/docs/ares_parse_soa_reply.3 new file mode 100644 index 0000000..1c4456f --- /dev/null +++ b/docs/ares_parse_soa_reply.3 @@ -0,0 +1,80 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_PARSE_SOA_REPLY 3 "29 May 2012" +.SH NAME +ares_parse_soa_reply \- Parse a reply to a DNS query of type SOA +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_parse_soa_reply(const unsigned char* \fIabuf\fP, int \fIalen\fP, +.B struct ares_soa_reply** \fIsoa_out\fP); +.fi +.SH DESCRIPTION +The +.B ares_parse_soa_reply +function parses the response to a query of type SOA into a +.IR struct\ ares_soa_reply . +The parameters +.I abuf +and +.I alen +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 soa_out . +It is the caller's responsibility to free the resulting +.IR soa_out +structure when it is no longer needed using the function +.B ares_free_data +.PP +The structure +.I ares_soa_reply +contains the following fields: +.sp +.in +4n +.nf +struct ares_soa_reply { + char *nsname; + char *hostmaster; + unsigned int serial; + unsigned int refresh; + unsigned int retry; + unsigned int expire; + unsigned int minttl; +}; +.fi +.in +.PP +.SH RETURN VALUES +.B ares_parse_soa_reply +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +The response was successfully parsed. +.TP 15 +.B ARES_EBADRESP +The response was malformatted. +.TP 15 +.B ARES_ENODATA +The response did not contain an answer to the query. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH AVAILABILITY +This function was first introduced in c-ares version 1.9.0. +.SH SEE ALSO +.BR ares_query (3) +.BR ares_free_data (3) diff --git a/docs/ares_parse_srv_reply.3 b/docs/ares_parse_srv_reply.3 new file mode 100644 index 0000000..9b561ff --- /dev/null +++ b/docs/ares_parse_srv_reply.3 @@ -0,0 +1,81 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_PARSE_SRV_REPLY 3 "4 August 2009" +.SH NAME +ares_parse_srv_reply \- Parse a reply to a DNS query of type SRV +.SH SYNOPSIS +.nf +.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); +.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 +and +.I alen +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 . +It is the caller's responsibility to free the resulting +.IR srv_out +structure when it is no longer needed using the function +.B ares_free_data +.PP +The structure +.I ares_srv_reply +contains the following fields: +.sp +.in +4n +.nf +struct ares_srv_reply { + struct ares_srv_reply *next; + unsigned short weight; + unsigned short priority; + unsigned short port; + char *host; +}; +.fi +.in +.PP +.SH RETURN VALUES +.B ares_parse_srv_reply +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +The response was successfully parsed. +.TP 15 +.B ARES_EBADRESP +The response was malformatted. +.TP 15 +.B ARES_ENODATA +The response did not contain an answer to the query. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH AVAILABILITY +This function was first introduced in c-ares version 1.7.0. +.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 diff --git a/docs/ares_parse_txt_reply.3 b/docs/ares_parse_txt_reply.3 new file mode 100644 index 0000000..e15d0ea --- /dev/null +++ b/docs/ares_parse_txt_reply.3 @@ -0,0 +1,120 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_PARSE_TXT_REPLY 3 "27 October 2009" +.SH NAME +ares_parse_txt_reply \- Parse a reply to a DNS query of type TXT +.SH SYNOPSIS +.nf +.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); +.PP +.B int ares_parse_txt_reply_ext(const unsigned char* \fIabuf\fP, int \fIalen\fP, +.B struct ares_txt_ext **\fItxt_out\fP); +.fi +.SH DESCRIPTION +The +.BR "ares_parse_txt_reply" " (" "ares_parse_txt_reply_ext" ")" +function parses the response to a query of type TXT into a +linked list (one element per sub-string) of +.IR "struct ares_txt_reply" " (" "struct ares_txt_ext" ")" +The parameters +.I abuf +and +.I alen +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 . +It is the caller's responsibility to free the resulting +.IR txt_out +structure when it is no longer needed using the function +.B ares_free_data +.PP +The structure +.I ares_txt_reply +contains the following fields: +.sp +.in +4n +.nf +struct ares_txt_reply { + struct ares_txt_reply *next; + unsigned int length; + unsigned char *txt; +}; +.fi +.in +.PP +The structure +.I ares_txt_ext +contains the following fields: +.sp +.in +4n +.nf +struct ares_txt_ext { + struct ares_txt_ext *next; + unsigned int length; + unsigned char *txt; + unsigned char record_start; +}; +.fi +.in +.PP +The +.I record_start +field in +.I struct ares_txt_ext +is 1 if this structure is a start of a TXT record, and 0 if the structure is a +continuation of a previous record. The linked list of the +.I struct ares_txt_ext +will have at least one item with +.I record_start +equal to 1, and may have some items with +.I record_start +equal to 0 between them. +.PP +These sequences of +.I struct ares_txt_ext +(starting from the item with +.I record_start +equal to 1, and ending right before the record start item) may be treated as +either components of a single TXT record or as a multi-parted TXT record, +depending on particular use case. +.PP +.SH RETURN VALUES +.BR "ares_parse_txt_reply" " (" "ares_parse_txt_reply_ext" ")" +can return any of the following values: +.TP 15 +.B ARES_SUCCESS +The response was successfully parsed. +.TP 15 +.B ARES_EBADRESP +The response was malformatted. +.TP 15 +.B ARES_ENODATA +The response did not contain an answer to the query. +.TP 15 +.B ARES_ENOMEM +Memory was exhausted. +.SH AVAILABILITY +This function was first introduced in c-ares version 1.7.0. +.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 +.PP +Amended by Fedor Indutny <fedor@indutny.com>, on behalf of PayPal, Inc https://www.paypal.com diff --git a/docs/ares_process.3 b/docs/ares_process.3 new file mode 100644 index 0000000..caabbf1 --- /dev/null +++ b/docs/ares_process.3 @@ -0,0 +1,79 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_PROCESS 3 "25 July 1998" +.SH NAME +ares_process \- Process events for name resolution +.SH SYNOPSIS +.nf +#include <ares.h> + +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 +associated with queries pending on the name service channel identified by +.IR channel . +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 \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 provided to allow users of +c-ares to void \fIselect(3)\fP in their applications and within c-ares. + +To only process possible timeout conditions without a socket event occurring, +one may pass NULL as the values for both \fIread_fds\fP and \fIwrite_fds\fP for +\fBares_process(3)\fP, or ARES_SOCKET_BAD for both \fIread_fd\fP and +\fIwrite_fd\fP for \fBares_process_fd(3)\fP. +.SH EXAMPLE +The following code fragment waits for all pending queries on a channel +to complete: + +.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); +} +.fi +.SH SEE ALSO +.BR ares_fds (3), +.BR ares_timeout (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_query.3 b/docs/ares_query.3 new file mode 100644 index 0000000..733fbc9 --- /dev/null +++ b/docs/ares_query.3 @@ -0,0 +1,149 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_QUERY 3 "24 July 1998" +.SH NAME +ares_query \- Initiate a single-question DNS query +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B typedef void (*ares_callback)(void *\fIarg\fP, int \fIstatus\fP, +.B int \fItimeouts\fP, unsigned char *\fIabuf\fP, int \fIalen\fP) +.PP +.B void ares_query(ares_channel \fIchannel\fP, const char *\fIname\fP, +.B int \fIdnsclass\fP, int \fItype\fP, ares_callback \fIcallback\fP, +.B void *\fIarg\fP) +.fi +.SH DESCRIPTION +The +.B ares_query +function initiates a single-question DNS query on the name service +channel identified by +.IR channel . +The parameter +.I name +gives the query name as a NUL-terminated C string of period-separated +labels optionally ending with a period; periods and backslashes within +a label must be escaped with a backslash. The parameters +.I dnsclass +and +.I type +give the class and type of the query using the values defined in +.BR <arpa/nameser.h> . +When the query is complete or has failed, the ares library will invoke +.IR callback . +Completion or failure of the query may happen immediately, or may +happen during a later call to +.BR ares_process (3) +or +.BR ares_destroy (3). +.PP +The callback argument +.I arg +is copied from the +.B ares_query +argument +.IR arg . +The callback argument +.I status +indicates whether the query succeeded and, if not, how it failed. It +may have any of the following values: +.TP 19 +.B ARES_SUCCESS +The query completed successfully. +.TP 19 +.B ARES_ENODATA +The query completed but contains no answers. +.TP 19 +.B ARES_EFORMERR +The query completed but the server claims that the query was +malformatted. +.TP 19 +.B ARES_ESERVFAIL +The query completed but the server claims to have experienced a +failure. (This code can only occur if the +.B ARES_FLAG_NOCHECKRESP +flag was specified at channel initialization time; otherwise, such +responses are ignored at the +.BR ares_send (3) +level.) +.TP 19 +.B ARES_ENOTFOUND +The query completed but the queried-for domain name was not found. +.TP 19 +.B ARES_ENOTIMP +The query completed but the server does not implement the operation +requested by the query. (This code can only occur if the +.B ARES_FLAG_NOCHECKRESP +flag was specified at channel initialization time; otherwise, such +responses are ignored at the +.BR ares_send (3) +level.) +.TP 19 +.B ARES_EREFUSED +The query completed but the server refused the query. (This code can +only occur if the +.B ARES_FLAG_NOCHECKRESP +flag was specified at channel initialization time; otherwise, such +responses are ignored at the +.BR ares_send (3) +level.) +.TP 19 +.B ARES_EBADNAME +The query name +.I name +could not be encoded as a domain name, either because it contained a +zero-length label or because it contained a label of more than 63 +characters. +.TP 19 +.B ARES_ETIMEOUT +No name servers responded within the timeout period. +.TP 19 +.B ARES_ECONNREFUSED +No name servers could be contacted. +.TP 19 +.B ARES_ENOMEM +Memory was exhausted. +.TP 19 +.B ARES_ECANCELLED +The query was cancelled. +.TP 19 +.B ARES_EDESTRUCTION +The name service channel +.I channel +is being destroyed; the query will not be completed. +.PP +The callback argument +.I timeouts +reports how many times a query timed out during the execution of the +given request. +.PP +If the query completed (even if there was something wrong with it, as +indicated by some of the above error codes), the callback argument +.I abuf +points to a result buffer of length +.IR alen . +If the query did not complete, +.I abuf +will be NULL and +.I alen +will be 0. +.SH SEE ALSO +.BR ares_process (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_save_options.3 b/docs/ares_save_options.3 new file mode 100644 index 0000000..bddae04 --- /dev/null +++ b/docs/ares_save_options.3 @@ -0,0 +1,74 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_SAVE_OPTIONS 3 "5 March 2010" +.SH NAME +ares_save_options \- Save configuration values obtained from initialized ares_channel +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.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 +.IR channel , +into the options struct identified by +.IR options , +and saves the mask of options which are set to the integer +pointer (passed by reference) identified by +.IR optmask . + +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 successfully 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 functions. This function will remain +functioning, but it can only return config data that can be represented in +this config struct, which may no longer be the complete set of config +options. \fBares_dup(3)\fP will not have that restriction. + +The ares_options struct can not handle potential IPv6 name servers the +ares_channel might be configured to use. The \fBares_save_options(3)\fP function +will only return IPv4 servers, if any. In order to retrieve all name servers +an ares_channel might be using, the \fBares_get_servers(3)\fP function must be +used instead. +.SH SEE ALSO +.BR ares_destroy_options (3), +.BR ares_init_options (3), +.BR ares_get_servers (3), +.BR ares_dup (3) +.SH AVAILABILITY +ares_save_options(3) was added in c-ares 1.4.0 +.SH AUTHOR +Brad House +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_search.3 b/docs/ares_search.3 new file mode 100644 index 0000000..2c85d20 --- /dev/null +++ b/docs/ares_search.3 @@ -0,0 +1,151 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_SEARCH 3 "24 July 1998" +.SH NAME +ares_search \- Initiate a DNS query with domain search +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B typedef void (*ares_callback)(void *\fIarg\fP, int \fIstatus\fP, +.B int \fItimeouts\fP, unsigned char *\fIabuf\fP, int \fIalen\fP) +.PP +.B void ares_search(ares_channel \fIchannel\fP, const char *\fIname\fP, +.B int \fIdnsclass\fP, int \fItype\fP, ares_callback \fIcallback\fP, +.B void *\fIarg\fP) +.fi +.SH DESCRIPTION +The +.B ares_search +function initiates a series of single-question DNS queries on the name +service channel identified by +.IR channel , +using the channel's search domains as well as a host alias file given +by the HOSTALIAS environment variable. The parameter +.I name +gives the alias name or the base of the query name as a NUL-terminated +C string of period-separated labels; if it ends with a period, the +channel's search domains will not be used. Periods and backslashes +within a label must be escaped with a backslash. The parameters +.I dnsclass +and +.I type +give the class and type of the query using the values defined in +.BR <arpa/nameser.h> . +When the query sequence is complete or has failed, the ares library +will invoke +.IR callback . +Completion or failure of the query sequence may happen immediately, or +may happen during a later call to +.BR ares_process (3) +or +.BR ares_destroy (3). +.PP +The callback argument +.I arg +is copied from the +.B ares_search +argument +.IR arg . +The callback argument +.I status +indicates whether the query sequence ended with a successful query +and, if not, how the query sequence failed. It may have any of the +following values: +.TP 19 +.B ARES_SUCCESS +A query completed successfully. +.TP 19 +.B ARES_ENODATA +No query completed successfully; when the query was tried without a +search domain appended, a response was returned with no answers. +.TP 19 +.B ARES_EFORMERR +A query completed but the server claimed that the query was +malformatted. +.TP 19 +.B ARES_ESERVFAIL +No query completed successfully; when the query was tried without a +search domain appended, the server claimed to have experienced a +failure. (This code can only occur if the +.B ARES_FLAG_NOCHECKRESP +flag was specified at channel initialization time; otherwise, such +responses are ignored at the +.BR ares_send (3) +level.) +.TP 19 +.B ARES_ENOTFOUND +No query completed successfully; when the query was tried without a +search domain appended, the server reported that the queried-for +domain name was not found. +.TP 19 +.B ARES_ENOTIMP +A query completed but the server does not implement the operation +requested by the query. (This code can only occur if the +.B ARES_FLAG_NOCHECKRESP +flag was specified at channel initialization time; otherwise, such +responses are ignored at the +.BR ares_send (3) +level.) +.TP 19 +.B ARES_EREFUSED +A query completed but the server refused the query. (This code can +only occur returned if the +.B ARES_FLAG_NOCHECKRESP +flag was specified at channel initialization time; otherwise, such +responses are ignored at the +.BR ares_send (3) +level.) +.TP 19 +.B ARES_TIMEOUT +No name servers responded to a query within the timeout period. +.TP 19 +.B ARES_ECONNREFUSED +No name servers could be contacted. +.TP 19 +.B ARES_ENOMEM +Memory was exhausted. +.TP 19 +.B ARES_ECANCELLED +The query was cancelled. +.TP 19 +.B ARES_EDESTRUCTION +The name service channel +.I channel +is being destroyed; the query will not be completed. +.PP +The callback argument +.I timeouts +reports how many times a query timed out during the execution of the +given request. +.PP +If a query completed successfully, the callback argument +.I abuf +points to a result buffer of length +.IR alen . +If the query did not complete successfully, +.I abuf +will usually be NULL and +.I alen +will usually be 0, but in some cases an unsuccessful query result may +be placed in +.IR abuf . +.SH SEE ALSO +.BR ares_process (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_send.3 b/docs/ares_send.3 new file mode 100644 index 0000000..b89abfe --- /dev/null +++ b/docs/ares_send.3 @@ -0,0 +1,123 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_SEND 3 "25 July 1998" +.SH NAME +ares_send \- Initiate a DNS query +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B typedef void (*ares_callback)(void *\fIarg\fP, int \fIstatus\fP, +.B int \fItimeouts\fP, unsigned char *\fIabuf\fP, int \fIalen\fP) +.PP +.B void ares_send(ares_channel \fIchannel\fP, const unsigned char *\fIqbuf\fP, +.B int \fIqlen\fP, ares_callback \fIcallback\fP, void *\fIarg\fP) +.fi +.SH DESCRIPTION +The +.B ares_send +function initiates a DNS query on the name service channel identified +by +.IR channel . +The parameters +.I qbuf +and +.I qlen +give the DNS query, which should already have been formatted according +to the DNS protocol. When the query is complete or has failed, the +ares library will invoke +.IR callback . +Completion or failure of the query may happen immediately, or may +happen during a later call to +.BR ares_process (3) +or +.BR ares_destroy (3). +.PP +The callback argument +.I arg +is copied from the +.B ares_send +argument +.IR arg . +The callback argument +.I status +indicates whether the query succeeded and, if not, how it failed. It +may have any of the following values: +.TP 19 +.B ARES_SUCCESS +The query completed. +.TP 19 +.B ARES_EBADQUERY +The query buffer was poorly formed (was not long enough for a DNS +header or was too long for TCP transmission). +.TP 19 +.B ARES_ETIMEOUT +No name servers responded within the timeout period. +.TP 19 +.B ARES_ECONNREFUSED +No name servers could be contacted. +.TP 19 +.B ARES_ENOMEM +Memory was exhausted. +.TP 19 +.B ARES_ECANCELLED +The query was cancelled. +.TP 19 +.B ARES_EDESTRUCTION +The name service channel +.I channel +is being destroyed; the query will not be completed. +.PP +The callback argument +.I timeouts +reports how many times a query timed out during the execution of the +given request. +.PP +If the query completed, the callback argument +.I abuf +points to a result buffer of length +.IR alen . +If the query did not complete, +.I abuf +will be NULL and +.I alen +will be 0. +.PP +Unless the flag +.B ARES_FLAG_NOCHECKRESP +was set at channel initialization time, +.B ares_send +will normally ignore responses whose questions do not match the +questions in +.IR qbuf , +as well as responses with reply codes of +.BR SERVFAIL , +.BR NOTIMP , +and +.BR REFUSED . +Unlike other query functions in the ares library, however, +.B ares_send +does not inspect the header of the reply packet to determine the error +status, so a callback status of +.B ARES_SUCCESS +does not reflect as much about the response as for other query +functions. +.SH SEE ALSO +.BR ares_process (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_set_local_dev.3 b/docs/ares_set_local_dev.3 new file mode 100644 index 0000000..7d82133 --- /dev/null +++ b/docs/ares_set_local_dev.3 @@ -0,0 +1,39 @@ +.\" +.\" Copyright 2010 by Ben Greear <greearb@candelatech.com> +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_SET_LOCAL_DEV 3 "30 June 2010" +.SH NAME +ares_set_local_dev \- Bind to a specific network device when creating sockets. +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B void ares_set_local_dev(ares_channel \fIchannel\fP, const char* \fIlocal_dev_name\fP) +.fi +.SH DESCRIPTION +The \fBares_set_local_dev\fP function causes all future sockets +to be bound to this device with SO_BINDTODEVICE. This forces communications +to go over a certain interface, which can be useful on multi-homed machines. +This option is only supported on Linux, and root privileges are required +for the option to work. If SO_BINDTODEVICE is not supported or the +setsocktop call fails (probably because of permissions), the error is +silently ignored. +.SH SEE ALSO +.BR ares_set_local_ip4 (3) +.BR ares_set_local_ip6 (3) +.SH NOTES +This function was added in c-ares 1.7.4 +.SH AUTHOR +Ben Greear diff --git a/docs/ares_set_local_ip4.3 b/docs/ares_set_local_ip4.3 new file mode 100644 index 0000000..e68e80e --- /dev/null +++ b/docs/ares_set_local_ip4.3 @@ -0,0 +1,34 @@ +.\" +.\" Copyright 2010 by Ben Greear <greearb@candelatech.com> +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_SET_LOCAL_IP4 3 "30 June 2010" +.SH NAME +ares_set_local_ip4 \- Set local IPv4 address outgoing requests. +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B void ares_set_local_ip4(ares_channel \fIchannel\fP, unsigned int \fIlocal_ip\fP) +.fi +.SH DESCRIPTION +The \fBares_set_local_ip4\fP function sets the IP address for outbound +requests. The parameter \fIlocal_ip\fP is specified in host byte order. This +allows users to specify outbound interfaces when used on multi-homed systems. +.SH SEE ALSO +.BR ares_set_local_ip6 (3) +.SH NOTES +This function was added in c-ares 1.7.4 +.SH AUTHOR +Ben Greear diff --git a/docs/ares_set_local_ip6.3 b/docs/ares_set_local_ip6.3 new file mode 100644 index 0000000..e659f5c --- /dev/null +++ b/docs/ares_set_local_ip6.3 @@ -0,0 +1,35 @@ +.\" +.\" Copyright 2010 by Ben Greear <greearb@candelatech.com> +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_SET_LOCAL_IP6 3 "30 June 2010" +.SH NAME +ares_set_local_ip6 \- Set local IPv6 address outgoing requests. +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B void ares_set_local_ip6(ares_channel \fIchannel\fP, const unsigned char* \fIlocal_ip6\fP) +.fi +.SH DESCRIPTION +The \fBares_set_local_ip6\fP function sets the IPv6 address for outbound +IPv6 requests. The parameter \fIlocal_ip6\fP is specified in network byte +order. This allows users to specify outbound interfaces when used on +multi-homed systems. The local_ip6 argument must be 16 bytes in length. +.SH SEE ALSO +.BR ares_set_local_ip4 (3) +.SH NOTES +This function was added in c-ares 1.7.4 +.SH AUTHOR +Ben Greear diff --git a/docs/ares_set_servers.3 b/docs/ares_set_servers.3 new file mode 100644 index 0000000..65ad1e1 --- /dev/null +++ b/docs/ares_set_servers.3 @@ -0,0 +1,95 @@ +.\" +.\" Copyright 2010 by Ben Greear <greearb@candelatech.com> +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_SET_SERVERS 3 "5 March 2010" +.SH NAME +ares_set_servers, ares_set_servers_ports \- Initialize an ares_channel name servers configuration +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_set_servers(ares_channel \fIchannel\fP, struct ares_addr_node *\fIservers\fP) +.B int ares_set_servers_ports(ares_channel \fIchannel\fP, struct ares_addr_port_node *\fIservers\fP) +.fi +.SH DESCRIPTION +The \fBares_set_servers(3)\fP function initializes name servers configuration +for the channel data identified by +.IR channel , +from a +.IR servers +pointer to a linked list of ares_addr_node structs holding name servers +address data. +.PP +The name server linked list pointer argument may be the result of a previous +call to \fBares_get_servers(3)\fP or a linked list of \fBares_addr_node\fP structs +set up by other means. +.PP +The \fBares_set_servers(3)\fP function also allows the specification of UDP and +TCP ports to be used for communication on a per-server basis. The provided +linked list argument may be the result of a previous call to +\fBares_get_servers_ports(3)\fP or a linked list of \fBares_addr_port_node\fP structs +set up by other means. +.PP +This function replaces any potentially previously configured name servers +with the ones given in the linked list. So, in order to configure a channel +with more than one name server all the desired ones must be specified in a +single list. +.PP +The function does not take ownership of the linked list argument. +The caller is responsible for freeing the linked list when no longer needed. +.PP +This function is capable of handling IPv4 and IPv6 name server +addresses simultaneously, rendering \fBares_init_options(3)\fP with +optmask \fBARES_OPT_SERVERS\fP functionally obsolete except for +IPv4-only name server usage. + +.SH RETURN VALUES +.B ares_set_servers(3) +may return any of the following values: +.TP 15 +.B ARES_SUCCESS +The name servers configuration was successfully initialized. +.TP 15 +.B ARES_ENOMEM +The process's available memory was exhausted. +.TP 15 +.B ARES_ENODATA +The channel data identified by +.IR channel +was invalid. +.TP 15 +.B ARES_ENOTINITIALIZED +c-ares library initialization not yet performed. +.TP 15 +.B ARES_ENOTIMP +Changing name servers configuration while queries are outstanding is not implemented. +.SH SEE ALSO +.BR ares_set_servers_csv (3), +.BR ares_get_servers (3), +.BR ares_init_options (3), +.BR ares_dup(3) +.SH AVAILABILITY +\fBares_set_servers(3)\fP was added in c-ares 1.7.1; +\fBares_set_servers_ports(3)\fP was added in c-ares 1.11.0. +.SH AUTHOR +Implementation of this function and associated library internals are based +on code, comments and feedback provided in November and December of 2008 by +Daniel Stenberg, Gregor Jasny, Phil Blundell and Yang Tse, December 2009 +by Cedric Bail, February 2010 by Jakub Hrozek. On March 2010 Yang Tse +shuffled all the bits and this function popped out. +.br +Copyright 1998 by the Massachusetts Institute of Technology. +.br +Copyright (C) 2008-2010 by Daniel Stenberg diff --git a/docs/ares_set_servers_csv.3 b/docs/ares_set_servers_csv.3 new file mode 100644 index 0000000..638d269 --- /dev/null +++ b/docs/ares_set_servers_csv.3 @@ -0,0 +1,67 @@ +.\" +.\" Copyright 2010 by Ben Greear <greearb@candelatech.com> +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_SET_SERVERS_CSV 3 "30 June 2010" +.SH NAME +ares_set_servers_csv, ares_set_servers_ports_csv \- Set list of DNS servers to be used. +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_set_servers_csv(ares_channel \fIchannel\fP, const char* \fIservers\fP) +.B int ares_set_servers_ports_csv(ares_channel \fIchannel\fP, const char* \fIservers\fP) +.fi +.SH DESCRIPTION +The \fBares_set_servers_csv\fP and \fBares_set_servers_ports_csv\fPfunctions set +the list of DNS servers that ARES will query. The format of the servers option is: + +host[:port][,host[:port]]... + +For example: + +192.168.1.100,192.168.1.101,3.4.5.6 +.PP +The \fBares_set_servers_csv\fP function will ignore any port values specified in +the input string, whereare the \fBares_set_servers_ports_csv\fP function will +apply any specified port values as the UDP and TCP port to be used for that +particular nameserver. + +.SH RETURN VALUES +.B ares_set_servers_csv(3) +This function may return any of the following values: +.TP 15 +.B ARES_SUCCESS +The name servers configuration was successfully initialized. +.TP 15 +.B ARES_ENOMEM +The process's available memory was exhausted. +.TP 15 +.B ARES_ENODATA +The channel data identified by +.IR channel +was invalid. +.TP 15 +.B ARES_ENOTINITIALIZED +c-ares library initialization not yet performed. +.TP 15 +.B ARES_ENOTIMP +Changing name servers configuration while queries are outstanding is not implemented. +.SH SEE ALSO +.BR ares_set_servers (3) +.SH AVAILABILITY +\fBares_set_servers_csv\fP was added in c-ares 1.7.2; +\fBares_set_servers_ports_csv\fP was added in c-ares 1.11.0. +.SH AUTHOR +Ben Greear diff --git a/docs/ares_set_servers_ports.3 b/docs/ares_set_servers_ports.3 new file mode 100644 index 0000000..a3be189 --- /dev/null +++ b/docs/ares_set_servers_ports.3 @@ -0,0 +1 @@ +.so man3/ares_set_servers.3 diff --git a/docs/ares_set_servers_ports_csv.3 b/docs/ares_set_servers_ports_csv.3 new file mode 100644 index 0000000..30535c6 --- /dev/null +++ b/docs/ares_set_servers_ports_csv.3 @@ -0,0 +1 @@ +.so man3/ares_set_servers_csv.3 diff --git a/docs/ares_set_socket_callback.3 b/docs/ares_set_socket_callback.3 new file mode 100644 index 0000000..14a5ad2 --- /dev/null +++ b/docs/ares_set_socket_callback.3 @@ -0,0 +1,32 @@ +.\" +.TH ARES_SET_SOCKET_CALLBACK 3 "20 Nov 2009" +.SH NAME +ares_set_socket_callback \- Set a socket creation callback +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B typedef int (*ares_sock_create_callback)(ares_socket_t \fIsocket_fd\fP, + int \fItype\fP, + void *\fIuserdata\fP) +.PP +.B void ares_set_socket_callback(ares_channel \fIchannel\fP, + ares_sock_create_callback \fIcallback\fP, + void *\fIuserdata\fP) +.PP +.B cc file.c -lcares +.fi +.SH DESCRIPTION +.PP +This function sets a \fIcallback\fP in the given ares channel handle. This +callback function will be invoked after the socket has been created, and +connected to the remote server. The callback must return ARES_SUCCESS if +things are fine, or return -1 to signal an error. A returned error will +abort the ares operation. +.SH SEE ALSO +.BR ares_init_options (3), ares_set_socket_configure_callback (3) +.SH AVAILABILITY +ares_set_socket_callback(3) was added in c-ares 1.6.0 +.SH AUTHOR +Gregor Jasny + diff --git a/docs/ares_set_socket_configure_callback.3 b/docs/ares_set_socket_configure_callback.3 new file mode 100644 index 0000000..d3b2f93 --- /dev/null +++ b/docs/ares_set_socket_configure_callback.3 @@ -0,0 +1,33 @@ +.\" +.TH ARES_SET_SOCKET_CONFIGURE_CALLBACK 3 "6 Feb 2016" +.SH NAME +ares_set_socket_configure_callback \- Set a socket configuration callback +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B typedef int (*ares_sock_config_callback)(ares_socket_t \fIsocket_fd\fP, + int \fItype\fP, + void *\fIuserdata\fP) +.PP +.B void ares_set_socket_configure_callback(ares_channel \fIchannel\fP, + ares_sock_config_callback \fIcallback\fP, + void *\fIuserdata\fP) +.PP +.B cc file.c -lcares +.fi +.SH DESCRIPTION +.PP +This function sets a \fIcallback\fP in the given ares channel handle. This +callback function will be invoked after the socket has been created, but +before it has been connected to the remote server, which is an ideal time +to configure various socket options. The callback must return ARES_SUCCESS +if things are fine, or return -1 to signal an error. A returned error will +abort the ares operation. +.SH SEE ALSO +.BR ares_init_options (3), ares_set_socket_callback (3) +.SH AVAILABILITY +ares_set_socket_configure_callback(3) was added in c-ares 1.11.0 +.SH AUTHOR +Andrew Ayer + diff --git a/docs/ares_set_socket_functions.3 b/docs/ares_set_socket_functions.3 new file mode 100644 index 0000000..1cb0b85 --- /dev/null +++ b/docs/ares_set_socket_functions.3 @@ -0,0 +1,99 @@ +.\" +.TH ARES_SET_SOCKET_FUNCTIONS 3 "13 Dec 2016" +.SH NAME +ares_set_socket_functions \- Set socket io callbacks +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B struct ares_socket_functions { + ares_socket_t(*\fIasocket\fP)(int, int, int, void *); + int(*\fIaclose\fP)(ares_socket_t, void *); + int(*\fIaconnect\fP)(ares_socket_t, const struct sockaddr *, ares_socklen_t, void *); + ares_ssize_t(*\fIarecvfrom\fP)(ares_socket_t, void *, size_t, int, struct sockaddr *, ares_socklen_t *, void *); + ares_ssize_t(*\fIasendv\fP)(ares_socket_t, const struct iovec *, int, void *); + }; + +.PP +.B void ares_set_socket_functions(ares_channel \fIchannel\fP, + const struct ares_socket_functions * \fIfunctions\fP, + void *\fIuser_data\fP); + +.fi +.SH DESCRIPTION +.PP +This function sets a set of callback \fIfunctions\fP in the given ares channel handle. +These callback functions will be invoked to create/destroy socket objects and perform +io, instead of the normal system calls. A client application can override normal network +operation fully through this functionality, and provide its own transport layer. +.PP +All callback functions are expected to operate like their system equivalents, and to +set +.BR errno(3) +to an appropriate error code on failure. C-ares also expects all io functions to behave +asynchronously, i.e. as if the socket object has been set to non-blocking mode. Thus +read/write calls (for TCP connections) are expected to often generate +.BR EAGAIN +or +.BR EWOULDBLOCK. + +.PP +The \fIuser_data\fP value is provided to each callback function invocation to serve as +context. +.PP +The +.B ares_socket_functions +must provide the following callbacks: +.TP 18 +.B \fIasocket\fP +.B ares_socket_t(*)(int \fIdomain\fP, int \fItype\fP, int \fIprotocol\fP, void * \fIuser_data\fP) +.br +Creates an endpoint for communication and returns a descriptor. \fIdomain\fP, \fItype\fP, and \fIprotocol\fP +each correspond to the parameters of +.BR socket(2). +Returns ahandle to the newly created socket, or -1 on error. +.TP 18 +.B \fIaclose\fP +.B int(*)(ares_socket_t \fIfd\fP, void * \fIuser_data\fP) +.br +Closes the socket endpoint indicated by \fIfd\fP. See +.BR close(2) +.TP 18 +.B \fIaconnect\fP +.B int(*)(ares_socket_t \fIfd\fP, const struct sockaddr * \fIaddr\fP, ares_socklen_t \fIaddr_len\fP, void * \fIuser_data\fP) +.br +Initiate a connection to the address indicated by \fIaddr\fP on a socket. See +.BR connect(2) + +.TP 18 +.B \fIarecvfrom\fP +.B ares_ssize_t(*)(ares_socket_t \fIfd\fP, void * \fIbuffer\fP, size_t \fIbuf_size\fP, int \fIflags\fP, struct sockaddr * \fIaddr\fP, ares_socklen_t * \fIaddr_len\fP, void * \fIuser_data\fP) +.br +Receives data from remote socket endpoint, if available. If the \fIaddr\fP parameter is not NULL and the connection protocol provides the source address, the callback should fill this in. See +.BR recvfrom(2) + +.TP 18 +.B \fIasendv\fP +.B ares_ssize_t(*)(ares_socket_t \fIfd\fP, const struct iovec * \fIdata\fP, int \fIlen\fP, void * \fIuser_data\fP) +.br +Send data, as provided by the iovec array \fIdata\fP, to the socket endpoint. See +.BR writev(2), + +.PP +The +.B ares_socket_functions +struct provided is not copied but directly referenced, +and must thus remain valid through out the channels and any created socket's lifetime. +.SH AVAILABILITY +Added in c-ares 1.13.0 +.SH SEE ALSO +.BR ares_init_options (3), +.BR socket(2), +.BR close(2), +.BR connect(2), +.BR recv(2), +.BR recvfrom(2), +.BR send(2), +.BR writev(2) +.SH AUTHOR +Carl Wilund diff --git a/docs/ares_set_sortlist.3 b/docs/ares_set_sortlist.3 new file mode 100644 index 0000000..24a9790 --- /dev/null +++ b/docs/ares_set_sortlist.3 @@ -0,0 +1,58 @@ +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_SET_SORTLIST 3 "23 November 2015" +.SH NAME +ares_set_sortlist \- Initialize an ares_channel sortlist configuration +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B int ares_set_sortlist(ares_channel \fIchannel\fP, const char *\fIsortstr\fP) +.fi +.SH DESCRIPTION +The \fBares_set_sortlist(3)\fP function initializes an address sortlist configuration +for the channel data identified by +.IR channel , +so that addresses returned by \fBares_gethostbyname(3)\fP are sorted according to the +sortlist. The provided +.IR sortstr +string that holds a space separated list of IP-address-netmask pairs. The +netmask is optional but follows the address after a slash if present. For example, +"130.155.160.0/255.255.240.0 130.155.0.0". + +This function replaces any potentially previously configured address sortlist +with the ones given in the configuration string. + +.SH RETURN VALUES +.B ares_set_sortlist(3) +may return any of the following values: +.TP 15 +.B ARES_SUCCESS +The sortlist configuration was successfully initialized. +.TP 15 +.B ARES_ENOMEM +The process's available memory was exhausted. +.TP 15 +.B ARES_ENODATA +The channel data identified by +.IR channel +was invalid. +.TP 15 +.B ARES_ENOTINITIALIZED +c-ares library initialization not yet performed. +.SH SEE ALSO +.BR ares_init_options (3), +.BR ares_dup(3) +.SH AVAILABILITY +ares_set_sortlist(3) was added in c-ares 1.11.0 diff --git a/docs/ares_strerror.3 b/docs/ares_strerror.3 new file mode 100644 index 0000000..4b50d5b --- /dev/null +++ b/docs/ares_strerror.3 @@ -0,0 +1,37 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_STRERROR 3 "25 July 1998" +.SH NAME +ares_strerror \- Get the description of an ares library error code +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B const char *ares_strerror(int \fIcode\fP) +.fi +.SH DESCRIPTION +The +.B ares_strerror +function gets the description of the ares library error code +.IR code , +returning the result as a NUL-terminated C string. +.SH NOTES +This function is not compatible with ares, it takes a different set of +arguments. +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_timeout.3 b/docs/ares_timeout.3 new file mode 100644 index 0000000..c57685d --- /dev/null +++ b/docs/ares_timeout.3 @@ -0,0 +1,46 @@ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_TIMEOUT 3 "25 July 1998" +.SH NAME +ares_timeout \- return maximum time to wait +.SH SYNOPSIS +.nf +#include <ares.h> + +struct timeval *ares_timeout(ares_channel \fIchannel\fP, + struct timeval *\fImaxtv\fP, + struct timeval *\fItv\fP) +.fi +.SH DESCRIPTION +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 +\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_fd (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. diff --git a/docs/ares_version.3 b/docs/ares_version.3 new file mode 100644 index 0000000..9ba7831 --- /dev/null +++ b/docs/ares_version.3 @@ -0,0 +1,35 @@ +.\" +.\" Copyright 2004 by Daniel Stenberg +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_VERSION 3 "29 January 2004" +.SH NAME +ares_version \- Get the version number of the library +.SH SYNOPSIS +.nf +#include <ares.h> + +const char *ares_version(int *\fIversion\fP) +.fi +.SH DESCRIPTION +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 "SEE ALSO" +.BR ares_init (3), +.BR ares_library_init (3) |