pax_global_header00006660000000000000000000000064136262230710014514gustar00rootroot0000000000000052 comment=1b3f57079297f7dead1723f0f6d567e77ae60d83 getdns-1.6.0/000077500000000000000000000000001362622307100130045ustar00rootroot00000000000000getdns-1.6.0/AUTHORS000066400000000000000000000004121362622307100140510ustar00rootroot00000000000000Craig Despeaux Neel Goyal Allison Mankin Melinda Shore Willem Toorop W.C.A. Wijngaards Glen Wiley getdns-1.6.0/CMakeLists.txt000066400000000000000000001237761362622307100155640ustar00rootroot00000000000000cmake_minimum_required(VERSION 3.5 FATAL_ERROR) if (POLICY CMP0075) cmake_policy(SET CMP0075 NEW) endif () # The following must be set BEFORE doing project() or enable_language(). if (NOT CMAKE_BUILD_TYPE) message(STATUS "No build type defined; defaulting to 'Debug'") set(CMAKE_BUILD_TYPE "Debug" CACHE STRING "The type of build. Possible values are: Debug, Release, RelWithDebInfo and MinSizeRel.") endif () set(PACKAGE "getdns") set(PACKAGE_NAME "getdns") set(PACKAGE_VERSION "1.6.0") set(PACKAGE_BUGREPORT "team@getdnsapi.net") set(PACKAGE_URL "https://getdnsapi.net") # Dont forget to put a dash in front of the release candidate!!! # That is how it is done with semantic versioning! set(RELEASE_CANDIDATE "") set(PACKAGE_STRING "${PACKAGE_NAME} ${PACKAGE_VERSION}${RELEASE_CANDIDATE}") set(PACKAGE_TARNAME "${PACKAGE}-${PACKAGE_VERSION}${RELEASE_CANDIDATE}") set(GETDNS_VERSION "${PACKAGE_VERSION}${RELEASE_CANDIDATE}") set(GETDNS_NUMERIC_VERSION 0x01060000) set(API_VERSION "December 2015") set(API_NUMERIC_VERSION 0x07df0c00) # Library version # --------------- # current:revision:age # (binary-api-number):(which-binary-api-version):(how-many-nrs-backwardscompat) # if source code changes increment revision # if any interfaces have been added/removed/changed since last update then # increment current and set revision to 0 # if any interfaces have been added since the last public release then increment age # if any interfaces have been removed or changed since the last public release then # set age to 0 # # getdns-0.1.4 had libversion 0:0:0 # getdns-0.1.5 had libversion 1:0:0 # getdns-0.1.6 had libversion 1:1:0 # getdns-0.1.7 had libversion 1:2:1 (but should have had 2:0:1) # getdns-0.1.8 had libversion 1:3:0 (but should have had 2:1:1) # getdns-0.2.0 had libversion 2:2:1 # getdns-0.3.0 had libversion 3:3:2 # getdns-0.3.1 had libversion 3:4:2 # getdns-0.3.2 had libversion 3:5:2 # getdns-0.3.3 had libversion 3:6:2 # getdns-0.5.0 had libversion 4:0:3 # getdns-0.5.1 had libversion 4:1:3 (but should have been getdns-0.6.0) # getdns-0.9.0 had libversion 5:0:4 # getdns-1.0.0 had libversion 5:1:4 # getdns-1.1.0 had libversion 6:0:0 # getdns-1.1.1 had libversion 6:1:0 # getdns-1.1.2 had libversion 7:0:1 # getdns-1.1.3 had libversion 7:1:1 # getdns-1.2.0 had libversion 8:0:2 # getdns-1.2.1 had libversion 8:1:2 # getdns-1.3.0 had libversion 9:0:3 # getdns-1.4.0 had libversion 10:0:0 # getdns-1.4.1 had libversion 10:1:0 # getdns-1.4.2 had libversion 10:2:0 # getdns-1.5.0 had libversion 11:0:1 # getdns-1.5.1 had libversion 11:1:1 # getdns-1.5.2 had libversion 11:2:1 # getdns-1.6.0 has libversion 11:3:1 set(GETDNS_VERSION_CURRENT 11) set(GETDNS_VERSION_REVISION 3) set(GETDNS_VERSION_AGE 1) project(getdns VERSION ${PACKAGE_VERSION} LANGUAGES C) set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules/") include(CheckCSourceRuns) include(CheckFunctionExists) include(CheckIncludeFile) include(CheckLibraryExists) include(CheckSymbolExists) include(CheckTypeSize) include(CMakeDependentOption) include(CTest) include(GNUInstallDirs) include(TestBigEndian) include(TargetSharedLibraryExports) include(TargetSharedLibraryVersion) # Target Platform if (WIN32 OR MINGW OR MSYS OR CYGWIN) set(HOSTOS "windows") set(GETDNS_ON_WINDOWS 1) set(USE_WINSOCK 1) elseif (APPLE) set(HOSTOS "macos") set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -D_DARWIN_C_SOURCE") elseif (UNIX) set(HOSTOS "unix") if (NOT ${CMAKE_SYSTEM_NAME} STREQUAL "FreeBSD") set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -D_POSIX_C_SOURCE=200112L -D_XOPEN_SOURCE=600") endif () if (${CMAKE_SYSTEM_NAME} STREQUAL "Linux") set(LINUX 1) set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -D_BSD_SOURCE -D_DEFAULT_SOURCE") elseif (${CMAKE_SYSTEM_NAME} STREQUAL "Solaris") set(SOLARIS 1) set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -D__EXTENSIONS_") endif () endif () test_big_endian(TARGET_IS_BIG_ENDIAN) set(HAVE_TARGET_ENDIANNESS 1) # Options. option(ENABLE_SHARED "Build shared libraries." ON) option(ENABLE_STATIC "Build static libraries." ON) if ((NOT ENABLE_SHARED) AND (NOT ENABLE_STATIC)) message(FATAL_ERROR "You must build either static or shared libraries.") endif () option(ENABLE_DEBUG_ALL "Enable all debugging messages.") cmake_dependent_option(ENABLE_DEBUG_REQ "Enable request debugging messages." OFF "NOT ENABLE_DEBUG_ALL" ON) cmake_dependent_option(ENABLE_DEBUG_SCHED "Enable scheduling debugging messages." OFF "NOT ENABLE_DEBUG_ALL" ON) cmake_dependent_option(ENABLE_DEBUG_STUB "Enable stub debugging messages." OFF "NOT ENABLE_DEBUG_ALL" ON) cmake_dependent_option(ENABLE_DEBUG_DAEMON "Enable daemon debugging messages." OFF "NOT ENABLE_DEBUG_ALL" ON) cmake_dependent_option(ENABLE_DEBUG_DNSSEC "Enable DNSSEC debugging messages." OFF "NOT ENABLE_DEBUG_ALL" ON) cmake_dependent_option(ENABLE_DEBUG_SERVER "Enable server debugging messages." OFF "NOT ENABLE_DEBUG_ALL" ON) cmake_dependent_option(ENABLE_DEBUG_ANCHOR "Enable anchor debugging messages." OFF "NOT ENABLE_DEBUG_ALL" ON) option(ENABLE_SHA1 "Enable SHA1 RRSIG support." ON) option(ENABLE_SHA2 "Enable SHA256 and SHA512 RRSIG support." ON) option(ENABLE_GOST "Enable GOST support." ON) option(ENABLE_ECDSA "Enable ECDSA support." ON) option(ENABLE_DSA "Enable DSA support." ON) option(ENABLE_ED25519 "Enable ED25519 support." ON) option(ENABLE_ED448 "Enable ED448 support." ON) option(ENABLE_DRAFT_MDNS_SUPPORT "Enable draft mdns client support.") option(ENABLE_EDNS_COOKIES "Enable EDNS cookies." ON) option(ENABLE_NATIVE_STUB_DNSSEC "Enable native stub DNSSEC support." ON) option(ENABLE_POLL_EVENTLOOP "Enable default eventloop based on poll." ON) if (WIN32) option(ENABLE_STUB_ONLY "Restrict resolution modes to STUB." ON) else() option(ENABLE_STUB_ONLY "Restrict resolution modes to STUB." OFF) endif() option(ENABLE_TCP_FAST_OPEN "Enable use of TCP Fast Open." ON) option(ENABLE_UNBOUND_EVENT_API "Enable usage of libunbound's event API." ON) option(BUILD_DOXYGEN "Build source documentation." OFF) option(BUILD_EXAMPLES "Compile the example programs." OFF) option(BUILD_GETDNS_QUERY "Compile and install the getdns_query tool." ON) option(BUILD_GETDNS_SERVER_MON "Compile and install the getdns_server_mon tool." ON) option(BUILD_STUBBY "Compile and install stubby, the (stub) resolver daemon." OFF) option(BUILD_LIBEV "Build libev support library if available." ON) option(BUILD_LIBEVENT2 "Build libevent2 support library if available." ON) option(BUILD_LIBUV "Build libuv support library available." ON) option(USE_LIBIDN2 "Use libidn2 if available." ON) option(USE_GNUTLS "Use GnuTLS for TLS connections." OFF) # Above names chosen for user consistency. Now define substituted names. set(REQ_DEBUG ${ENABLE_DEBUG_REQ}) set(SCHED_DEBUG ${ENABLE_DEBUG_SCHED}) set(STUB_DEBUG ${ENABLE_DEBUG_STUB}) set(DAEMON_DEBUG ${ENABLE_DEBUG_DAEMON}) set(SEC_DEBUG ${ENABLE_DEBUG_DNSSEC}) set(SERVER_DEBUG ${ENABLE_DEBUG_SERVER}) set(ANCHOR_DEBUG ${ENABLE_DEBUG_ANCHOR}) set(EDNS_COOKIES ${ENABLE_EDNS_COOKIES}) set(USE_SHA1 ${ENABLE_SHA1}) set(USE_SHA2 ${ENABLE_SHA2}) set(USE_GOST ${ENABLE_GOST}) set(USE_ECDSA ${ENABLE_ECDSA}) set(USE_DSA ${ENABLE_DSA}) set(USE_ED25519 ${ENABLE_ED25519}) set(USE_ED448 ${ENABLE_ED448}) set(HAVE_MDNS_SUPPORT ${ENABLE_DRAFT_MDNS_SUPPORT}) set(STUB_NATIVE_DNSSEC ${ENABLE_NATIVE_STUB_DNSSEC}) set(USE_LIBEV ${BUILD_LIBEV}) set(USE_LIBEVENT2 ${BUILD_LIBEVENT2}) set(USE_LIBUV ${BUILD_LIBUV}) option(ENABLE_DEBUG_KEEP_CONNECTIONS_OPEN "Disable connection idle timeout. Do not enable.") mark_as_advanced(ENABLE_DEBUG_KEEP_CONNECTIONS_OPEN) set(KEEP_CONNECTIONS_OPEN_DEBUG ${ENABLE_DEBUG_KEEP_CONNECTIONS_OPEN}) # Options variables. string(TIMESTAMP timestamp "%Y-%m-%dT%H:%M:%SZ") set(CURRENT_DATE "${timestamp}" CACHE STRING "Current date of the compilation, set to fixed date for reproducible builds.") set(DNSSEC_ROADBLOCK_AVOIDANCE ON CACHE BOOL "Enable/disable DNSSEC roadblock avoidance.") set(FD_SETSIZE "" CACHE STRING "Set maximum file descriptor number that can be used by select.") set(MAX_UDP_BACKOFF 1000 CACHE STRING "Set the maximum number of messages that can be sent to other upstreams before the upstream which has previously timed out will be tried again.") if (WIN32) # BUG! Don't hardcode the Windows directory and drive. set(hostsfile "C:/Windows/System32/Drivers/etc/hosts") else () set(hostsfile "/etc/hosts") endif () set(PATH_HOSTS "${hostsfile}" CACHE STRING "Set the static table lookup for hostnames path.") set(PATH_RESOLVCONF "/etc/resolv.conf" CACHE STRING "Set the resolver configuration file path. Not used on Windows, where values are retrieved via GetNetworkParams().") set(PATH_TRUST_ANCHOR_FILE "${CMAKE_INSTALL_FULL_SYSCONFDIR}/unbound/getdns-root.key" CACHE STRING "Default location of the trust anchor file.") # Ensure option variables in config.h that get values from the above are # defined, and so will actually appear in config.h. set(GETDNS_FN_HOSTS 1) set(GETDNS_FN_RESOLVCONF 1) set(TRUST_ANCHOR_FILE 1) set(UDP_MAX_BACKOFF 1) # Options not exposed in autoconf. set(DRAFT_RRTYPES 1) set(EDNS_COOKIE_OPCODE 10) set(EDNS_COOKIE_ROLLOVER_TIME "(24*60*60)") set(EDNS_PADDING_OPCODE 12) set(MAX_CNAME_REFERRALS 100) set(MAXIMUM_UPSTREAM_OPTION_SPACE 3000) # Values derived from options. set(GETDNS_COMPILATION_COMMENT "${PACKAGE_NAME} ${GETDNS_VERSION} configured on ${CURRENT_DATE} for the ${API_VERSION} version of the API") # Compiler flags if (MSVC) # The Visual Studio C compiler is C90 with some of C99 and C11. # So full on warnings are not appropriate. add_compile_options(/W2) else () add_compile_options(-Wall -Wextra -Wpedantic) endif () # Windows. Uh-oh. set(getdns_system_libs "") set(static_lib_suffix "") if (DEFINED GETDNS_ON_WINDOWS) set(static_lib_suffix "_static") list(APPEND getdns_system_libs "ws2_32" "crypt32" "gdi32" "iphlpapi" "psapi" "userenv" ) endif () # Check for include files check_include_file(assert.h HAVE_ASSERT_H) check_include_file(inttypes.h HAVE_INTTYPES_H) check_include_file(limits.h HAVE_LIMITS_H) check_include_file(sys/limits.h HAVE_SYS_LIMITS_H) check_include_file(stdarg.h HAVE_STDARG_H) check_include_file(stdint.h HAVE_STDINT_H) check_include_file(stdio.h HAVE_STDIO_H) check_include_file(stdlib.h HAVE_STDLIB_H) check_include_file(string.h HAVE_STRING_H) check_include_file(strings.h HAVE_STRINGS_H) check_include_file(time.h HAVE_TIME_H) check_include_file(unistd.h HAVE_UNISTD_H) check_include_file(fcntl.h HAVE_FCNTL_H) check_include_file(signal.h HAVE_SIGNAL_H) check_include_file(sys/poll.h HAVE_SYS_POLL_H) check_include_file(poll.h HAVE_POLL_H) check_include_file(resource.h HAVE_RESOURCE_H) check_include_file(sys/types.h HAVE_SYS_TYPES_H) check_include_file(sys/stat.h HAVE_SYS_STAT_H) check_include_file(endian.h HAVE_ENDIAN_H) check_include_file(netdb.h HAVE_NETDB_H) check_include_file(arpa/inet.h HAVE_ARPA_INET_H) check_include_file(netinet/in.h HAVE_NETINET_IN_H) check_include_file(sys/select.h HAVE_SYS_SELECT_H) check_include_file(sys/socket.h HAVE_SYS_SOCKET_H) check_include_file(sys/sysctl.h HAVE_SYS_SYSCTL_H) check_include_file(sys/time.h HAVE_SYS_TIME_H) check_include_file(sys/wait.h HAVE_SYS_WAIT_H) check_include_file(windows.h HAVE_WINDOWS_H) check_include_file(winsock.h HAVE_WINSOCK_H) check_include_file(winsock2.h HAVE_WINSOCK2_H) check_include_file(ws2tcpip.h HAVE_WS2TCPIP_H) # Check for include declarations check_symbol_exists(getentropy unistd.h HAVE_DECL_GETENTROPY) if (DEFINED GETDNS_ON_WINDOWS) set(CMAKE_REQUIRED_LIBRARIES ${getdns_system_libs}) check_symbol_exists(inet_pton ws2tcpip.h HAVE_DECL_INET_PTON) check_symbol_exists(inet_ntop ws2tcpip.h HAVE_DECL_INET_NTOP) else () check_symbol_exists(inet_pton arpa/inet.h HAVE_DECL_INET_PTON) check_symbol_exists(inet_ntop arpa/inet.h HAVE_DECL_INET_NTOP) endif () check_symbol_exists(mkstemp stdlib.h HAVE_DECL_MKSTEMP) check_symbol_exists(sigemptyset signal.h HAVE_DECL_SIGEMPTYSET) check_symbol_exists(sigfillset signal.h HAVE_DECL_SIGFILLSET) check_symbol_exists(sigaddset signal.h HAVE_DECL_SIGADDSET) check_symbol_exists(strptime time.h HAVE_DECL_STRPTIME) # Check for functions check_function_exists(fcntl HAVE_FCNTL) check_function_exists(getauxval HAVE_GETAUXVAL) check_function_exists(gettimeofday HAVE_GETTIMEOFDAY) check_function_exists(ioctlsocket HAVE_IOCTLSOCKET) check_function_exists(sigemptyset HAVE_SIGEMPTYSET) check_function_exists(sigfillset HAVE_SIGFILLSET) check_function_exists(sigaddset HAVE_SIGADDSET) check_function_exists(strptime HAVE_STRPTIME) # Check for types check_type_size(sigset_t SIGSET_T) check_type_size(_sigset_t _SIGSET_T) # SSL library find_package(OpenSSL "1.0.2" REQUIRED) set(HAVE_SSL 1) set(tlsdir "openssl") set(CMAKE_REQUIRED_INCLUDES ${OPENSSL_INCLUDE_DIR}) check_include_file(openssl/ssl.h HAVE_OPENSSL_SSL_H) check_include_file(openssl/evp.h HAVE_OPENSSL_EVP_H) check_include_file(openssl/err.h HAVE_OPENSSL_ERR_H) check_include_file(openssl/rand.h HAVE_OPENSSL_RAND_H) check_include_file(openssl/conf.h HAVE_OPENSSL_CONF_H) check_include_file(openssl/engine.h HAVE_OPENSSL_ENGINE_H) set(CMAKE_REQUIRED_LIBRARIES ${OPENSSL_LIBRARIES}) check_function_exists(DSA_SIG_set0 HAVE_DSA_SIG_SET0) check_function_exists(DSA_set0_pqg HAVE_DSA_SET0_PQG) check_function_exists(DSA_set0_key HAVE_DSA_SET0_KEY) check_function_exists(RSA_set0_key HAVE_RSA_SET0_KEY) check_function_exists(EVP_md5 HAVE_EVP_MD5) check_function_exists(EVP_sha1 HAVE_EVP_SHA1) check_function_exists(EVP_sha224 HAVE_EVP_SHA224) check_function_exists(EVP_sha256 HAVE_EVP_SHA256) check_function_exists(EVP_sha384 HAVE_EVP_SHA384) check_function_exists(EVP_sha512 HAVE_EVP_SHA512) check_function_exists(EVP_dss1 HAVE_EVP_DSS1) check_function_exists(EVP_DigestVerify HAVE_EVP_DIGESTVERIFY) check_function_exists(EVP_MD_CTX_new HAVE_EVP_MD_CTX_NEW) check_function_exists(HMAC_CTX_new HAVE_HMAC_CTX_NEW) check_function_exists(OpenSSL_version_num HAVE_OPENSSL_VERSION_NUM) check_function_exists(OpenSSL_version HAVE_OPENSSL_VERSION) check_function_exists(SSL_CTX_dane_enable HAVE_SSL_CTX_DANE_ENABLE) check_function_exists(SSL_CTX_set_ciphersuites HAVE_SSL_CTX_SET_CIPHERSUITES) check_function_exists(SSL_set_ciphersuites HAVE_SSL_SET_CIPHERSUITES) check_function_exists(OPENSSL_init_crypto HAVE_OPENSSL_INIT_CRYPTO) check_symbol_exists(SSL_dane_enable "openssl/ssl.h" HAVE_SSL_DANE_ENABLE) check_symbol_exists(SSL_CTX_set1_curves_list "openssl/ssl.h" HAVE_DECL_SSL_CTX_SET1_CURVES_LIST) check_symbol_exists(SSL_set1_curves_list "openssl/ssl.h" HAVE_DECL_SSL_SET1_CURVES_LIST) check_symbol_exists(SSL_set_min_proto_version "openssl/ssl.h" HAVE_DECL_SSL_SET_MIN_PROTO_VERSION) check_symbol_exists(TLS_client_method "openssl/ssl.h" HAVE_TLS_CLIENT_METHOD) check_symbol_exists(X509_get_notAfter "openssl/x509.h" HAVE_X509_GET_NOTAFTER) check_symbol_exists(X509_get0_notAfter "openssl/x509.h" HAVE_X509_GET0_NOTAFTER) check_symbol_exists(NID_ED25519 "openssl/obj_mac.h" HAVE_SSL_ED25519) check_symbol_exists(NID_ED448 "openssl/obj_mac.h" HAVE_SSL_ED448) # Threading library set(THREADS_PREFER_PTHREAD_FLAG ON) find_package(Threads REQUIRED) if (CMAKE_USE_PTHREADS_INIT) set(HAVE_PTHREAD 1) elseif (CMAKE_USE_WIN32_THREADS_INIT) set(HAVE_WINDOWS_THREADS 1) else () message(WARNING "Neither pthreads nor Windows threading available.") endif () # Libidn2 if (USE_LIBIDN2) find_package(Libidn2 "2.0.0" REQUIRED) if (Libidn2_FOUND) set(HAVE_LIBIDN2 1) else() message(FATAL_ERROR "Libidn2 required but not found. Disable with USE_LIBIDN2 option.") endif() endif() # GnuTLS and Nettle. If using GnuTLS, we need the Nettle dev stuff to # handle digital signature algorithms. GnuTLS uses Nettle internally. if (USE_GNUTLS) find_package(GnuTLS "3.5.0" REQUIRED) find_package(Nettle "3.2" REQUIRED) set(tlsdir "gnutls") set(HAVE_NETTLE 1) set(CMAKE_REQUIRED_INCLUDES ${NETTLE_INCLUDE_DIR}) set(CMAKE_REQUIRED_LIBRARIES ${NETTLE_LIBRARIES}) check_include_file(nettle/dsa-compat.h HAVE_NETTLE_DSA_COMPAT_H) check_include_file(nettle/eddsa.h HAVE_NETTLE_EDDSA_H) # API change in Nettle 3.4. check_symbol_exists(nettle_get_secp_256r1 "nettle/ecc-curve.h" HAVE_NETTLE_GET_SECP_256R1) check_symbol_exists(nettle_get_secp_384r1 "nettle/ecc-curve.h" HAVE_NETTLE_GET_SECP_384R1) endif() # Sort out what signature algorithms can be used. if (USE_ED25519) if (USE_GNUTLS) if (NOT HAVE_NETTLE_EDDSA_H) message(WARNING "ED25519 enabled and Nettle does not support it. Disabled.") unset(USE_ED25519) endif () elseif (NOT HAVE_SSL_ED25519) message(WARNING "ED25519 enabled and OpenSSL does not support it. Disabled.") unset(USE_ED25519) endif () endif () if (USE_ED448) if (USE_GNUTLS) message(WARNING "ED448 enabled and Nettle support not implemented. Disabled.") unset(USE_ED448) elseif (NOT HAVE_SSL_ED448) message(WARNING "ED448 enabled and OpenSSL does not support it. Disabled.") unset(USE_ED448) endif () endif () # Stuff that might be in a BSD library check_symbol_exists(strlcpy string.h HAVE_DECL_STRLCPY) check_symbol_exists(arc4random stdlib.h HAVE_DECL_ARC4RANDOM) check_symbol_exists(arc4random_uniform stdlib.h HAVE_DECL_ARC4RANDOM_UNIFORM) check_function_exists(strlcpy HAVE_STRLCPY) check_function_exists(arc4random HAVE_ARC4RANDOM) check_function_exists(arc4random_uniform HAVE_ARC4RANDOM_UNIFORM) if (NOT (HAVE_STRLCPY AND HAVE_DECL_STRLCPY AND HAVE_ARC4RANDOM AND HAVE_DECL_ARC4RANDOM AND HAVE_ARC4RANDOM_UNIFORM AND HAVE_DECL_ARC4RANDOM_UNIFORM)) find_library(BSD_LIBRARY bsd) if (BSD_LIBRARY) unset(CMAKE_REQUIRED_LIBRARIES) set(CMAKE_REQUIRED_LIBRARIES ${BSD_LIBRARY}) mark_as_advanced(BSD_LIBRARY) list(APPEND getdns_system_libs ${BSD_LIBRARY}) check_include_file(bsd/stdlib.h HAVE_BSD_STDLIB_H) check_include_file(bsd/string.h HAVE_BSD_STRING_H) check_symbol_exists(strlcpy "bsd/string.h" HAVE_BSD_DECL_STRLCPY) set(HAVE_DECL_STRLCPY ${HAVE_BSD_DECL_STRLCPY}) check_symbol_exists(arc4random "bsd/stdlib.h" HAVE_BSD_DECL_ARC4RANDOM) set(HAVE_DECL_ARC4RANDOM ${HAVE_BSD_DECL_ARC4RANDOM}) check_symbol_exists(arc4random_uniform "bsd/stdlib.h" HAVE_BSD_DECL_ARC4RANDOM_UNIFORM) set(HAVE_DECL_ARC4RANDOM_UNIFORM ${HAVE_BSD_DECL_ARC4RANDOM_UNIFORM}) check_function_exists(strlcpy HAVE_BSD_STRLCPY) set(HAVE_STRLCPY ${HAVE_BSD_STRLCPY}) check_function_exists(arc4random HAVE_BSD_ARC4RANDOM) set(HAVE_ARC4RANDOM ${HAVE_BSD_ARC4RANDOM}) check_function_exists(arc4random_uniform HAVE_BSD_ARC4RANDOM_UNIFORM) set(HAVE_ARC4RANDOM_UNIFORM ${HAVE_BSD_ARC4RANDOM_UNIFORM}) endif () endif () mark_as_advanced(BSD_LIBRARY) # If we're not stub only, we need libunbound. if (NOT ENABLE_STUB_ONLY) find_package(Libunbound "1.5.9" REQUIRED) set(HAVE_LIBUNBOUND 1) list(APPEND getdns_system_libs Libunbound::Libunbound) set(CMAKE_REQUIRED_INCLUDES ${LIBUNBOUND_INCLUDE_DIR}) set(CMAKE_REQUIRED_LIBRARIES ${LIBUNBOUND_LIBRARIES}) check_include_file(unbound-event.h HAVE_UNBOUND_EVENT_H) check_symbol_exists(ub_ctx_create_ub_event "unbound-event.h" HAVE_UNBOUND_EVENT_API) check_symbol_exists(ub_ctx_set_stub "unbound-event.h" HAVE_UB_CTX_SET_STUB) endif () # Event loop extension set(DEFAULT_EVENTLOOP "select_eventloop") if (ENABLE_POLL_EVENTLOOP) if (HAVE_SYS_POLL_H) set(TEST_CFLAG "-DHAVE_SYS_POLL_H=1") endif () try_compile(USE_POLL_DEFAULT_EVENTLOOP ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tests/test_poll.c COMPILE_DEFINITIONS "${TEST_CFLAG}" ) if (USE_POLL_DEFAULT_EVENTLOOP) set(DEFAULT_EVENTLOOP "poll_eventloop") endif () endif () # Custom checks set(STRPTIME_TEST_SOURCE "\n #define _XOPEN_SOURCE 600\n #include \n int main(void) { struct tm tm; char *res;\n res = strptime(\"2010-07-15T00:00:00+00:00\", \"%t%Y%t-%t%m%t-%t%d%tT%t%H%t:%t%M%t:%t%S%t\", &tm);\n if (!res) return 2;\n res = strptime(\"20070207111842\", \"%Y%m%d%H%M%S\", &tm);\n if (!res) return 1; return 0; }") if (HAVE_STRPTIME) check_c_source_runs("${STRPTIME_TEST_SOURCE}" STRPTIME_WORKS) endif () try_compile(HAVE___FUNC__ ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tests/test___func__.c ) # TCP Fast Open. if (NOT ENABLE_TCP_FAST_OPEN) message(WARNING "TCP Fast Open disabled.") else () if (APPLE AND HAVE_SYS_SOCKET_H) check_symbol_exists(CONNECT_RESUME_ON_READ_WRITE "sys/socket.h" USE_OSX_TCP_FASTOPEN) if (NOT USE_OSX_TCP_FASTOPEN) message(WARNING "TCP Fast Open not available, continuing without.") endif () else () check_include_file(netinet/tcp.h HAVE_NETINET_TCP_H) check_symbol_exists(TCP_FASTOPEN "sys/socket.h;netinet/tcp.h" HAVE_DECL_TCP_FASTOPEN) check_symbol_exists(TCP_FASTOPEN_CONNECT "sys/socket.h;netinet/tcp.h" HAVE_DECL_TCP_FASTOPEN_CONNECT) check_symbol_exists(MSG_FASTOPEN "sys/socket.h;netinet/tcp.h" HAVE_DECL_MSG_FASTOPEN) if (NOT HAVE_DECL_TCP_FASTOPEN) message(WARNING "TCP Fast Open not available, continuing without.") endif () endif () endif () # Main library add_library(getdns_objects OBJECT src/anchor.c src/const-info.c src/convert.c src/context.c src/dict.c src/dnssec.c src/general.c src/list.c src/request-internal.c src/mdns.c src/platform.c src/pubkey-pinning.c src/rr-dict.c src/rr-iter.c src/server.c src/stub.c src/sync.c src/ub_loop.c src/util-internal.c src/extension/${DEFAULT_EVENTLOOP}.c src/gldns/keyraw.c src/gldns/gbuffer.c src/gldns/wire2str.c src/gldns/parse.c src/gldns/parseutil.c src/gldns/rrdef.c src/gldns/str2wire.c src/util/rbtree.c src/util/lruhash.c src/util/lookup3.c src/util/locks.c src/jsmn/jsmn.c src/yxml/yxml.c src/tls/val_secalgo.c src/tls/anchor-internal.c src/${tlsdir}/tls.c src/${tlsdir}/pubkey-pinning-internal.c src/${tlsdir}/keyraw-internal.c ${CMAKE_CURRENT_BINARY_DIR}/version.c ) if (NOT HAVE_GETTIMEOFDAY) target_sources(getdns_objects PRIVATE src/compat/gettimeofday.c) endif () if (NOT HAVE_DECL_INET_PTON) target_sources(getdns_objects PRIVATE src/compat/inet_pton.c) endif () if (NOT HAVE_DECL_INET_NTOP) target_sources(getdns_objects PRIVATE src/compat/inet_ntop.c) endif () if (NOT HAVE_DECL_MKSTEMP) target_sources(getdns_objects PRIVATE src/compat/mkstemp.c) endif () if (NOT HAVE_DECL_STRLCPY) target_sources(getdns_objects PRIVATE src/compat/strlcpy.c) endif () if (NOT HAVE_DECL_ARC4RANDOM) target_sources(getdns_objects PRIVATE src/compat/arc4random.c src/compat/explicit_bzero.c src/compat/arc4_lock.c ) if (NOT HAVE_DECL_GETENTROPY) if (DEFINED GETDNS_ON_WINDOWS) target_sources(getdns_objects PRIVATE src/compat/getentropy_win.c) elseif (APPLE) target_sources(getdns_objects PRIVATE src/compat/getentropy_osx.c) elseif (DEFINED LINUX) target_sources(getdns_objects PRIVATE src/compat/getentropy_linux.c) endif () endif () endif () if (NOT HAVE_DECL_ARC4RANDOM_UNIFORM) target_sources(getdns_objects PRIVATE src/compat/arc4random_uniform.c) endif () if (NOT STRPTIME_WORKS) target_sources(getdns_objects PRIVATE src/compat/strptime.c) endif () target_include_directories(getdns_objects PUBLIC src PRIVATE src/util/auxiliary src/${tlsdir} src/tls src/yxml ${CMAKE_CURRENT_BINARY_DIR} # Note - CMake 3.5 doesn't like target_link_libraries on objects, # which would be preferred way to add an include dependency. ${OPENSSL_INCLUDE_DIR} ) target_compile_definitions(getdns_objects PRIVATE JSMN_GETDNS YXML_GETDNS) if (NOT HAVE_SSL_DANE_ENABLE) target_sources(getdns_objects PRIVATE src/ssl_dane/danessl.c) target_include_directories(getdns_objects PRIVATE src/ssl_dane) set(USE_DANESSL 1) endif () if (Libidn_FOUND) target_include_directories(getdns_objects PRIVATE ${LIBIDN_INCLUDE_DIR}) endif () if (Libidn2_FOUND) target_include_directories(getdns_objects PRIVATE ${LIBIDN2_INCLUDE_DIR}) endif () if (Libunbound_FOUND) target_include_directories(getdns_objects PRIVATE ${LIBUNBOUND_INCLUDE_DIR}) endif () if (GnuTLS_FOUND) target_include_directories(getdns_objects PRIVATE ${GNUTLS_INCLUDE_DIR}) endif () # Don't compile separate objects for shared and static libraries. # Yes, -fPIC is slightly suboptimal for static libraries, but it looks # to me that it's the behaviour the autoconf build follows. set_property(TARGET getdns_objects PROPERTY POSITION_INDEPENDENT_CODE 1) set_property(TARGET getdns_objects PROPERTY C_STANDARD 11) # Static library version of main library. if (ENABLE_STATIC) add_library(getdns STATIC $) target_include_directories(getdns PUBLIC "$" ${CMAKE_CURRENT_BINARY_DIR} ) target_link_libraries(getdns PUBLIC OpenSSL::SSL OpenSSL::Crypto Threads::Threads ${getdns_system_libs} ) if (Libunbound_FOUND) target_link_libraries(getdns PUBLIC Libunbound::Libunbound) endif () if (Libidn_FOUND) target_link_libraries(getdns PUBLIC Libidn::Libidn) endif () if (Libidn2_FOUND) target_link_libraries(getdns PUBLIC Libidn2::Libidn2) endif () if (GnuTLS_FOUND) target_link_libraries(getdns PUBLIC GnuTLS::GnuTLS GnuTLS::Dane) endif () if (Nettle_FOUND) target_link_libraries(getdns PUBLIC Nettle::Nettle Nettle::Hogweed) endif () set_target_properties(getdns PROPERTIES OUTPUT_NAME getdns${static_lib_suffix}) endif () # Shared library version of main library. if (ENABLE_SHARED) add_library(getdns_shared SHARED $) target_include_directories(getdns_shared PUBLIC "$" ${CMAKE_CURRENT_BINARY_DIR} ) target_link_libraries(getdns_shared PUBLIC OpenSSL::SSL OpenSSL::Crypto Threads::Threads ${getdns_system_libs} ) if (Libunbound_FOUND) target_link_libraries(getdns_shared PUBLIC Libunbound::Libunbound) endif () if (Libidn_FOUND) target_link_libraries(getdns_shared PUBLIC Libidn::Libidn) endif () if (Libidn2_FOUND) target_link_libraries(getdns_shared PUBLIC Libidn2::Libidn2) endif () if (GnuTLS_FOUND) target_link_libraries(getdns_shared PUBLIC GnuTLS::GnuTLS GnuTLS::Dane) endif () if (Nettle_FOUND) target_link_libraries(getdns_shared PUBLIC Nettle::Nettle Nettle::Hogweed) endif () set_target_properties(getdns_shared PROPERTIES OUTPUT_NAME getdns) target_shared_library_version(getdns_shared ${GETDNS_VERSION_CURRENT} ${GETDNS_VERSION_REVISION} ${GETDNS_VERSION_AGE}) # Generate platform-specific link file with the export symbols. file(STRINGS src/libgetdns.symbols symbols) target_shared_library_exports(getdns_shared getdns "${symbols}") # If we're not building a static library, use this wherever we use # the static library in tool and test builds. if (NOT ENABLE_STATIC) add_library(getdns ALIAS getdns_shared) endif () endif () # libev extension. if (USE_LIBEV) find_package(Libev) if (Libev_FOUND) # Copy module header to getdns include dir. file(COPY src/getdns/getdns_ext_libev.h DESTINATION getdns) add_library(ev_objects OBJECT src/extension/libev.c) target_include_directories(ev_objects PRIVATE src ${CMAKE_CURRENT_BINARY_DIR} ${LIBEV_INCLUDE_DIR} ) set_property(TARGET ev_objects PROPERTY POSITION_INDEPENDENT_CODE 1) set_property(TARGET ev_objects PROPERTY C_STANDARD 11) if (ENABLE_STATIC) add_library(getdns_ex_ev STATIC $) target_include_directories(getdns_ex_ev PRIVATE Libev::Libev) target_link_libraries(getdns_ex_ev PUBLIC getdns Libev::Libev) if (Libunbound_FOUND) target_link_libraries(getdns_ex_ev PUBLIC Libunbound::Libunbound) endif () set_target_properties(getdns_ex_ev PROPERTIES OUTPUT_NAME getdns_ex_ev${static_lib_suffix}) endif () if (ENABLE_SHARED) add_library(getdns_ex_ev_shared SHARED $) target_include_directories(getdns_ex_ev_shared PRIVATE Libev::Libev) target_link_libraries(getdns_ex_ev_shared PUBLIC getdns_shared Libev::Libev) if (Libunbound_FOUND) target_link_libraries(getdns_ex_ev_shared PUBLIC Libunbound::Libunbound) endif () set_target_properties(getdns_ex_ev_shared PROPERTIES OUTPUT_NAME getdns_ex_ev) target_shared_library_version(getdns_ex_ev_shared ${GETDNS_VERSION_CURRENT} ${GETDNS_VERSION_REVISION} ${GETDNS_VERSION_AGE}) file(STRINGS src/extension/libev.symbols symbols) target_shared_library_exports(getdns_ex_ev_shared getdns_ex_ev "${symbols}") if (NOT ENABLE_STATIC) add_library(getdns_ex_ev ALIAS getdns_ex_ev_shared) endif () endif () else () message(WARNING "Libev support library build requested, but libev not found. Disabled.") unset(USE_LIBEV) endif () endif () # libevent2 extension. if (USE_LIBEVENT2) find_package(Libevent2) if (Libevent2_FOUND) # Given libevent2, set defines required by source. set(HAVE_EVENT2_EVENT_H 1) set(HAVE_EVENT_BASE_FREE 1) set(HAVE_EVENT_BASE_NEW 1) # Copy module header to getdns include dir. file(COPY src/getdns/getdns_ext_libevent.h DESTINATION getdns) add_library(event2_objects OBJECT src/extension/libevent.c) target_include_directories(event2_objects PRIVATE src ${CMAKE_CURRENT_BINARY_DIR} ${LIBEVENT2_INCLUDE_DIR} ) set_property(TARGET event2_objects PROPERTY POSITION_INDEPENDENT_CODE 1) set_property(TARGET event2_objects PROPERTY C_STANDARD 11) if (ENABLE_STATIC) add_library(getdns_ex_event STATIC $) target_include_directories(getdns_ex_event PRIVATE Libevent2::Libevent_code) target_link_libraries(getdns_ex_event PUBLIC getdns Libevent2::Libevent_core) if (Libunbound_FOUND) target_link_libraries(getdns_ex_event PUBLIC Libunbound::Libunbound) endif () set_target_properties(getdns_ex_event PROPERTIES OUTPUT_NAME getdns_ex_event${static_lib_suffix}) endif () if (ENABLE_SHARED) add_library(getdns_ex_event_shared SHARED $) target_include_directories(getdns_ex_event_shared PRIVATE Libevent2::Libevent_code) target_link_libraries(getdns_ex_event_shared PUBLIC getdns_shared Libevent2::Libevent_core) if (Libunbound_FOUND) target_link_libraries(getdns_ex_event_shared PUBLIC Libunbound::Libunbound) endif () set_target_properties(getdns_ex_event_shared PROPERTIES OUTPUT_NAME getdns_ex_event) target_shared_library_version(getdns_ex_event_shared ${GETDNS_VERSION_CURRENT} ${GETDNS_VERSION_REVISION} ${GETDNS_VERSION_AGE}) file(STRINGS src/extension/libevent.symbols symbols) target_shared_library_exports(getdns_ex_event_shared getdns_ex_event "${symbols}") if (NOT ENABLE_STATIC) add_library(getdns_ex_event ALIAS getdns_ex_event_shared) endif () endif () else () message(WARNING "Libevent2 support library build requested, but libevent2 not found. Disabled.") unset(USE_LIBEVENT2) endif () endif () # libuv extension. if (USE_LIBUV) find_package(Libuv) if (Libuv_FOUND) # Check for new-style callbacks. try_compile(HAVE_NEW_UV_TIMER_CB ${CMAKE_CURRENT_BINARY_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/cmake/tests/test_uv_cb.c ) # Copy module header to getdns include dir. file(COPY src/getdns/getdns_ext_libuv.h DESTINATION getdns) add_library(uv_objects OBJECT src/extension/libuv.c) target_include_directories(uv_objects PRIVATE src ${CMAKE_CURRENT_BINARY_DIR} ${LIBUV_INCLUDE_DIR} ) set_property(TARGET uv_objects PROPERTY POSITION_INDEPENDENT_CODE 1) set_property(TARGET uv_objects PROPERTY C_STANDARD 11) if (ENABLE_STATIC) add_library(getdns_ex_uv STATIC $) target_include_directories(getdns_ex_uv PRIVATE Libuv::Libuv) target_link_libraries(getdns_ex_uv PUBLIC getdns Libuv::Libuv) if (Libunbound_FOUND) target_link_libraries(getdns_ex_uv PUBLIC Libunbound::Libunbound) endif () set_target_properties(getdns_ex_uv PROPERTIES OUTPUT_NAME getdns_ex_uv${static_lib_suffix}) endif () if (ENABLE_SHARED) add_library(getdns_ex_uv_shared SHARED $) target_include_directories(getdns_ex_uv_shared PRIVATE Libuv::Libuv) target_link_libraries(getdns_ex_uv_shared PUBLIC getdns_shared Libuv::Libuv) if (Libunbound_FOUND) target_link_libraries(getdns_ex_uv_shared PUBLIC Libunbound::Libunbound) endif () set_target_properties(getdns_ex_uv_shared PROPERTIES OUTPUT_NAME getdns_ex_uv) target_shared_library_version(getdns_ex_uv_shared ${GETDNS_VERSION_CURRENT} ${GETDNS_VERSION_REVISION} ${GETDNS_VERSION_AGE}) file(STRINGS src/extension/libuv.symbols symbols) target_shared_library_exports(getdns_ex_uv_shared getdns_ex_uv "${symbols}") if (NOT ENABLE_STATIC) add_library(getdns_ex_uv ALIAS getdns_ex_uv_shared) endif () endif () else () message(WARNING "Libuv support library build requested, but libuv not found. Disabled.") unset(USE_LIBUV) endif () endif () # The tools. if (BUILD_GETDNS_QUERY) add_executable(getdns_query src/tools/getdns_query.c) if (NOT HAVE_GETTIMEOFDAY) target_sources(getdns_query PRIVATE src/compat/gettimeofday.c) endif () target_link_libraries(getdns_query PRIVATE getdns) if (Libunbound_FOUND) target_link_libraries(getdns_query PUBLIC Libunbound::Libunbound) endif () set_property(TARGET getdns_query PROPERTY C_STANDARD 11) endif () if (BUILD_GETDNS_SERVER_MON) add_executable(getdns_server_mon src/tools/getdns_server_mon.c) target_link_libraries(getdns_server_mon PUBLIC OpenSSL::SSL OpenSSL::Crypto PRIVATE getdns ) if (Libunbound_FOUND) target_link_libraries(getdns_server_mon PUBLIC Libunbound::Libunbound) endif () set_property(TARGET getdns_server_mon PROPERTY C_STANDARD 11) endif () if (BUILD_TESTING) if (WIN32) message(WARNING "Test programs require libcheck and so do not build on Windows, skipping.") else () find_package(Check "0.9.6" REQUIRED) set(GETDNS_TEST_SOURCE_FILES src/test/check_getdns_common.c src/test/check_getdns_context_set_timeout.c src/test/check_getdns_transport.c src/test/check_getdns_selectloop.c src/test/check_getdns.c) set(GETDNS_TEST_LINK_LIBS getdns Check::Check Threads::Threads) add_executable(check_getdns ${GETDNS_TEST_SOURCE_FILES}) target_link_libraries(check_getdns PRIVATE ${GETDNS_TEST_LINK_LIBS}) add_test(NAME test_noeventloop COMMAND check_getdns) set_property(TEST test_noeventloop PROPERTY ENVIRONMENT "GETDNS_TEST_PORT=43210;CK_TIMEOUT_MULTIPLIER=2;CK_LOG_FILE_NAME=check_getdns.log" ) if (USE_LIBEVENT2) add_executable(check_getdns_event ${GETDNS_TEST_SOURCE_FILES}) target_link_libraries(check_getdns_event PRIVATE ${GETDNS_TEST_LINK_LIBS} getdns_ex_event) add_test(NAME test_libevent COMMAND check_getdns_event) set_property(TEST test_libevent PROPERTY ENVIRONMENT "GETDNS_TEST_PORT=44321;CK_TIMEOUT_MULTIPLIER=2;CK_LOG_FILE_NAME=check_getdns_event.log" ) endif() if (USE_LIBEV) add_executable(check_getdns_ev ${GETDNS_TEST_SOURCE_FILES}) target_link_libraries(check_getdns_ev PRIVATE ${GETDNS_TEST_LINK_LIBS} getdns_ex_ev) add_test(NAME test_libev COMMAND check_getdns_ev) set_property(TEST test_libev PROPERTY ENVIRONMENT "GETDNS_TEST_PORT=45321;CK_TIMEOUT_MULTIPLIER=2;CK_LOG_FILE_NAME=check_getdns_ev.log" ) endif() if (USE_LIBUV) add_executable(check_getdns_uv ${GETDNS_TEST_SOURCE_FILES}) target_link_libraries(check_getdns_uv PRIVATE ${GETDNS_TEST_LINK_LIBS} getdns_ex_uv) add_test(NAME test_libuv COMMAND check_getdns_uv) set_property(TEST test_libuv PROPERTY ENVIRONMENT "GETDNS_TEST_PORT=46321;CK_TIMEOUT_MULTIPLIER=2;CK_LOG_FILE_NAME=check_getdns_uv.log" ) endif() add_executable(tests_dict src/test/tests_dict.c src/test/testmessages.c ) target_link_libraries(tests_dict PRIVATE getdns Check::Check) add_executable(tests_list src/test/tests_list.c src/test/testmessages.c ) target_link_libraries(tests_list PRIVATE getdns Check::Check) add_executable(tests_namespaces src/test/tests_namespaces.c) target_link_libraries(tests_namespaces PRIVATE getdns Check::Check) add_executable(tests_stub_async src/test/tests_stub_async.c src/test/testmessages.c ) target_link_libraries(tests_stub_async PRIVATE getdns Check::Check) add_executable(tests_stub_sync src/test/tests_stub_sync.c) target_link_libraries(tests_stub_sync PRIVATE getdns Check::Check) endif() endif () # Substitutions in files. configure_file(cmake/include/cmakeconfig.h.in config.h) configure_file(src/getdns/getdns.h.in getdns/getdns.h) configure_file(src/getdns/getdns_extra.h.in getdns/getdns_extra.h) configure_file(src/version.c.in version.c) set(version ${PACKAGE_VERSION}) set(date ${API_VERSION}) file(GLOB mans doc/*.3.in) file(MAKE_DIRECTORY man3) foreach (man ${mans}) get_filename_component(out ${man} NAME_WE) configure_file(${man} man3/${out}.3 @ONLY) # Look through the page and make copies of the page for all APIs # defined in that page. Defined means listed in a line ".B " # between lines ".SH NAME" and ".SH LIBRARY". Ignore terminating "," # or spaces in .B line. file(STRINGS ${man} manpage REGEX "^\\.(SH +NAME|SH +LIBRARY|B )") set(in_list 0) foreach (line ${manpage}) if ("${line}" MATCHES "^\\.SH +NAME") set(in_list 1) elseif ("${line}" MATCHES "^\\.SH +LIBRARY") set(in_list 0) elseif (${in_list}) string(REGEX REPLACE ".B +([^ ,]+).*" "\\1" alt "${line}") configure_file(${man} man3/${alt}.3 @ONLY) endif () endforeach() endforeach() set(prefix ${CMAKE_INSTALL_PREFIX}) configure_file(getdns.pc.in getdns.pc @ONLY) # Installing. if (ENABLE_STATIC) install(TARGETS getdns LIBRARY DESTINATION lib ARCHIVE DESTINATION lib) if (USE_LIBEV) install(TARGETS getdns_ex_ev LIBRARY DESTINATION lib ARCHIVE DESTINATION lib) endif () if (USE_LIBEVENT2) install(TARGETS getdns_ex_event LIBRARY DESTINATION lib ARCHIVE DESTINATION lib) endif () if (USE_LIBUV) install(TARGETS getdns_ex_uv LIBRARY DESTINATION lib ARCHIVE DESTINATION lib) endif () endif () if (ENABLE_SHARED) install(TARGETS getdns_shared LIBRARY DESTINATION lib ARCHIVE DESTINATION lib) if (USE_LIBEV) install(TARGETS getdns_ex_ev_shared LIBRARY DESTINATION lib ARCHIVE DESTINATION lib) endif () if (USE_LIBEVENT2) install(TARGETS getdns_ex_event_shared LIBRARY DESTINATION lib ARCHIVE DESTINATION lib) endif () if (USE_LIBUV) install(TARGETS getdns_ex_uv_shared LIBRARY DESTINATION lib ARCHIVE DESTINATION lib) endif () endif () if (BUILD_GETDNS_QUERY) install(TARGETS getdns_query RUNTIME DESTINATION bin) endif () if (BUILD_GETDNS_SERVER_MON) install(TARGETS getdns_server_mon RUNTIME DESTINATION bin) endif () install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/getdns DESTINATION include) install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/man3 DESTINATION share/man) set(docdir share/doc/getdns) install(FILES AUTHORS ChangeLog COPYING LICENSE NEWS README.md DESTINATION ${docdir}) install(FILES spec/index.html DESTINATION ${docdir}/spec) install(FILES ${CMAKE_CURRENT_BINARY_DIR}/getdns.pc DESTINATION lib/pkgconfig) install(CODE "message(\"\ ***\n\ *** !!! IMPORTANT !!!!\n\ ***\n\ *** From release 1.2.0, getdns comes with built-in DNSSEC\n\ *** trust anchor management. External trust anchor management,\n\ *** for example with unbound-anchor, is no longer necessary\n\ *** and no longer recommended.\n\ ***\n\ *** Previously installed trust anchors, in the default location -\n\ ***\n\ *** /etc/unbound/getdns-root.key\n\ ***\n\ *** - will be preferred and used for DNSSEC validation, however\n\ *** getdns will fallback to trust-anchors obtained via built-in\n\ *** trust anchor management when the anchors from the default\n\ *** location fail to validate the root DNSKEY rrset.\n\ ***\n\ *** To prevent expired DNSSEC trust anchors to be used for\n\ *** validation, we strongly recommend removing the trust anchors\n\ *** on the default location when there is no active external\n\ *** trust anchor management keeping it up-to-date.\n\ ***\")") if (BUILD_STUBBY) add_subdirectory(stubby) endif () if (BUILD_EXAMPLES) add_executable(example-all-functions spec/example/example-all-functions.c) target_include_directories(example-all-functions PRIVATE spec/example) target_link_libraries(example-all-functions PRIVATE getdns) set_property(TARGET example-all-functions PROPERTY C_STANDARD 11) add_executable(example-synchronous spec/example/example-synchronous.c) target_include_directories(example-synchronous PRIVATE spec/example) target_link_libraries(example-synchronous PRIVATE getdns) set_property(TARGET example-synchronous PROPERTY C_STANDARD 11) if (USE_LIBEVENT2) add_executable(example-simple-answers spec/example/example-simple-answers.c) target_include_directories(example-simple-answers PRIVATE spec/example) target_link_libraries(example-simple-answers PRIVATE getdns getdns_ex_event) set_property(TARGET example-simple-answers PROPERTY C_STANDARD 11) add_executable(example-tree spec/example/example-tree.c) target_include_directories(example-tree PRIVATE spec/example) target_link_libraries(example-tree PRIVATE getdns getdns_ex_event) set_property(TARGET example-tree PROPERTY C_STANDARD 11) add_executable(example-reverse spec/example/example-reverse.c) target_include_directories(example-reverse PRIVATE spec/example) target_link_libraries(example-reverse PRIVATE getdns getdns_ex_event) set_property(TARGET example-reverse PROPERTY C_STANDARD 11) else () message(WARNING "\ Three examples from the specification need libevent. \ libevent was not found or usable at compile time. \ To compile and run all examples from the spec, make sure \ libevent is available and usable during configuration.") endif () endif () if (BUILD_DOXYGEN) find_package(Doxygen REQUIRED) set(srcdir ${CMAKE_CURRENT_SOURCE_DIR}/src) configure_file(src/Doxyfile.in Doxyfile @ONLY) add_custom_command(OUTPUT doc/html/index.html COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile MAIN_DEPENDENCY Doxyfile COMMENT "Generating Doxygen docs.") add_custom_target(doc ALL DEPENDS doc/html/index.html) endif () getdns-1.6.0/COPYING000077700000000000000000000000001362622307100150372LICENSEustar00rootroot00000000000000getdns-1.6.0/ChangeLog000066400000000000000000001030121362622307100145530ustar00rootroot00000000000000* 2020-02-28: Version 1.6.0 * Issues #457, #458, #461: New symbols with libnettle >= 3.4. Thanks hanvinke & kometchtech for testing & reporting. * Issue #432: answer_ipv4_address and answer_ipv6_address in reply and response dicts. * Issue #430: Record and guard UDP max payload size with servers. * Issue #407: Run only offline-tests option with: src/test/tpkg/run-offline-only.sh (only with git checkouts). * Issue #175: Include the packet the stub resolver sent to the upstream the call_reporting dict. Thanks Tom Pusateri * Issue #169: Build eventloop support libraries if event libraries are available. Thanks Tom Pusateri * 2019-12-20: Version 1.6.0-beta.1 * Migration of build system to cmake. Build now works on Ubuntu, Windows 10 and macOS. Some notes on minor differences in the new cmake build: * OpenSSL 1.0.2 or higher is now required * libunbound 1.5.9 is now required * Only libidn2 2.0.0 and later is supported (not libidn) * Windows uses ENABLE_STUB_ONLY=ON as the default * Unit and regression tests work on Linux/macOS (but not Windows yet) * 2019-04-03: Version 1.5.2 * PR #424: Two small trust anchor fetcher fixes Thanks Maciej S. Szmigiero * Issue #422: Enable server side and update client side TCP Fast Open implementation. Thanks Craig Andrews * Issue #423: Fix insecure delegation detection while scheduling. Thanks Charles Milette * Issue #419: Escape backslashed when printing in JSON format. Thanks boB Rudis * Use GnuTLS instead of OpenSSL for TLS with the --with-gnutls option to configure. libcrypto (from OpenSSL) still needed for Zero configuration DNSSEC. * DOA rr-type * AMTRELAY rr-type * 2019-01-11: Version 1.5.1 * Introduce proof of concept GnuTLS implementation. Incomplete support for Trust Anchor validation. Requires GnuTLS DANE library. Currently untested with GnuTLS prior to 3.5.19, so configure demands a minumum version of 3.5.0. * Be consistent and always fail connection setup if setting ciphers/curves/ TLS version/cipher suites fails. * Refactor OpenSSL usage into modules under src/openssl. Drop support for LibreSSL and versions of OpenSSL prior to 1.0.2. * PR #414: remove TLS13 ciphers from cipher_list, but only when SSL_CTX_set_ciphersuites is available. Thanks Bruno Pagani * Issue #415: Filter out #defines etc. when creating symbols file. Thanks Zero King * 2018-12-21: Version 1.5.0 * RFE getdnsapi/stubby#121 log re-instantiating TLS upstreams (because they reached tls_backoff_time) at log level 4 (WARNING) * GETDNS_RESPSTATUS_NO_NAME for NODATA answers too * ZONEMD rr-type * getdns_query queries for addresses when a query name without a type is given. * RFE #408: Fetching of trust anchors will be retried after failure, after a certain backoff time. The time can be configured with getdns_context_set_trust_anchors_backoff_time(). * RFE #408: A "dnssec" extension that requires DNSSEC verification. When this extension is set, Indeterminate DNSSEC status will not be returned. * Issue #410: Unspecified ownership of get_api_information() * Fix for DNSSEC bug in finding most specific key when trust anchor proves non-existance of one of the labels along the authentication chain other than the non- existance of a DS record on a zonecut. * Enhancement getdnsapi/stubby#56 & getdnsapi/stubby#130: Configurable minimum and maximum TLS versions with getdns_context_set_tls_min_version() and getdns_context_set_tls_max_version() functions and tls_min_version and tls_max_version configuration parameters for upstreams. * Configurable TLS1.3 ciphersuites with the getdns_context_set_tls_ciphersuites() function and tls_ciphersuites config parameter for upstreams. * Bugfix in upstream string configurations: tls_cipher_list and tls_curve_list * Bugfix finding signer for validating NSEC and NSEC3s, which caused trouble with the partly tracing DNSSEC from the root up, introduced in 1.4.2. Thanks Philip Homburg * 2018-05-11: Version 1.4.2 * Bugfix getdnsapi/stubby#87: Detect and ignore duplicate certs in the Windows root CA store. * PR #397: No TCP sendto without TCP_FASTOPEN Thanks Emery Hemingway * Bugfix getdnsapi/stubby#106: Core dump when printing certain configuration. Thanks Han Vinke * Bugfix getdnsapi/stubby#99: Partly trace DNSSEC from the root up (for tld and sld), to find insecure delegations quicker. Thanks UniverseXXX * Bugfix: Allow NSEC spans starting from (unexpanded) wildcards Bug was introduced when dealing with CVE-2017-15105 * Bugfix getdnsapi/stubby#46: Don't assume trailing zero with string bindata's. Thanks Lonnie Abelbeck * Bugfix #394: Update src/compat/getentropy_linux.c in order to handle ENOSYS (not implemented) fallback. Thanks Brent Blood * Bugfix #395: Clarify that libidn2 dependency is for version 2.0.0 or higher. Thanks mire3212 * 2018-03-12: Version 1.4.1 * Bugfix #388: Prevent fallback to an earlier tries upstream within a single query. Thanks Robert Groenenberg * PR #387: Compile with OpenSSL with deprecated APIs disabled. Thanks Rosen Penev * PR #386: UDP failover improvements: - When all UDP upstreams fail, retry them (more or less) equally - Limit maximum UDP backoff (default to 1000) This is configurable with the --with-max-udp-backoff configure option. Thanks Robert Groenenberg * Bugfix: Find zonecut with DS queries (instead of SOA queries). Thanks Elmer Lastdrager * Bugfix #385: Verifying insecure NODATA answers (broken since 1.2.1). Thanks hanvinke * PR #384: Fix minor spelling and formatting. Thanks dkg. * Bugfix #382: Parallel install of getdns_query and getdns_server_mon * 2018-02-21: Version 1.4.0 * .so revision bump to please fedora packaging system. Thanks Paul Wouters * Specify the supported curves with getdns_context_set_tls_curves_list() An upstream specific list of supported curves may also be given with the tls_curves_list setting in the upstream dict with getdns_context_set_upstream_recursive_servers() * New tool getdns_server_mon for checking upstream recursive resolver's capabilities. * Improved handling of opportunistic back-off. If other transports are working, don’t forcibly promote failed upstreams just wait for the re-try timer. * Hostname authentication with libressl Thanks Norbert Copones * Security bugfix in response to CVE-2017-15105. Although getdns was not vulnerable for this specific issue, as a precaution code has been adapted so that signatures of DNSKEYs, DSs, NSECs and NSEC3s can not be wildcard expansions when used with DNSSEC proofs. Only direct queries for those types are allowed to be wildcard expansions. * Bugfix PR#379: Miscelleneous double free or corruption, and corrupted memory double linked list detected issue, with serving functionality. Thanks maddie and Bruno Pagani * Security Bugfix PR#293: Check sha256 pinset's with OpenSSL native DANE functions for OpenSSL >= 1.1.0 with Viktor Dukhovni's danessl library for OpenSSL >= 1.0.0 don't allow for authentication exceptions (like self-signed certificates) otherwise. Thanks Viktor Dukhovni * libidn2 support. Thanks Paul Wouters * 2017-12-21: Version 1.3.0 * Bugfix #300: Detect dnsmasq and skip unit test that fails with it. Thanks Tim Rühsen and Konomi Kitten * Specify default available cipher suites for authenticated TLS upstreams with getdns_context_set_tls_ciphers_list() An upstream specific available cipher suite may also be given with the tls_cipher_list setting in the upstream dict with getdns_context_set_upstream_recursive_servers() * PR #366: Add support for TLS 1.3 and Chacha20-Poly1305 Thanks Pascal Ernster * Bugfix #356: Do Zero configuration DNSSEC meta queries over on the context configured upstreams. Thanks Andreas Schulze * Report default extension settings with getdns_context_get_api_information() * Specify locations at which CA certificates for verification purposes are located: getdns_context_set_tls_ca_path() getdns_context_set_tls_ca_file() * getdns_context_set_resolvconf() function to initialize a context upstreams and suffices with a resolv.conf file. getdns_context_get_resolvconf() to get the file used to initialize the context's upstreams and suffixes. getdns_context_set_hosts() function to initialize a context's LOCALNAMES namespace. getdns_context_get_hosts() function to get the file used to initialize the context's LOCALNAMES namespace. * get which version of OpenSSL was used at build time and at run time when available with getdns_context_get_api_information() * GETDNS_RETURN_IO_ERROR return error code * Bugfix #359: edns_client_subnet_private should set family Thanks Daniel Areiza & Andreas Schulze * Bugfix getdnsapi/stubby#34: Segfault issue with native DNSSEC validation. Thanks Bruno Pagani * 2017-11-11: Version 1.2.1 * Handle more I/O error cases. Also, when an I/O error does occur, never stop listening (with servers), and never exit (when running the built-in event loop). * Bugfix: Tolerate unsigned and unused RRsets in the authority section. Fixes DNSSEC with BIND upstream. * Bugfix: DNSSEC validation without support records * Bugfix: Validation of full recursive DNSKEY lookups * Bugfix: Retry to validate full recursion BOGUS replies with zero configuration DNSSEC only when DNSSEC was actually requested * Bugfix #348: Fix a linking issue in stubby when libbsd is present Thanks Remi Gacogne * More robust scheduling; Eliminating a segfault with long running applications. * Miscellaneous Windows portability fixes from Jim Hague. * Fix Makefile dependencies for parallel install. Thanks ilovezfs * 2017-09-29: Version 1.2.0 * Bugfix of rc1: authentication of first query with TLS Thanks Travis Burtrum * A function to set the location for library specific data, like trust-anchors: getdns_context_set_appdata(). * Zero configuration DNSSEC - build upon the scheme described in RFC7958. The URL from which to fetch the trust anchor, the verification CA and email can be set with the new getdns_context_set_trust_anchor_url(), getdns_context_set_trust_anchor_verify_CA() and getdns_context_set_trust_anchor_verify_email() functions. The default values are to fetch from IANA and to validate with the ICANN CA. * Update of Stubby with yaml configuration file and logging from a certain severity support. * Fix tpkg exit status on test failure. Thanks Jim Hague. * Refined logging levels for upstream statistics * Reuse (best behaving) backed-off TLS upstreams when non are usable. * Let TLS upstreams back-off a incremental amount of time. Back-off time starts with 1 second and is doubled each failure, but will not exceed the time given by getdns_context_set_tls_backoff_time() * Make TLS upstream management more resilient to temporary outages (like laptop sleeps) * 2017-09-04: Version 1.1.3 * Small bugfixes that came out of static analysis * No annotations with the output of getdns_query anymore, unless -V option is given to increase verbosity Thanks Ollivier Robert * getdns_query will now exit with failure status if replies are BOGUS * Bugfix: dnssec_return_validation_chain now also works when fallback to full recursion was needed with dnssec_roadblock_avoidance * More clear build instructions from Paul Hoffman. Thanks. * Bugfix #320.1: Eliminate multiple closing of file descriptors Thanks Neil Cook * Bugfix #320.2: Array bounds bug in upstream_select Thanks Neil Cook * Bugfix #318: getdnsapi/getdns/README.md links to nonexistent wiki pages. Thanks James Raftery * Bugfix #322: MacOS 10.10 (Yosemite) provides TCP fastopen interface but does not have it implemented. Thanks Joel Purra * Compile without Stubby by default. Stubby now has a git repository of its own. The new Stubby repository is added as a submodule. Stubby will still be build alongside getdns with the --with-stubby configure option. * 2017-07-03: Version 1.1.2 * Bugfix for parallel make install * Bugfix to trigger event callbacks on socket errors * A getdns_context_set_logfunc() function with which one may register a callback log function for certain library subsystems at certain levels. Currently this can only be used for upstream stastistics subsystem. * 2017-06-15: Version 1.1.1 * Bugfix #306 hanging/segfaulting on certain (IPv6) upstream failures * Spelling fix s/receive/receive. Thanks Andreas Schulze. * Added stubby-setdns-macos.sh script to support Homebrew formula * Include stubby.conf in the districution tarball * Bugfix #286 reschedule reused listening addresses * Bugfix #166 Allow parallel builds and unit-tests * NSAP-PTR, EID and NIMLOC, TALINK, AVC support * Bugfix of TA RR type * OPENPGPKEY and SMIMEA support * Bugfix TAG rdata type presentation format for CAA RR type * Bugfix Zero sized gateways with IPSECKEY gateway_type 0 * Guidance for integration with systemd * Also check for memory leaks with advances server capabilities. * Bugfix convert IP string to IP dict with getdns_str2dict() directly. * 2017-04-13: Version 1.1.0 * bugfix: Check size of tls_auth_name. * Improvements that came from Visual Studio static analysis * Fix to compile with libressl. Thanks phicoh. * Spelling fixes. Thanks Andreas Schulze. * bugfix: Reschedule request timeout when getting the DNSSEC chain. * getdns_context_unset_edns_maximum_udp_payload_size() to reset to default IPv4/IPv6 dependent edns max udp payload size. * Implement sensible default edns0 padding policy. Thanks DKG. * Keep connections open with sync requests too. * Fix of event loops so they do not give up with naked timers with windows. Thanks Christian Huitema. * Include peer certificate with DNS-over-TLS in combination with the return_call_reporting extension. * More fine grained control over TLS upstream retry and back off behaviour with getdns_context_set_tls_backoff_time() and getdns_context_set_tls_connection_retries(). * New round robin over the available upstreams feaure. Enable with getdns_context_set_round_robin_upstreams() * Bugfix: Queue requests when no sockets available for outgoing queries. * Obey the outstanding query limit with STUB resolution mode too. * Updated stubby config file * Draft MDNS client implementation by Christian Huitema. Enable with --enable-draft-mdns-support to configure * bugfix: Let synchronous queries use fds > MAX_FDSETSIZE; By moving default eventloop from select to poll Thanks Neil Cook * bugfix: authentication failure for self signed cert + only pinset * bugfix: issue with session re-use making authentication appear to fail * 2017-01-13: Version 1.0.0 * edns0_cookies extension enabled by default (per RFC7873) * dnssec_roadblock_avoidance enabled by default (per RFC8027) * bugfix: DSA support with OpenSSL 1.1.0 * Initialize OpenSSL just once in a thread safe way * Thread safety with arc4random function * Improvements that came from Visual Studio static analysis Thanks Christian Huitema * Conventional RFC3986 IPv6 [address]:port parsing from getdns_query * bugfix: OpenSSL 1.1.0 style crypto locking Thanks volkommenheit * configure tells *which* dependency is missing * bugfix: Exclude terminating '\0' from bindata's returned by getdns_get_suffix(). Thanks Jim Hague * Better README.md. Thanks Andrew Sullivan * 2016-10-19: Version 1.1.0-a2 * Improved TLS connection management * OpenSSL 1.1 support * Stubby, Server version of getdns_query that by default listens on 127.0.0.1 and ::1 and reads config from /etc/stubby.conf and $HOME/.stubby.conf * 2016-07-14: Version 1.1.0a1 * Conversion functions from text strings to getdns native types: getdns_str2dict(), getdns_str2list(), getdns_str2bindata() and getdns_str2int() * A getdns_context_config() function that configures a context with settings given in a getdns_dict * A a getdns_context_set_listen_addresses() function and companion getdns_reply() function to construct simple name servers. * Relocate getdns_query to src/tools and build by default * Enhancements to the logic used to select connection based upstream transports (TCP, TLS) to improve robustness and re-use of connections/upstreams. * 2016-07-14: Version 1.0.0b2 * Collect coverage information from the unit tests Thanks Shane Kerr * pkg-config for the getdns_ext_event library Thanks Tom Pusateri * Bugfix: Multiple requests on the same upstream with a transport that keeps connections open in synchronous stub mode. * Canonicalized DNSSEC chain with dnssec_return_validation_chain (when validated) * A dnssec_return_full_validation_chain extension which includes then validated resource records. * Bugfix: Callbacks fired while scheduling (answer from cache) with the unbound plugable event API * header extension to set opcode and flags in stub mode * Unit tests that cover more code * Static checking with the clang analyzer * getdns_pretty_print_dict prints dname's as primitives * Accept just bindata's instead of address dicts. Allow misshing "address_type" in address dicts. * TLS session resumption * -C option to getdns_query to configure context from a json like formatted file. The output of -i (print API information) can be used as config file directly. Settings may also be given in this format as arguments of the getdns_query command directly. * DNS server mode for getdns_query. Enable by providing addresses to listen on, either by giving "-z " options or by providing "listen_addresses" in the config file or settings. * Bugfixes from deckard testing: CNAME loop protection. * "srv_addresses" in response dict with getdns_service() * use libbsd when available Thanks Guillem Jover * Bugfix: DNSSEC wildcard validation issue * Bugfix: TLS timeouts not re-using a connection * A getdns_context_get_eventloop(), to get the current (pluggable) eventloop from context * getdns_query now uses the default event loop (instead of custom) * Return call_reporting info in case of timeout Thanks Robert Groenenberg * Bugfix: Build fails with autoconf 2.63, works with 2.68. Thanks Robert Groenenberg * Doxygen output for getdns.h and getdns_extra.h only * Do not call SSL_library_init() from getdns_context_create() when the second bit from the set_from_os parameter is set. * 2016-03-31: Version 1.0.0b1 * openssl 1.1.0 support * GETDNS_APPEND_NAME_TO_SINGLE_LABEL_FIRST default suffix handling * getdns_context_set_follow_redirects() * Read suffix list from registry on Windows * A dnssec_return_all_statuses extension * Set root servers without temporary file (libunbound >= 1.5.8 needed) * Eliminate unit test's ldns dependency * pkts wireformat <-> getdns_dict <-> string conversion functions * Eliminate all side effects when doing sync requests (libunbound >= 1.5.9 needed) * Bugfix: Load gost algorithm if digest is seen before key algorithm Thanks Jelte Janssen * Bugfix: Respect DNSSEC skew. * Offline dnssec validation for any given point in time * Correct return value in documentation for getdns_pretty_print_dict(). Thanks Linus Nordberg * Bugfix: Don't treat "domain" or "search" as a nameserver. Thanks Linus Nordberg * Use the default CA trust store on Windows (for DNS over TLS). * Propagate eventloop to unbound when unbound has pluggable event loops (libunbound >= 1.5.9 needed) * Replace mini_event extension by default_eventloop * Bugfix: Segfault on NULL pin * Bugfix: Correct output of get_api_settings * Bugfix: Memory leak with getdns_get_api_information() Thanks Robert Groenenberg. * 2015-12-31: Version 0.9.0 * Update of unofficial extension to the API that supports stub mode TLS verification. GETDNS_AUTHENTICATION_HOSTNAME is replaced by GETDNS_AUTHENTICATION_REQUIRED (but remains available as an alias). Upstreams can now be configured with either a hostname or a SPKI pinset for TLS authentication (or both). If the GETDNS_AUTHENTICATION_REQUIRED option is used at least one piece of authentication information must be configured for each upstream, and all the configured authentication information for an upstream must validate. * Remove STARTTLS implementation (no change to SPEC) * Enable TCP Fast Open when possible. Add OSX support for TFO. * Rename return_call_debugging to return_call_reporting * Bugfix: configure problem with getdns-0.5.1 on OpenBSD Thanks Claus Assmann. * pkg-config support. Thanks Neil Cook. * Functions to convert from RR dicts to wireformat and text format and vice versa. Including a function that builds a getdns_list of RR dicts from a zonefile. * Use the with the getdns_context_set_dns_root_servers() function provided root servers in recursing resolution modus. * getdns_query option (-f) to read a DNSSEC trust anchor from file. * getdns_query option (-R) to read a "root hints" file. * Bugfix: Detect and prevent duplicate NSEC(3)s to be returned with dnssec_return_validation_chain. * Bugfix: Remove duplicate RRs from RRsets when DNSSEC verifying * Client side edns-tcp-keepalive support * TSIG support + getdns_query syntax to specify TSIG parameters per upstream: @[^[:]:] * Bugfix: Allow truncated answers to be returned in case of missing fallback transport. * Verify upstream TLS pubkeys with pinsets; A getdns_query option (-K) to attach pinsets to getdns_contexts. Thanks Daniel Kahn Gillmor * Initial support for Windows. Thanks Gowri Visweswaran * add_warning_for_bad_dns extension * Try and retry with suffixes giving with getdns_context_set_suffix() following directions given by getdns_context_set_append_name() getdns_query options to set suffixes and append_name directions: '-W' to append suffix always (default) '-1' to append suffix only to single label after failure '-M' to append suffix only to multi label name after failure '-N' to never append a suffix '-Z ' to set suffixes with the given comma separated list * Better help text for getdns_query (printed with the '-h' option) * Setting the +specify_class extension with getdns_query * Return NOT_IMPLEMENTED for not implemented namespaces, and the not implemented getdns_context_set_follow_redirects() function. * 2015-11-18: Version 0.5.1 * Bugfix: growing upstreams arrow. * Bugfix: Segfault on timeout in specific conditions * Bugfix: install getdns_extra.h from build location * Bugfix: Don't let cookies overwrite existing EDNS0 options * Don't link libdl * The EDNS(0) Padding Option (draft-mayrhofer-edns0-padding). When using DNS over TLS, query sizes will be padded to multiples of a block size given with: getdns_context_set_tls_query_padding_blocksize() * An EDNS client subnet private option, that will ask a EDNS client subnet aware resolver to not reveal any details about the originating network. See: draft-ietf-dnsop-edns-client-subnet Set with: getdns_context_set_edns_client_subnet_private() * The return_call_debugging extension. The extension will also return the transport used on top of the information about the request which is described in the API spec. * A dnssec_roadblock_avoidance extension. When set, the library will work in stub resolution mode and try to get a by DNSSEC validation assessed answer. On BOGUS answers the library will retry rescursive resolution mode. This is the simplest form of passive roadblock detection and avoidance: draft-ietf-dnsop-dnssec-roadblock-avoidance. Use the --enable-draft-dnssec-roadblock-avoidance option to configure to compile with this extension. * 2015-10-29: Version 0.5.0 * Native crypto. No ldns dependency anymore. (ldns still necessary to be able to run tests though) * JSON pointer arguments to getdns_dict_get_* and getdns_dict_set_* to dereference nested dicts and lists. * Bugfix: DNSSEC code finding zone cut with redirects + pursuing unsigned DS answers close to the root. Thanks Theogene Bucuti! * Default port for TLS changed to 853 * Unofficial extension to the API to allow TLS hostname verification to be required for stub mode when using only TLS as a transport. When required a hostname must be supplied in the 'hostname' field of the upstream_list dict and the TLS cipher suites are restricted to the 4 AEAD suites recommended in RFC7525. * 2015-09-09: Version 0.3.3 * Fix clearing upstream events on shutdown * Fix dnssec validation of direct CNAME queries. Thanks Simson L. Garfinkel. * Fix get_api_information():version_string also for release candidates * 2015-09-04: Version 0.3.2 * Fix returned upstreams list by getdns_context_get_api_information() * Fix some autoconf issues when srcdir != builddir * Fix remove build date from manpage version for reproducible builds * Fix transport fallback issues plus transport fallback unit test script * Fix string bindata's need not contain trailing zero byte * --enable-stub-only configure option for stub only operation. Stub mode will be the default. Removes the dependency on libunbound * --with-getdns_query compiles and installs the getdns_query tool too * Fix assert on context destruction from a callback in stub mode too. * Use a thread instead of a process for running the unbound event loop. * 2015-07-18: Version 0.3.1 * Fix repeating rdata fields * 2015-07-17: Version 0.3.0 * Unit test for spurious execute bits. Thanks Paul Wouters. * Added new transport list options in API. The option is now an ordered list of GETDNS_TRANSPORT_UDP, GETDNS_TRANSPORT_TCP, GETDNS_TRANSPORT_TLS, GETDNS_TRANSPORT_STARTTLS. * Added new context setting for idle_timeout * CSYNC RR type * EDNS0 COOKIE option code set to 10 * dnssec_return_validation_chain for negative and insecure responses. * dnssec_return_validation_chain return a single RRSIG on each RRSET (whenever possible) * getdns_validate_dnssec() accept replies from the replies_tree * getdns_validate_dnssec() asses negative and insecure responses. * Native stub dnssec validation * Implemented getdns_context_set_dnssec_trust_anchors() * Switch freely between stub and recursive mode * getdns_query -k shows default trust anchors * functions and defines to get library and API versions in string and numeric values: getdns_get_version(), getdns_get_version_number(), getdns_get_api_version() and getdns_get_api_version_number() * 2015-05-21: Version 0.2.0 * Fix libversion numbering: Thanks Daniel Kahn Gillmor * run_once method for the libevent extension * autoreconf -fi on FreeBSD always, because of newer libtool version suitable for FreeBSD installs too. Thanks Robert Edmonds * True asynchronous processing of the new TLS transport options * GETDNS_TRANSPORT_STARTTLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN transport option. * Manpage fixes: Thanks Anthony Kirby * 2015-04-19: Version 0.1.8 * The GETDNS_TRANSPORT_TLS_ONLY_KEEP_CONNECTIONS_OPEN and GETDNS_TRANSPORT_TLS_FIRST_AND_FALL_BACK_TO_TCP_KEEP_CONNECTIONS_OPEN DNS over TLS transport options. * 2015-04-08: Version 0.1.7 * Individual getter functions for context settings * Fix: --with-current-date function to make build deterministically reproducible (i.e. the GETDNS_COMPILATION_COMMENT define from getdns.h contains a date value). Thanks Ondřej Surý * Fix: Include m4 dir in distribution tarball * Fix: Link build requirements in tests too. Thanks Ondřej Surý * Fix: Remove executable flags on source files. Thanks Paul Wouters * Fix: Return "just_address_answers" only when queried for addresses * Eliminate ldns intermediate wireformat parsing * The CSYNC RR type * Fix: canonical_name in response dict returns the canonical name found after following all CNAMEs * Implementation of the section 6 and 7 version of draft-ietf-dnsop-cookies-01.txt for stub resolution. Enable with the --enable-draft-edns-cookies option to configure. Use it by setting the edns_cookies extension to GETDNS_EXTENSION_TRUE. * Pretty printing of lists with: char *getdns_pretty_print_list(getdns_list *list) * Output to json format with: char * getdns_print_json_dict(const getdns_dict *some_dict, int pretty); char * getdns_print_json_list(const getdns_list *some_list, int pretty); * snprintf style versions of the dict, list and json print functions. * Better random number generation with OpenBSD's arc4random * Let getdns_address schedule the AAAA query first. This results in AAAA being the first in the just_address_answers sections of the response dict. * New context update callback function to also return a user given argument along with the context and which item was changed. Thanks Scott Hollenbeck. * Demotivate use of getdns_strerror and expose getdns_get_errorstr_by_id. Thanks Scott Hollenbeck. * A getter for context update callback, to allow for chaining update callbacks. * 2015-01-16: Version 0.1.6 * Fix: linking against libev on FreeBSD * Fix: Let configure report problem on FreeBSD when configuring with libevent and libunbound <= 1.4.22 is not compiled with libevent. * Fix: Build on Mac OS-X * Fix: Lintian errors in manpages * Better libcheck detection * Better portability with UNIX systems * 2014-10-31: Version 0.1.5 * Unit tests for transport settings * Fix: adhere to set maximum UDP payload size * API change: when no maximum UDP payload size is set, outgoing values will adhere to the suggestions in RFC 6891 and may follow a scheme that uses multiple values to maximize receptivity. * Stub mode use 1232 maximum UDP payload size when connecting to an IPv6 upstreams and 1432 with an IPv4 upstream. * Evaluate namespaces (or not) on a per query basis * GETDNS_NAMESPACE_LOCALNAMES namespace now gives just_address_answers only and does not mimic a DNS packet answer anymore * The add_opt_parameters extension * IPv6 scope_id support with link-local addresses. Both with parsing /etc/resolv.conf and by providing them explicitly via getdns_context_set_upstream_recursive_servers * Query for A and AAAA simultaneously with return_both_v4_and_v6 * GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN DNS transport * Fix: Answers without RRs in query secion (i.e. REFUSED) * Fix: Return empty response dict on timeout in async mode too * Move spec examples to spec subdirectory * Fix issue#76: Setting UDP Payload size below 512 should not error * Fix: Include OPT RR in response dict always (even without options) * TCP Fast open support (linux only). Enable with the --enable-tcp-fastopen configure option * Bump library version because of binary API change * 2014-09-03: Version 0.1.4 * Synchronous resolves now respect timeout setting, * On timeout *_sync functions now return GETDNS_RETURN_GOOD and a response dict with "status" GETDNS_RESPSTATUS_ALL_TIMEOUT> * Fix issue#50: getdns_dict_remove_name returns GETDNS_RETURN_GOOD on success. * Fix Issue#54: set_ub_dns_transport() not working * Fix Issue#49: Typo in documentation (thanks Stephane Bortzmeyer) * getdns_context_set_limit_outstanding_queries(), getdns_context_set_dnssec_allowed_skew() and getdns_context_set_edns_maximum_udp_payload_size() now working * _unknown rdata field for unknown or unsupported RR types * Temporarily disable timeout unit test 3 because of unpredictable results * Spec updated to version 0.507 * Renamed "resolver_type" to "resolution_type" in dict returned from getdns_context_get_api_information() * Added GETDNS_RESPSTATUS_ALL_BOGUS_ANSWERS return code for with the dnssec_return_only_secure extension * Added support for CDS and CDNSKEY RR types, but needs ldns > 1.6.17 to be able to parse the wire format (not released yet at time of writing) * Added OPENPGPKEY RR type, but no rdata fields implementation yet * Updated spec to version 0.508 (September 2014) * Also chase NSEC and NSEC3 RRSIGs with dnssec_return_validation_chain * 2014-06-25: Version 0.1.3 * libtool chage, remove -release, added -version-info * Update specification to the June 2014 version (0.501) * 2014-06-02: Version 0.1.2 * Fixed rdata fields for MX * Expose only public API symbols * Updated manpages * specify_class extension * Build from separate build directory * Anticipate libunbound not returning the answer packet * Pretty print bindata's representing IP addresses * Anticipate absence of implicit DSO linking * Mention getdns specific options to configure in INSTALL Thanks Paul Hoffman * Mac OSX package built instructions for generic user in README.md Thanks Joel Purra * Fixed build problems on RHEL/CentOS due using libevent 1.x * 2014-03-24 : Version 0.1.1 * default to NOT build extensions (libev, libuv, libevent), handle --with/--without options to configure for them * Fixed some build/make nits * respect configure --docdir=X * Documentation/man page updates * Fix install and cpp guards in getdns_extra.h * Add method to switch between threads and fork mode for unbound * Fixes for libuv integration (saghul) * Fixes for calling getdns_destroy_context within a callback * Fixed signal related defines/decls * 2014-02-25 : Version 0.1.0 * Initial public release of the getdns API getdns-1.6.0/LICENSE000066400000000000000000000027111362622307100140120ustar00rootroot00000000000000Copyright (c) 2013, Verisign, Inc., NLnet Labs All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the names of the copyright holders nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. getdns-1.6.0/NEWS000066400000000000000000000000431362622307100135000ustar00rootroot00000000000000this page intentionally left blank getdns-1.6.0/README.md000066400000000000000000000412551362622307100142720ustar00rootroot00000000000000getdns ====== # Overview of getdns * GitHub: getdns is an implementation of a modern asynchronous DNS API; the specification was originally edited by Paul Hoffman. It is intended to make all types of DNS information easily available to application developers and non-DNS experts. ## Why you might want getdns Traditional access to DNS data from applications has several limitations: * APIs require applications to have considerable sophistication about DNS data and data types * Some kinds of data about the response (notably, the resource record set time to live) is not exposed via any API, so applications need to process raw protocol responses to get such data * APIs are often blocking, meaning asynchronous access is not possible without some work * Sophisticated uses of the DNS (things like IDNA and DNSSEC validation) require considerable application work, possibly by application developers with little experience with the vagaries of DNS. getdns also provides an experimental DNS Privacy enabled client called 'stubby' - see below for more details. ## Motivation for providing the API The developers are of the opinion that DNSSEC offers a unique global infrastructure for establishing and enhancing cryptographic trust relations. With the development of this API we intend to offer application developers a modern and flexible interface that enables end-to-end trust in the DNS architecture, and which will inspire application developers to implement innovative security solutions in their applications. ### API Documentation Note that this implementation offers additional functionality to supplement that in the [official getdns API](https://getdnsapi.net/documentation/spec/). Some additions are convenient utility functions but other functionality is experimental prior to be being recommended for inclusion in the official API. The [Doxygen documentation](https://getdnsapi.net/doxygen/modules.html) provides the details of the full API for this implementation. ## License This implementation is licensed under the New BSD License (BSD-new). Obtaining and getting started with getdns ========================================= The project home page at [getdnsapi.net](https://getdnsapi.net) provides documentation, binary downloads, and news regarding the getdns API implementation. This README file captures the goals and direction of the project and the current state of the implementation. If you are just getting started with the library take a look at the section below that describes building and handling external dependencies for the library. ### Examples Once it is built you should take a look at `spec/example` to see how the library is used. # Download Download the sources from our [github repo](https://github.com/getdnsapi/getdns) or from [getdnsapi.net](https://getdnsapi.net) and verify the download using the checksums (SHA1 or MD5) or using gpg to verify the signature. Our keys are available from the [pgp keyservers](https://keyserver.pgp.com) * `willem@nlnetlabs.nl`, key id E5F8F8212F77A498 # Releases Release numbering follows the [Semantic Versioning](http://semver.org/) approach. The code is currently under active development. The following requirements were met as conditions for the present release: * code compiles cleanly on at least the primary target platforms: OSX, Linux (RHEL/CentOS, Ubuntu), FreeBSD * examples must compile and run cleanly * there must be clear documentation of supported and unsupported elements of the API # External Dependencies If you are installing from packages, you have to install the library and also the library-devel (or -dev) for your package management system to get the the necessary compile time files. External dependencies are linked outside the getdns API build tree (we rely on CMake to find them). We would like to keep the dependency tree short, see [Minimising Dependancies](#minimizing-dependancies) for more details. Required for all builds: * [libssl and libcrypto from the OpenSSL Project](https://www.openssl.org/) version 1.0.2 or later. Using OpenSSL 1.1 is recommended due to TSL 1.3 support. Required for all builds that include recursive functionality: * [libunbound from NLnet Labs](https://unbound.net/) version 1.5.9 or later. (Note: linking to libunbound is not yet supported on Windows, see [Windows 10](#microsoft-windows-10)) Required for all builds that include IDN functionality: * [libidn2 from the FSF](https://www.gnu.org/software/libidn/) version 2.0.0 and higher. Required to build the documentation: * [Doxygen](http://www.doxygen.nl) is used to generate documentation; while this is not technically necessary for the build it makes things a lot more pleasant. For example, to build on Ubuntu 18.04 or later, you would need the following packages for a full build: # apt install build-essential libunbound-dev libidn2-dev libssl-dev cmake # Building If you are building from git, you need to do the following before building: # git submodule update --init From release 1.6.0 getdns uses CMake (previous versions used autoconf/libtool). To build from this release and later use: # cmake . # make If you are unfamiliar with CMake, see our [CMake Quick Start](https://getdnsapi.net/quick-start/cmake-quick-start/) for how to use CMake options to customise the getdns build. As well as building the getdns library two other tools are installed by default: * getdns_query: a command line test script wrapper for getdns. This can be used to quickly check the functionality of the library, see (#using-getdnsquery) * getdns_server_mon: test DNS server function and capabilities Additionally `Stubby` a DNS Privacy enabled client can also be built and installed by using the `BUILD_STUBBY` option when running `cmake`, see [Stubby](#stubby). ## Minimizing dependencies * getdns can be configured for stub resolution mode only with the `ENABLE_STUB_ONLY` option to `cmake`. This removes the dependency on `libunbound`. * Currently getdns only offers two helper functions to deal with IDN: `getdns_convert_ulabel_to_alabel` and `getdns_convert_alabel_to_ulabel`. If you do not need these functions, getdns can be configured to compile without them by setting the`USE_LIBIDN2` option to `cmake` to OFF. * When `ENABLE_STUB_ONLY` is ON, and `USE_LIBIDN2` is OFF, getdns has only one dependency left, which is OpenSSL. ## Extensions and Event loop dependencies The implementation works with a variety of event loops, each built as a separate shared library. See [this Doxygen page](https://getdnsapi.net/doxygen/group__eventloops.html) and [this man page](https://getdnsapi.net/documentation/manpages/#ASYNCHRONOUS USE) for more details. * [libevent](http://libevent.org). Note: the examples *require* this. libevent 2.x is required. * [libuv](https://libuv.org/) * [libev](http://software.schmorp.de/pkg/libev.html) ## Using getdns_query Example test queries using `getdns_query` (pointed at Google Public DNS) and requesting the `call_reporting` extension which provides information on the transport and query time: getdns_query -s example.com A @8.8.8.8 +return_call_reporting (UDP) getdns_query -s example.com A @8.8.8.8 -T +return_call_reporting (TCP) getdns_query -s example.com A @8.8.8.8 -L +return_call_reporting (TLS without authentication) getdns_query -s getdnsapi.net A +dnssec_return_status +return_call_reporting (DNSSEC) ## Stubby * Stubby is an implementation of a DNS Privacy enabled stub resolver that encrypts DNS queries using TLS. It is currently suitable for advanced/technical users - all feedback is welcome! * Details on how to use Stubby can be found in the [Stubby Reference Guide](https://dnsprivacy.org/wiki/x/JYAT). * Also see [dnsprivacy.org](https://dnsprivacy.org) for more information on DNS Privacy. ## Experimental support for GnuTLS A project to allow user selection of either OpenSSL or GnuTLS is currently a work in progress. At present a user may select to use GnuTLS for the majority of the supported functionality, however, OpenSSL is still required for some cryptographic functions. ## Regression Tests A suite of regression tests are included with the library, if you make changes or just want to sanity check things on your system take a look at src/test. You will need to install [libcheck](https://libcheck.github.io/check/). The check library is also available from many of the package repositories for the more popular operating systems. Note: The tests currently do not run on Windows because of a dependancy on bash. ## DNSSEC dependencies For the library to be DNSSEC capable, it needs to know the root trust anchor. The library will try to load the root trust anchor from `/etc/unbound/getdns-root.key` by default. This file is expected to have one or more `DS` or `DNSKEY` resource records in presentation (i.e. zone file) format. Note that this is different than the format of BIND.keys. ## Zero configuration DNSSEC When the root trust anchor is not installed in the default location and a DNSSEC query is done, getdns will try to use the trust anchors published here: http://data.iana.org/root-anchors/root-anchors.xml . It will validate these anchors with the ICANN Certificate Authority certificate following the procedure described in [RFC7958]. The `root-anchors.xml` and `root-anchors.p7s` S/MIME signature will be cached in the `$HOME/.getdns` directory on Unixes, and the `%appdata%\getdns` directory on Windows. When using trust-anchors from the `root-anchors.xml` file, getdns will track the keys in the root DNSKEY rrset and store a copy in `$HOME/.getdns/root.key` on Unixes, and `%appdata%\getdns\root.key` on Windows. Only when the KSK DNSKEY's change, a new version of `root-anchors.xml` is tried to be retrieved from [data.iana.org](https://data.iana.org/root-anchors/). A installed trust-anchor from the default location (`/etc/unbound/getdns-root.key`) that fails to validate the root DNSKEY RRset, will also trigger the "Zero configuration DNSSEC" procedure described above. Support ======= ## Mailing lists We have a [getdns users list](https://lists.getdnsapi.net/mailman/listinfo/users) for this implementation. ## Tickets and Bug Reports Tickets and bug reports should be reported via the [GitHub issues list](https://github.com/getdnsapi/getdns/issues). Features of this release ======================== ## Goals The goals of this implementation of the getdns API are: * Provide an open source implementation, in C, of the formally described getdns API by getdns API team at * Support FreeBSD, OSX, Linux (CentOS/RHEL, Ubuntu) * Support Windows 10 * Include examples and tests as part of the build * Document code using doxygen * Leverage github as much as possible for project coordination * Follow the BSD coding style/standards Non-goals (things we will not be doing at least initially) include: * implementation of the traditional DNS related routines (gethostbyname, etc.) ## Language Bindings In parallel, the team is actively developing bindings for various languages. For more information, visit this [webpage](https://getdnsapi.net/bindings/). ## Unsupported getDNS Features The following API calls are documented in getDNS but *not supported* by the implementation at this time: * Detecting changes to resolv.conf and hosts * MDNS, NIS and NetBIOS namespaces (only DNS and LOCALFILES are supported) ### Minor omissions The following minor implementation omissions are noted: Recursive mode does not support: * TLS as a transport * Non-zero connection idle timeouts or query pipelining * Anything other than query_type and resolution_type in the return_call_reporting extension Stub mode does not support: * Non zero idle timeouts for synchronous calls # Known Issues * None # Supported Platforms The platforms listed here are intended to help ensure that we catch platform specific breakage prior to release. * Ubuntu 18.04 LTS and newer LTS releases * Microsoft Windows 10 * FreeBSD 11.3 and newer * RHEL/CentOS 8 * OSX 10.14 and 10.15 ### Platform Specific Build Notes [![Build Status](https://travis-ci.org/getdnsapi/getdns.png?branch=master)](https://travis-ci.org/getdnsapi/getdns) ## FreeBSD If you're using [FreeBSD](https://www.freebsd.org/), you may install getdns via the [ports tree](https://www.freshports.org/dns/getdns/) by running: `cd /usr/ports/dns/getdns && make install clean` If you are using FreeBSD 10 getdns can be intalled via 'pkg install getdns'. ## Ubuntu getdns should also work on Ubuntu 16.04, however if you require IDN functionality you will have to install a recent version of libidn2 via a ppa e.g. from https://launchpad.net/~ondrej/+archive/ubuntu/php You will also have to build Unbound from source code to provide libunbound at version >= 1.5.9. ## OSX A self-compiled version of OpenSSL or the version installed via Homebrew is required and the options OPENSSL_ROOT_DIR, OPENSSL_CRYPTO_LIBRARY and OPENSSL_SSL_LIBRARY can be used to specify the location of the libraries. Note: If using a self-compiled version, manual configuration of certificates into /usr/local/etc/openssl/certs is required for TLS authentication to work. ### Homebrew If you're using [Homebrew](http://brew.sh/), you may run `brew install getdns`. By default, this will only build the core library without any 3rd party event loop support. To install the [event loop integration libraries](https://getdnsapi.net/doxygen/group__eventloops.html) that enable support for libevent, libuv, and libev, run: `brew install getdns --with-libevent --with-libuv --with-libev`. All switches are optional. Note that in order to compile the examples, the `--with-libevent` switch is required. Additionally, getdns is linked against the the OpenSSL library installed by Homebrew. Note that the Homebrew OpenSSL installation clones the Keychain certificates to the default OpenSSL location so TLS certificate authentication should work out of the box. ## Microsoft Windows 10 You will need CMake for Windows. Installers can be downloaded from https://cmake.org/download/. Windows versions of the following libraries are available using [the vcpkg package manager](https://docs.microsoft.com/en-us/cpp/build/vcpkg). * OpenSSL * libevent * libiconv (required for libidn2) * libidn2 * libyaml * libuv Once these are installed, set CMake variables CMAKE_INCLUDE_PATH and CMAKE_LIBRARY_PATH to the vcpkg include and library directories e.g. `../vcpkg/installed/x64-windows/include` and `../vcpkg/installed/x64-windows/lib`. To generate a project suitable for use in Visual Studio, select the appropriate Visual Studio generator in CMake. Once generated, the cmake-gui Open Project button can be used to load the project into Visual Studio. ### Limitations on Windows Full support for Windows is a work in progress. The following limitations will be addresses in future: * At present, no native Windows DLL version of libunbound exists; support for linking against libunbound is not currently available. The default build option for ENABLE_STUB_ONLY_ is ON for Windows. * The getdns unit tests (built with `make test`) require libcheck which is not currently available for Windows and so cannot be built. * The getdns tpkg test suite is not currently supported on Windows. * The detection of the location of the `/etc/hosts` file should be optimised - it currently assumes Windows is installed in the default directory on the C: drive Contributors ============ * Claus Assman * Theogene Bucuti * Andrew Cathrow, Verisign Labs * Neil Cook * Saúl Ibarra Corretgé * Craig Despeaux, Verisign, Inc. * John Dickinson, Sinodun * Sara Dickinson, Sinodun * Robert Edmonds * Angelique Finan, Verisign, Inc. * Simson Garfinkel * Daniel Kahn Gillmor * Neel Goyal, Verisign, Inc. * Bryan Graham, Verisign, Inc. * Robert Groenenberg * Jim Hague, Sinodun * Paul Hoffman * Scott Hollenbeck, Verising, Inc. * Christian Huitema * Shumon Huque, Verisign Labs * Jelte Janssen * Guillem Jover * Shane Kerr * Anthony Kirby * Olaf Kolkman, NLnet Labs * Sanjay Mahurpawar, Verisign, Inc. * Allison Mankin, Verisign, Inc. - Verisign Labs. * Sai Mogali, Verisign, Inc. * Linus Nordberg * Benno Overeinder, NLnet Labs * Joel Purra * Tom Pusateri * Prithvi Ranganath, Verisign, Inc. * Hoda Rohani, NLnet Labs * Rushi Shah, Verisign, Inc. * Vinay Soni, Verisign, Inc. * Melinda Shore, No Mountain Software LLC * Bob Steagall, Verisign, Inc. * Andrew Sullivan * Ondřej Surý * Willem Toorop, NLnet Labs * Gowri Visweswaran, Verisign Labs * Wouter Wijngaards, NLnet Labs * Glen Wiley, Verisign, Inc. * Paul Wouters Acknowledgements ================ The development team explicitly acknowledges Paul Hoffman for his initiative and efforts to develop a consensus based DNS API. We would like to thank the participants of the getdns-api mailing list (discontinued) for their contributions. getdns-1.6.0/cmake/000077500000000000000000000000001362622307100140645ustar00rootroot00000000000000getdns-1.6.0/cmake/include/000077500000000000000000000000001362622307100155075ustar00rootroot00000000000000getdns-1.6.0/cmake/include/cmakeconfig.h.in000066400000000000000000000320121362622307100205310ustar00rootroot00000000000000#ifndef CONFIG_H #define CONFIG_H #cmakedefine PACKAGE "@PACKAGE@" #cmakedefine PACKAGE_NAME "@PACKAGE_NAME@" #cmakedefine PACKAGE_VERSION "@PACKAGE_VERSION@" #cmakedefine PACKAGE_URL "@PACKAGE_URL@" #cmakedefine PACKAGE_BUGREPORT "@PACKAGE_BUGREPORT@" #cmakedefine PACKAGE_STRING "@PACKAGE_STRING@" #cmakedefine PACKAGE_TARNAME "@PACKAGE_TARNAME@" #cmakedefine HAVE_ASSERT_H 1 #cmakedefine HAVE_INTTYPES_H 1 #cmakedefine HAVE_LIMITS_H 1 #cmakedefine HAVE_SYS_LIMITS_H 1 #cmakedefine HAVE_STDARG_H 1 #cmakedefine HAVE_STDINT_H 1 #cmakedefine HAVE_STDIO_H 1 #cmakedefine HAVE_STDLIB_H 1 #cmakedefine HAVE_STRING_H 1 #cmakedefine HAVE_TIME_H 1 #cmakedefine HAVE_UNISTD_H 1 #cmakedefine HAVE_FCNTL_H 1 #cmakedefine HAVE_SIGNAL_H 1 #cmakedefine HAVE_SYS_POLL_H 1 #cmakedefine HAVE_POLL_H 1 #cmakedefine HAVE_RESOURCE_H 1 #cmakedefine HAVE_SYS_TYPES_H 1 #cmakedefine HAVE_SYS_STAT_H 1 #cmakedefine HAVE_ENDIAN_H 1 #cmakedefine HAVE_NETDB_H 1 #cmakedefine HAVE_ARPA_INET_H 1 #cmakedefine HAVE_NETINET_IN_H 1 #cmakedefine HAVE_NETINET_TCP_H 1 #cmakedefine HAVE_SYS_SELECT_H 1 #cmakedefine HAVE_SYS_SOCKET_H 1 #cmakedefine HAVE_SYS_SYSCTL_H 1 #cmakedefine HAVE_SYS_TIME_H 1 #cmakedefine HAVE_SYS_WAIT_H 1 #cmakedefine HAVE_WINDOWS_H 1 #cmakedefine HAVE_WINSOCK_H 1 #cmakedefine HAVE_WINSOCK2_H 1 #cmakedefine HAVE_WS2TCPIP_H 1 #cmakedefine GETDNS_ON_WINDOWS 1 #cmakedefine USE_WINSOCK 1 #cmakedefine HAVE_SSL 1 #cmakedefine USE_DANESSL 1 #cmakedefine HAVE_OPENSSL_SSL_H 1 #cmakedefine HAVE_OPENSSL_EVP_H 1 #cmakedefine HAVE_OPENSSL_ERR_H 1 #cmakedefine HAVE_OPENSSL_RAND_H 1 #cmakedefine HAVE_OPENSSL_CONF_H 1 #cmakedefine HAVE_OPENSSL_ENGINE_H 1 #cmakedefine HAVE_DSA_SIG_SET0 1 #cmakedefine HAVE_DSA_SET0_PQG 1 #cmakedefine HAVE_DSA_SET0_KEY 1 #cmakedefine HAVE_RSA_SET0_KEY 1 #cmakedefine HAVE_EVP_MD5 1 #cmakedefine HAVE_EVP_SHA1 1 #cmakedefine HAVE_EVP_SHA224 1 #cmakedefine HAVE_EVP_SHA256 1 #cmakedefine HAVE_EVP_SHA384 1 #cmakedefine HAVE_EVP_SHA512 1 #cmakedefine HAVE_EVP_DSS1 1 #cmakedefine HAVE_EVP_DIGESTVERIFY 1 #cmakedefine HAVE_EVP_MD_CTX_NEW 1 #cmakedefine HAVE_HMAC_CTX_NEW 1 #cmakedefine HAVE_NETTLE_GET_SECP_256R1 1 #cmakedefine HAVE_NETTLE_GET_SECP_384R1 1 #cmakedefine HAVE_TLS_CLIENT_METHOD 1 #cmakedefine HAVE_OPENSSL_VERSION_NUM 1 #cmakedefine HAVE_OPENSSL_VERSION 1 #cmakedefine HAVE_SSL_CTX_DANE_ENABLE 1 #cmakedefine HAVE_SSL_CTX_SET_CIPHERSUITS 1 #cmakedefine HAVE_SSL_SET_CIPHERSUITS 1 #cmakedefine HAVE_OPENSSL_INIT_CRYPTO 1 #cmakedefine HAVE_SSL_DANE_ENABLE 1 #cmakedefine HAVE_DECL_SSL_CTX_SET1_CURVES_LIST 1 #cmakedefine HAVE_DECL_SSL_SET1_CURVES_LIST 1 #cmakedefine HAVE_DECL_SSL_SET_MIN_PROTO_VERSION 1 #cmakedefine HAVE_X509_GET_NOTAFTER 1 #cmakedefine HAVE_X509_GET0_NOTAFTER 1 #cmakedefine HAVE_PTHREAD 1 #cmakedefine HAVE_WINDOWS_THREADS 1 #cmakedefine RUNSTATEDIR "@RUNSTATEDIR@" #cmakedefine TRUST_ANCHOR_FILE "@PATH_TRUST_ANCHOR_FILE@" #cmakedefine GETDNS_FN_RESOLVCONF "@PATH_RESOLVCONF@" #cmakedefine GETDNS_FN_HOSTS "@PATH_HOSTS@" #cmakedefine DNSSEC_ROADBLOCK_AVOIDANCE 1 #cmakedefine HAVE_MDNS_SUPPORT 1 #cmakedefine STUB_NATIVE_DNSSEC 1 #cmakedefine MAXIMUM_UPSTREAM_OPTION_SPACE @MAXIMUM_UPSTREAM_OPTION_SPACE@ #cmakedefine EDNS_PADDING_OPCODE @EDNS_PADDING_OPCODE@ #cmakedefine MAX_CNAME_REFERRALS @MAX_CNAME_REFERRALS@ #cmakedefine DRAFT_RRTYPES @DRAFT_RRTYPES@ #cmakedefine EDNS_COOKIES 1 #cmakedefine EDNS_COOKIE_OPCODE @EDNS_COOKIE_OPCODE@ #cmakedefine EDNS_COOKIE_ROLLOVER_TIME @EDNS_COOKIE_ROLLOVER_TIME@ #cmakedefine UDP_MAX_BACKOFF @MAX_UDP_BACKOFF@ #cmakedefine HAVE_DECL_GETENTROPY 1 #cmakedefine HAVE_DECL_INET_PTON 1 #cmakedefine HAVE_DECL_INET_NTOP 1 #cmakedefine HAVE_WIN_DECL_INET_PTON 1 #cmakedefine HAVE_WIN_DECL_INET_NTOP 1 #cmakedefine HAVE_DECL_MKSTEMP 1 #cmakedefine HAVE_DECL_SIGEMPTYSET 1 #cmakedefine HAVE_DECL_SIGFILLSET 1 #cmakedefine HAVE_DECL_SIGADDSET 1 #cmakedefine HAVE_DECL_STRPTIME 1 #cmakedefine HAVE_DECL_TCP_FASTOPEN 1 #cmakedefine HAVE_DECL_TCP_FASTOPEN_CONNECT 1 #cmakedefine HAVE_DECL_MSG_FASTOPEN 1 #if defined(HAVE_DECL_INET_PTON) || defined(HAVE_WIN_DECL_INET_PTON) #undef HAVE_DECL_INET_PTON #define HAVE_DECL_INET_PTON 1 #endif #if defined(HAVE_DECL_INET_NTOP) || defined(HAVE_WIN_DECL_INET_NTOP) #undef HAVE_DECL_INET_NTOP #define HAVE_DECL_INET_NTOP 1 #endif #cmakedefine HAVE_FCNTL 1 #cmakedefine HAVE_GETTIMEOFDAY 1 #cmakedefine HAVE_IOCTLSOCKET 1 #cmakedefine HAVE_SIGEMPTYSET 1 #cmakedefine HAVE_SIGFILLSET 1 #cmakedefine HAVE_SIGADDSET 1 #cmakedefine HAVE_STRPTIME 1 #cmakedefine HAVE_SIGSET_T 1 #cmakedefine HAVE__SIGSET_T 1 #cmakedefine HAVE_BSD_STDLIB_H 1 #cmakedefine HAVE_BSD_STRING_H 1 #cmakedefine HAVE_DECL_STRLCPY 1 #cmakedefine HAVE_DECL_ARC4RANDOM 1 #cmakedefine HAVE_DECL_ARC4RANDOM_UNIFORM 1 #cmakedefine HAVE_BSD_DECL_STRLCPY 1 #cmakedefine HAVE_BSD_DECL_ARC4RANDOM 1 #cmakedefine HAVE_BSD_DECL_ARC4RANDOM_UNIFORM 1 #cmakedefine HAVE_STRLCPY 1 #cmakedefine HAVE_ARC4RANDOM 1 #cmakedefine HAVE_ARC4RANDOM_UNIFORM 1 #cmakedefine HAVE_LIBUNBOUND 1 #cmakedefine HAVE_UNBOUND_EVENT_H 1 #cmakedefine HAVE_UNBOUND_EVENT_API 1 #cmakedefine HAVE_UB_CTX_SET_STUB 1 #cmakedefine HAVE_LIBIDN 1 #cmakedefine HAVE_LIBIDN2 1 #cmakedefine HAVE_NETTLE 1 #cmakedefine HAVE_NETTLE_DSA_COMPAT_H 1 #cmakedefine HAVE_NETTLE_EDDSA_H 1 #cmakedefine HAVE_EVENT2_EVENT_H 1 #cmakedefine HAVE_EVENT_BASE_NEW 1 #cmakedefine HAVE_EVENT_BASE_FREE 1 #cmakedefine DEFAULT_EVENTLOOP "@DEFAULT_EVENTLOOP@" #cmakedefine USE_POLL_DEFAULT_EVENTLOOP 1 #cmakedefine STRPTIME_WORKS 1 #cmakedefine FD_SETSIZE @FD_SETSIZE@ #cmakedefine REQ_DEBUG 1 #cmakedefine SCHED_DEBUG 1 #cmakedefine STUB_DEBUG 1 #cmakedefine DAEMON_DEBUG 1 #cmakedefine SEC_DEBUG 1 #cmakedefine SERVER_DEBUG 1 #cmakedefine ANCHOR_DEBUG 1 #cmakedefine KEEP_CONNECTIONS_OPEN_DEBUG 1 #cmakedefine USE_SHA1 1 #cmakedefine USE_SHA2 1 #cmakedefine USE_GOST 1 #cmakedefine USE_ECDSA 1 #cmakedefine USE_DSA 1 #cmakedefine USE_ED25519 1 #cmakedefine USE_ED448 1 #cmakedefine USE_OSX_TCP_FASTOPEN 1 #cmakedefine HAVE_NEW_UV_TIMER_CB 1 #cmakedefine HAVE_TARGET_ENDIANNESS #cmakedefine TARGET_IS_BIG_ENDIAN #cmakedefine HAVE___FUNC__ 1 #ifdef HAVE___FUNC__ #define __FUNC__ __func__ #else #define __FUNC__ __FUNCTION__ #endif #ifdef GETDNS_ON_WINDOWS /* On windows it is allowed to increase the FD_SETSIZE * (and nescessary to make our custom eventloop work) * See: https://support.microsoft.com/en-us/kb/111855 */ # ifndef FD_SETSIZE # define FD_SETSIZE 1024 # endif /* the version of the windows API enabled */ # ifndef WINVER # define WINVER 0x0600 // 0x0502 # endif # ifndef _WIN32_WINNT # define _WIN32_WINNT 0x0600 // 0x0502 # endif # ifdef HAVE_WS2TCPIP_H # include # endif # ifdef _MSC_VER # if _MSC_VER >= 1800 # define PRIsz "zu" # else # define PRIsz "Iu" # endif # include typedef SSIZE_T ssize_t; # else # define PRIsz "Iu" # endif # ifdef HAVE_WINSOCK2_H # include # endif /* detect if we need to cast to unsigned int for FD_SET to avoid warnings */ # ifdef HAVE_WINSOCK2_H # define FD_SET_T (u_int) # else # define FD_SET_T # endif /* Windows wants us to use _strdup instead of strdup */ # ifndef strdup # define strdup _strdup # endif /* Windows doesn't have strcasecmp and strncasecmp. */ # define strcasecmp _stricmp # define strncasecmp _strnicmp #else # define PRIsz "zu" #endif #ifdef HAVE_STDINT_H #include #endif #ifdef HAVE_STDIO_H #include #endif #ifdef HAVE_UNISTD_H #include #endif #ifdef HAVE_ASSERT_H #include #endif #ifdef HAVE_STRING_H #include #endif #ifdef __cplusplus extern "C" { #endif #if STDC_HEADERS #include #include #endif #ifdef HAVE_BSD_STDLIB_H #include #endif #ifdef HAVE_BSD_STRING_H #include #endif #if !defined(HAVE_STRLCPY) || !HAVE_DECL_STRLCPY || !defined(strlcpy) size_t strlcpy(char *dst, const char *src, size_t siz); #else #ifndef __BSD_VISIBLE #define __BSD_VISIBLE 1 #endif #endif #if !defined(HAVE_ARC4RANDOM) || !HAVE_DECL_ARC4RANDOM uint32_t arc4random(void); #endif #if !defined(HAVE_ARC4RANDOM_UNIFORM) || !HAVE_DECL_ARC4RANDOM_UNIFORM uint32_t arc4random_uniform(uint32_t upper_bound); #endif #ifndef HAVE_ARC4RANDOM void explicit_bzero(void* buf, size_t len); int getentropy(void* buf, size_t len); void arc4random_buf(void* buf, size_t n); void _ARC4_LOCK(void); void _ARC4_UNLOCK(void); #endif #ifdef COMPAT_SHA512 #ifndef SHA512_DIGEST_LENGTH #define SHA512_BLOCK_LENGTH 128 #define SHA512_DIGEST_LENGTH 64 #define SHA512_DIGEST_STRING_LENGTH (SHA512_DIGEST_LENGTH * 2 + 1) typedef struct _SHA512_CTX { uint64_t state[8]; uint64_t bitcount[2]; uint8_t buffer[SHA512_BLOCK_LENGTH]; } SHA512_CTX; #endif /* SHA512_DIGEST_LENGTH */ void SHA512_Init(SHA512_CTX*); void SHA512_Update(SHA512_CTX*, void*, size_t); void SHA512_Final(uint8_t[SHA512_DIGEST_LENGTH], SHA512_CTX*); unsigned char *SHA512(void* data, unsigned int data_len, unsigned char *digest); #endif /* COMPAT_SHA512 */ #ifdef USE_WINSOCK # ifndef _CUSTOM_VSNPRINTF # define _CUSTOM_VSNPRINTF static inline int _gldns_custom_vsnprintf(char *str, size_t size, const char *format, va_list ap) { int r = vsnprintf(str, size, format, ap); return r == -1 ? _vscprintf(format, ap) : r; } # define vsnprintf _gldns_custom_vsnprintf # endif #endif #ifdef __cplusplus } #endif /** Use on-board gldns */ #define USE_GLDNS 1 #ifdef HAVE_SSL # define GLDNS_BUILD_CONFIG_HAVE_SSL 1 #endif #ifdef HAVE_STDARG_H #include #endif #include #ifdef HAVE_SYS_SOCKET_H #include #endif #ifdef HAVE_SYS_SELECT_H #include #endif #ifdef HAVE_SYS_TYPES_H #include #endif #ifdef HAVE_SYS_STAT_H #include #endif #ifdef HAVE_NETINET_IN_H #include #endif #ifdef HAVE_NETINET_TCP_H #include #endif #ifdef HAVE_ARPA_INET_H #include #endif #ifdef HAVE_SIGNAL_H #include #endif #ifdef HAVE_SYS_TYPES_H #include #endif #ifdef HAVE_INTTYPES_H #include #endif #ifdef HAVE_LIMITS_H #include #endif #ifdef HAVE_SYS_LIMITS_H #include #endif #ifdef PATH_MAX #define _GETDNS_PATH_MAX PATH_MAX #else #define _GETDNS_PATH_MAX 2048 #endif #ifndef PRIu64 #define PRIu64 "llu" #endif #ifdef HAVE_ATTR_FORMAT # define ATTR_FORMAT(archetype, string_index, first_to_check) \ __attribute__ ((format (archetype, string_index, first_to_check))) #else /* !HAVE_ATTR_FORMAT */ # define ATTR_FORMAT(archetype, string_index, first_to_check) /* empty */ #endif /* !HAVE_ATTR_FORMAT */ #if defined(DOXYGEN) # define ATTR_UNUSED(x) x #elif defined(__cplusplus) # define ATTR_UNUSED(x) #elif defined(HAVE_ATTR_UNUSED) # define ATTR_UNUSED(x) x __attribute__((unused)) #else /* !HAVE_ATTR_UNUSED */ # define ATTR_UNUSED(x) x #endif /* !HAVE_ATTR_UNUSED */ #ifdef TIME_WITH_SYS_TIME # include # include #else # ifdef HAVE_SYS_TIME_H # include # else # include # endif #endif #ifdef __cplusplus extern "C" { #endif #if !defined(HAVE_STRPTIME) || !defined(STRPTIME_WORKS) #define strptime unbound_strptime struct tm; char *strptime(const char *s, const char *format, struct tm *tm); #endif #if !defined(HAVE_SIGSET_T) && defined(HAVE__SIGSET_T) typedef _sigset_t sigset_t; #endif #if !defined(HAVE_SIGEMPTYSET) # define sigemptyset(pset) (*(pset) = 0) #endif #if !defined(HAVE_SIGFILLSET) # define sigfillset(pset) (*(pset) = (sigset_t)-1) #endif #if !defined(HAVE_SIGADDSET) # define sigaddset(pset, num) (*(pset) |= (1L<<(num))) #endif #ifdef HAVE_LIBUNBOUND # include # ifdef HAVE_UNBOUND_EVENT_H # include # else # ifdef HAVE_UNBOUND_EVENT_API # ifndef _UB_EVENT_PRIMITIVES # define _UB_EVENT_PRIMITIVES struct ub_event_base; struct ub_ctx* ub_ctx_create_ub_event(struct ub_event_base* base); typedef void (*ub_event_callback_t)(void*, int, void*, int, int, char*); int ub_resolve_event(struct ub_ctx* ctx, const char* name, int rrtype, int rrclass, void* mydata, ub_event_callback_t callback, int* async_id); # endif # endif # endif #endif #ifndef HAVE_DECL_INET_PTON int inet_pton(int af, const char* src, void* dst); #endif #ifndef HAVE_DECL_INET_NTOP const char *inet_ntop(int af, const void *src, char *dst, size_t size); #endif #ifndef HAVE_DECL_MKSTEMP int mkstemp(char *template); #endif #ifndef HAVE_GETTIMEOFDAY int gettimeofday(struct timeval* tv, void* tz); #endif #ifdef __cplusplus } #endif #endif /* CONFIG_H */ getdns-1.6.0/cmake/include/getdns_shared_version.rc.in000066400000000000000000000012021362622307100230140ustar00rootroot000000000000001 VERSIONINFO FILEVERSION @version_current@,@version_revision@,@version_age@,0 PRODUCTVERSION @version_current@,@version_revision@,0,0 FILEOS 4 FILETYPE 2 FILESUBTYPE 0 BEGIN BLOCK "StringFileInfo" BEGIN BLOCK "040904e4" BEGIN VALUE "CompanyName", "getdns project\0" VALUE "ProductName", "getdns\0" VALUE "FileVersion", "@version_current@.@version_revision@\0" VALUE "ProductVersion", "@version_current@.@version_revision@\0" VALUE "LegalCopyright", "NLnet Labs, Sinodun, No Mountain Software. New BSD licence.\0" END END END getdns-1.6.0/cmake/modules/000077500000000000000000000000001362622307100155345ustar00rootroot00000000000000getdns-1.6.0/cmake/modules/FindCheck.cmake000066400000000000000000000052121362622307100203540ustar00rootroot00000000000000#[=======================================================================[.rst: FindCheck -------- Find the Check (Unit Testing Framework for C) library Imported targets ^^^^^^^^^^^^^^^^ This module defines the following :prop_tgt:`IMPORTED` targets: ``Check::Check`` The Check library, if found. Result variables ^^^^^^^^^^^^^^^^ This module will set the following variables in your project: ``Check_FOUND`` If false, do not try to use Check. ``CHECK_INCLUDE_DIR`` where to find check.h, etc. ``CHECK_LIBRARIES`` the libraries needed to use Check. ``CHECK_VERSION`` the version of the Check library found #]=======================================================================] find_path(CHECK_INCLUDE_DIR check.h HINTS "${CHECK_DIR}" "${CHECK_DIR}/include" ) # Check for PIC and non-PIC libraries. If PIC present, use that # in preference (as per Debian check.pc). find_library(CHECK_LIBRARY NAMES check_pic libcheck_pic HINTS "${CHECK_DIR}" "${CHECK_DIR}/lib" ) if (NOT CHECK_LIBRARY) find_library(CHECK_LIBRARY NAMES check libcheck HINTS "${CHECK_DIR}" "${CHECK_DIR}/lib" ) endif () set(CHECK_LIBRARIES "") # Check may need the math, subunit and rt libraries on Unix if (UNIX) find_library(CHECK_MATH_LIBRARY m) find_library(CHECK_RT_LIBRARY rt) find_library(CHECK_SUBUNIT_LIBRARY subunit) if (CHECK_MATH_LIBRARY) list(APPEND CHECK_LIBRARIES "${CHECK_MATH_LIBRARY}") endif () if (CHECK_RT_LIBRARY) list(APPEND CHECK_LIBRARIES "${CHECK_RT_LIBRARY}") endif () if (CHECK_SUBUNIT_LIBRARY) list(APPEND CHECK_LIBRARIES "${CHECK_SUBUNIT_LIBRARY}") endif () endif() if (CHECK_INCLUDE_DIR AND CHECK_LIBRARY) if (NOT TARGET Check::Check) add_library(Check::Check UNKNOWN IMPORTED) set_target_properties(Check::Check PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${CHECK_INCLUDE_DIR}" INTERFACE_LINK_LIBRARIES "${CHECK_LIBRARIES}" IMPORTED_LINK_INTERFACE_LANGUAGES "C" IMPORTED_LOCATION "${CHECK_LIBRARY}" ) endif () if (NOT CHECK_VERSION AND CHECK_INCLUDE_DIR AND EXISTS "${CHECK_INCLUDE_DIR}/check.h") file(STRINGS "${CHECK_INCLUDE_DIR}/check.h" CHECK_H REGEX "^#define CHECK_M[A-Z]+_VERSION") string(REGEX REPLACE "^.*\(([0-9]+)\).*\(([0-9]+)\).*\(([0-9]+)\).*$" "\\1.\\2.\\3" CHECK_VERSION "${CHECK_H}") endif () endif() list(APPEND CHECK_LIBRARIES "${CHECK_LIBRARY}") include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Check REQUIRED_VARS CHECK_LIBRARIES CHECK_INCLUDE_DIR VERSION_VAR CHECK_VERSION ) mark_as_advanced(CHECK_INCLUDE_DIR CHECK_LIBRARIES CHECK_LIBRARY CHECK_MATH_LIBRARY CHECK_RT_LIBRARY CHECK_SUBUNIT_LIBRARY) getdns-1.6.0/cmake/modules/FindGnuTLS.cmake000066400000000000000000000045521362622307100204610ustar00rootroot00000000000000#[=======================================================================[.rst: FindGnuTLS ---------- Find the GnuTLS library. Imported targets ^^^^^^^^^^^^^^^^ This module defines the following :prop_tgt:`IMPORTED` targets: ``GnuTLS::GnuTLS`` The GnuTLS library, if found. ``GnuTLS::Dane`` The GnuTLS DANE library, if found. Result variables ^^^^^^^^^^^^^^^^ This module will set the following variables in your project: ``GnuTLS_FOUND`` If false, do not try to use GnuTLS. ``GNUTLS_INCLUDE_DIR`` where to find GnuTLS headers. ``GNUTLS_LIBRARIES`` the libraries needed to use GnuTLS. ``GNUTLS_VERSION`` the version of the GnuTLS library found #]=======================================================================] find_path(GNUTLS_INCLUDE_DIR gnutls/gnutls.h HINTS "${GNUTLS_DIR}" "${GNUTLS_DIR}/include" ) find_library(GNUTLS_LIBRARY NAMES gnutls libgnutls HINTS "${GNUTLS_DIR}" "${GNUTLS_DIR}/lib" ) find_library(GNUTLS_DANE_LIBRARY NAMES gnutls-dane libgnutls-dane HINTS "${GNUTLS_DIR}" "${GNUTLS_DIR}/lib" ) set(GNUTLS_LIBRARIES "") if (GNUTLS_INCLUDE_DIR AND GNUTLS_LIBRARY AND GNUTLS_DANE_LIBRARY) if (NOT TARGET GnuTLS::GnuTLS) add_library(GnuTLS::GnuTLS UNKNOWN IMPORTED) set_target_properties(GnuTLS::GnuTLS PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${GNUTLS_INCLUDE_DIR}" IMPORTED_LINK_INTERFACE_LANGUAGES "C" IMPORTED_LOCATION "${GNUTLS_LIBRARY}" ) endif () if (NOT TARGET GnuTLS::Dane) add_library(GnuTLS::Dane UNKNOWN IMPORTED) set_target_properties(GnuTLS::Dane PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${GNUTLS_INCLUDE_DIR}" IMPORTED_LINK_INTERFACE_LANGUAGES "C" IMPORTED_LOCATION "${GNUTLS_DANE_LIBRARY}" ) endif () if (NOT GNUTLS_VERSION AND GNUTLS_INCLUDE_DIR) file(STRINGS "${GNUTLS_INCLUDE_DIR}/gnutls/gnutls.h" GNUTLS_VER_H REGEX "^#define GNUTLS_VERSION_(MAJOR|MINOR|PATCH) ") string(REGEX REPLACE "^.*_MAJOR ([0-9]+).*_MINOR ([0-9]+).*_PATCH ([0-9]+).*$" "\\1.\\2.\\3c" GNUTLS_VERSION "${GNUTLS_VER_H}") endif () endif() list(APPEND GNUTLS_LIBRARIES "${GNUTLS_LIBRARY}" "${GNUTLS_DANE_LIBRARY}") include(FindPackageHandleStandardArgs) find_package_handle_standard_args(GnuTLS REQUIRED_VARS GNUTLS_LIBRARIES GNUTLS_INCLUDE_DIR VERSION_VAR GNUTLS_VERSION ) mark_as_advanced(GNUTLS_INCLUDE_DIR GNUTLS_LIBRARIES GNUTLS_LIBRARY GNUTLS_DANE_LIBRARY) getdns-1.6.0/cmake/modules/FindLibev.cmake000066400000000000000000000026721362622307100204070ustar00rootroot00000000000000#[=======================================================================[.rst: FindLibev --------- Find the Libev library. Imported targets ^^^^^^^^^^^^^^^^ This module defines the following :prop_tgt:`IMPORTED` targets: ``Libev::Libev`` The Libev library, if found. Result variables ^^^^^^^^^^^^^^^^ This module will set the following variables in your project: ``Libev_FOUND`` If false, do not try to use Libev. ``LIBEV_INCLUDE_DIR`` where to find libev headers. ``LIBEV_LIBRARIES`` the libraries needed to use Libev. ``LIBEV_VERSION`` the version of the Libev library found #]=======================================================================] find_path(LIBEV_INCLUDE_DIR ev.h HINTS "${LIBEV_DIR}" "${LIBEV_DIR}/include" ) find_library(LIBEV_LIBRARY NAMES ev libev HINTS "${LIBEV_DIR}" "${LIBEV_DIR}/lib" ) set(LIBEV_LIBRARIES "") if (LIBEV_INCLUDE_DIR AND LIBEV_LIBRARY) if (NOT TARGET Libev::Libev) add_library(Libev::Libev UNKNOWN IMPORTED) set_target_properties(Libev::Libev PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${LIBEV_INCLUDE_DIR}" IMPORTED_LINK_INTERFACE_LANGUAGES "C" IMPORTED_LOCATION "${LIBEV_LIBRARY}" ) endif () endif() list(APPEND LIBEV_LIBRARIES "${LIBEV_LIBRARY}") include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Libev REQUIRED_VARS LIBEV_LIBRARIES LIBEV_INCLUDE_DIR ) mark_as_advanced(LIBEV_INCLUDE_DIR LIBEV_LIBRARIES LIBEV_LIBRARY) getdns-1.6.0/cmake/modules/FindLibevent2.cmake000066400000000000000000000040321362622307100211700ustar00rootroot00000000000000#[=======================================================================[.rst: FindLibevent2 ------------- Find the Libevent2 library. For now this finds the core library only. Imported targets ^^^^^^^^^^^^^^^^ This module defines the following :prop_tgt:`IMPORTED` targets: ``Libevent2::Libevent_core`` The Libevent2 library, if found. Result variables ^^^^^^^^^^^^^^^^ This module will set the following variables in your project: ``Libevent2_FOUND`` If false, do not try to use Libevent2. ``LIBEVENT2_INCLUDE_DIR`` where to find libevent headers. ``LIBEVENT2_LIBRARIES`` the libraries needed to use Libevent2. ``LIBEVENT2_VERSION`` the version of the Libevent2 library found #]=======================================================================] find_path(LIBEVENT2_INCLUDE_DIR event2/event.h HINTS "${LIBEVENT2_DIR}" "${LIBEVENT2_DIR}/include" ) find_library(LIBEVENT2_LIBRARY NAMES event_core libevent_core HINTS "${LIBEVENT2_DIR}" "${LIBEVENT2_DIR}/lib" ) set(LIBEVENT2_LIBRARIES "") if (LIBEVENT2_INCLUDE_DIR AND LIBEVENT2_LIBRARY) if (NOT TARGET Libevent2::Libevent_core) add_library(Libevent2::Libevent_core UNKNOWN IMPORTED) set_target_properties(Libevent2::Libevent_core PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${LIBEVENT2_INCLUDE_DIR}" IMPORTED_LINK_INTERFACE_LANGUAGES "C" IMPORTED_LOCATION "${LIBEVENT2_LIBRARY}" ) endif () if (NOT LIBEVENT2_VERSION AND LIBEVENT2_INCLUDE_DIR AND EXISTS "${LIBEVENT2_INCLUDE_DIR}/event2/event.h") file(STRINGS "${LIBEVENT2_INCLUDE_DIR}/event2/event-config.h" LIBEVENT2_H REGEX "^#define _?EVENT_+VERSION ") string(REGEX REPLACE "^.*EVENT_+VERSION \"([^\"]+)\".*$" "\\1" LIBEVENT2_VERSION "${LIBEVENT2_H}") endif () endif() list(APPEND LIBEVENT2_LIBRARIES "${LIBEVENT2_LIBRARY}") include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Libevent2 REQUIRED_VARS LIBEVENT2_LIBRARIES LIBEVENT2_INCLUDE_DIR VERSION_VAR LIBEVENT2_VERSION ) mark_as_advanced(LIBEVENT2_INCLUDE_DIR LIBEVENT2_LIBRARIES LIBEVENT2_LIBRARY) getdns-1.6.0/cmake/modules/FindLibidn2.cmake000066400000000000000000000035251362622307100206270ustar00rootroot00000000000000#[=======================================================================[.rst: FindLibidn2 ----------- Find the Libidn2 library Imported targets ^^^^^^^^^^^^^^^^ This module defines the following :prop_tgt:`IMPORTED` targets: ``Libidn2::Libidn2`` The Libidn2 library, if found. Result variables ^^^^^^^^^^^^^^^^ This module will set the following variables in your project: ``Libidn2_FOUND`` If false, do not try to use Libidn2. ``LIBIDN2_INCLUDE_DIR`` where to find libidn2 headers. ``LIBIDN2_LIBRARIES`` the libraries needed to use Libidn2. ``LIBIDN2_VERSION`` the version of the Libidn2 library found #]=======================================================================] find_path(LIBIDN2_INCLUDE_DIR idn2.h HINTS "${LIBIDN2_DIR}" "${LIBIDN2_DIR}/include" ) find_library(LIBIDN2_LIBRARY NAMES idn2 libidn2 HINTS "${LIBIDN2_DIR}" "${LIBIDN2_DIR}/lib" ) set(LIBIDN2_LIBRARIES "") if (LIBIDN2_INCLUDE_DIR AND LIBIDN2_LIBRARY) if (NOT TARGET Libidn2::Libidn2) add_library(Libidn2::Libidn2 UNKNOWN IMPORTED) set_target_properties(Libidn2::Libidn2 PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${LIBIDN2_INCLUDE_DIR}" IMPORTED_LINK_INTERFACE_LANGUAGES "C" IMPORTED_LOCATION "${LIBIDN2_LIBRARY}" ) endif () if (NOT LIBIDN2_VERSION AND LIBIDN2_INCLUDE_DIR AND EXISTS "${LIBIDN2_INCLUDE_DIR}/unbound.h") file(STRINGS "${LIBIDN2_INCLUDE_DIR}/idn2.h" LIBIDN2_H REGEX "^#define IDN2_VERSION ") string(REGEX REPLACE "^.*IDN2_VERSION \"([0-9.]+)\".*$" "\\1" LIBIDN2_VERSION "${LIBIDN2_H}") endif () endif() list(APPEND LIBIDN2_LIBRARIES "${LIBIDN2_LIBRARY}") include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Libidn2 REQUIRED_VARS LIBIDN2_LIBRARIES LIBIDN2_INCLUDE_DIR VERSION_VAR LIBIDN2_VERSION ) mark_as_advanced(LIBIDN2_INCLUDE_DIR LIBIDN2_LIBRARIES LIBIDN2_LIBRARY) getdns-1.6.0/cmake/modules/FindLibunbound.cmake000066400000000000000000000053171362622307100214460ustar00rootroot00000000000000#[=======================================================================[.rst: FindLibunbound -------------- Find the Libunbound library Imported targets ^^^^^^^^^^^^^^^^ This module defines the following :prop_tgt:`IMPORTED` targets: ``Libunbound::Libunbound`` The Libunbound library, if found. Result variables ^^^^^^^^^^^^^^^^ This module will set the following variables in your project: ``Libunbound_FOUND`` If false, do not try to use Libunbound. ``LIBUNBOUND_INCLUDE_DIR`` where to find libunbound headers. ``LIBUNBOUND_LIBRARIES`` the libraries needed to use Libunbound. ``LIBUNBOUND_VERSION`` the version of the Libunbound library found #]=======================================================================] find_path(LIBUNBOUND_INCLUDE_DIR unbound.h HINTS "${LIBUNBOUND_DIR}" "${LIBUNBOUND_DIR}/include" ) find_library(LIBUNBOUND_LIBRARY NAMES unbound HINTS "${LIBUNBOUND_DIR}" "${LIBUNBOUND_DIR}/lib" ) set(LIBUNBOUND_LIBRARIES "") if (UNIX) find_package(Threads REQUIRED) find_package(OpenSSL REQUIRED) list(APPEND LIBUNBOUND_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}") list(APPEND LIBUNBOUND_LIBRARIES "${OPENSSL_LIBRARIES}") endif() if (LIBUNBOUND_INCLUDE_DIR AND LIBUNBOUND_LIBRARY) if (NOT TARGET Libunbound::Libunbound) add_library(Libunbound::Libunbound UNKNOWN IMPORTED) set_target_properties(Libunbound::Libunbound PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${LIBUNBOUND_INCLUDE_DIR}" IMPORTED_LINK_INTERFACE_LANGUAGES "C" IMPORTED_LOCATION "${LIBUNBOUND_LIBRARY}" ) if(UNIX AND TARGET Threads::Threads) set_property(TARGET Libunbound::Libunbound APPEND PROPERTY INTERFACE_LINK_LIBRARIES Threads::Threads) endif () if(UNIX AND TARGET OpenSSL::SSL) set_property(TARGET Libunbound::Libunbound APPEND PROPERTY INTERFACE_LINK_LIBRARIES OpenSSL::SSL) endif () if(UNIX AND TARGET OpenSSL::Crypto) set_property(TARGET Libunbound::Libunbound APPEND PROPERTY INTERFACE_LINK_LIBRARIES OpenSSL::Crypto) endif () endif () if (NOT LIBUNBOUND_VERSION AND LIBUNBOUND_INCLUDE_DIR AND EXISTS "${LIBUNBOUND_INCLUDE_DIR}/unbound.h") file(STRINGS "${LIBUNBOUND_INCLUDE_DIR}/unbound.h" LIBUNBOUND_H REGEX "^#define UNBOUND_VERSION_M[A-Z]+") string(REGEX REPLACE "^.*MAJOR ([0-9]+).*MINOR ([0-9]+).*MICRO ([0-9]+).*$" "\\1.\\2.\\3" LIBUNBOUND_VERSION "${LIBUNBOUND_H}") endif () endif() list(APPEND LIBUNBOUND_LIBRARIES "${LIBUNBOUND_LIBRARY}") include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Libunbound REQUIRED_VARS LIBUNBOUND_LIBRARIES LIBUNBOUND_INCLUDE_DIR VERSION_VAR LIBUNBOUND_VERSION ) mark_as_advanced(LIBUNBOUND_INCLUDE_DIR LIBUNBOUND_LIBRARIES LIBUNBOUND_LIBRARY) getdns-1.6.0/cmake/modules/FindLibuv.cmake000066400000000000000000000037651362622307100204330ustar00rootroot00000000000000#[=======================================================================[.rst: FindLibuv --------- Find the Libuv library. Imported targets ^^^^^^^^^^^^^^^^ This module defines the following :prop_tgt:`IMPORTED` targets: ``Libuv::Libuv`` The Libuv library, if found. Result variables ^^^^^^^^^^^^^^^^ This module will set the following variables in your project: ``Libuv_FOUND`` If false, do not try to use Libuv. ``LIBUV_INCLUDE_DIR`` where to find libuv headers. ``LIBUV_LIBRARIES`` the libraries needed to use Libuv. ``LIBUV_VERSION`` the version of the Libuv library found #]=======================================================================] find_path(LIBUV_INCLUDE_DIR uv.h HINTS "${LIBUV_DIR}" "${LIBUV_DIR}/include" ) find_library(LIBUV_LIBRARY NAMES uv libuv HINTS "${LIBUV_DIR}" "${LIBUV_DIR}/lib" ) set(LIBUV_LIBRARIES "") if (LIBUV_INCLUDE_DIR AND LIBUV_LIBRARY) if (NOT TARGET Libuv::Libuv) add_library(Libuv::Libuv UNKNOWN IMPORTED) set_target_properties(Libuv::Libuv PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${LIBUV_INCLUDE_DIR}" IMPORTED_LINK_INTERFACE_LANGUAGES "C" IMPORTED_LOCATION "${LIBUV_LIBRARY}" ) endif () if (NOT LIBUV_VERSION AND LIBUV_INCLUDE_DIR) if (EXISTS "${LIBUV_INCLUDE_DIR}/uv-version.h") file(STRINGS "${LIBUV_INCLUDE_DIR}/uv-version.h" LIBUV_VER_H REGEX "^#define UV_VERSION_(MAJOR|MINOR|PATCH) ") elseif (EXISTS "${LIBUV_INCLUDE_DIR}/uv/version.h") file(STRINGS "${LIBUV_INCLUDE_DIR}/uv/version.h" LIBUV_VER_H REGEX "^#define UV_VERSION_(MAJOR|MINOR|PATCH) ") endif () string(REGEX REPLACE "^.*_MAJOR ([0-9]+).*_MINOR ([0-9]+).*_PATCH ([0-9]+).*$" "\\1.\\2.\\3" LIBUV_VERSION "${LIBUV_VER_H}") endif () endif() list(APPEND LIBUV_LIBRARIES "${LIBUV_LIBRARY}") include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Libuv REQUIRED_VARS LIBUV_LIBRARIES LIBUV_INCLUDE_DIR VERSION_VAR LIBUV_VERSION ) mark_as_advanced(LIBUV_INCLUDE_DIR LIBUV_LIBRARIES LIBUV_LIBRARY) getdns-1.6.0/cmake/modules/FindNettle.cmake000066400000000000000000000050541362622307100205760ustar00rootroot00000000000000#[=======================================================================[.rst: FindNettle ---------- Find the Nettle library. Imported targets ^^^^^^^^^^^^^^^^ This module defines the following :prop_tgt:`IMPORTED` targets: ``Nettle::Nettle`` The Nettle library, if found. ``Nettle::Hogweed`` The Hogweed library, if found. Result variables ^^^^^^^^^^^^^^^^ This module will set the following variables in your project: ``Nettle_FOUND`` If false, do not try to use Nettle. ``NETTLE_INCLUDE_DIR`` where to find Nettle headers. ``NETTLE_LIBRARIES`` the libraries needed to use Nettle. ``NETTLE_VERSION`` the version of the Nettle library found #]=======================================================================] find_path(NETTLE_INCLUDE_DIR nettle/version.h HINTS "${NETTLE_DIR}" "${NETTLE_DIR}/include" ) find_library(NETTLE_LIBRARY NAMES nettle libnettle HINTS "${NETTLE_DIR}" "${NETTLE_DIR}/lib" ) find_library(HOGWEED_LIBRARY NAMES hogweed libhogweed HINTS "${NETTLE_DIR}" "${NETTLE_DIR}/lib" ) set(NETTLE_LIBRARIES "") # May need gmp library on Unix. if (UNIX) find_library(NETTLE_GMP_LIBRARY gmp) if (NETTLE_GMP_LIBRARY) list(APPEND NETTLE_LIBRARIES "${NETTLE_GMP_LIBRARY}") endif () endif () if (NETTLE_INCLUDE_DIR AND NETTLE_LIBRARY AND HOGWEED_LIBRARY) if (NOT TARGET Nettle::Nettle) add_library(Nettle::Nettle UNKNOWN IMPORTED) set_target_properties(Nettle::Nettle PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${NETTLE_INCLUDE_DIR}" INTERFACE_LINK_LIBRARIES "${NETTLE_LIBRARIES}" IMPORTED_LINK_INTERFACE_LANGUAGES "C" IMPORTED_LOCATION "${NETTLE_LIBRARY}" ) endif () if (NOT TARGET Nettle::Hogweed) add_library(Nettle::Hogweed UNKNOWN IMPORTED) set_target_properties(Nettle::Hogweed PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${NETTLE_INCLUDE_DIR}" IMPORTED_LINK_INTERFACE_LANGUAGES "C" IMPORTED_LOCATION "${HOGWEED_LIBRARY}" ) endif () if (NOT NETTLE_VERSION AND NETTLE_INCLUDE_DIR) file(STRINGS "${NETTLE_INCLUDE_DIR}/nettle/version.h" NETTLE_VER_H REGEX "^#define NETTLE_VERSION_(MAJOR|MINOR) ") string(REGEX REPLACE "^.*_MAJOR ([0-9]+).*_MINOR ([0-9]+).*$" "\\1.\\2" NETTLE_VERSION "${NETTLE_VER_H}") endif () endif() list(APPEND NETTLE_LIBRARIES "${NETTLE_LIBRARY}" "${HOGWEED_LIBRARY}") include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Nettle REQUIRED_VARS NETTLE_LIBRARIES NETTLE_INCLUDE_DIR VERSION_VAR NETTLE_VERSION ) mark_as_advanced(NETTLE_INCLUDE_DIR NETTLE_LIBRARIES NETTLE_LIBRARY HOGWEED_LIBRARY) getdns-1.6.0/cmake/modules/TargetSharedLibraryExports.cmake000066400000000000000000000024631362622307100240320ustar00rootroot00000000000000# Export only named entry points from shared library. function(target_shared_library_exports lib libname symbols) if (WIN32) file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/${libname}.def" "LIBRARY ${libname}\n EXPORTS\n") foreach (symbol IN LISTS symbols) file(APPEND "${CMAKE_CURRENT_BINARY_DIR}/${libname}.def" " ${symbol}\n") endforeach () target_sources(${lib} PRIVATE "${CMAKE_CURRENT_BINARY_DIR}/${libname}.def") elseif (APPLE) file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/${libname}.syms" "") foreach (symbol IN LISTS symbols) file(APPEND "${CMAKE_CURRENT_BINARY_DIR}/${libname}.syms" "_${symbol}\n") endforeach () target_sources(${lib} PRIVATE "${CMAKE_CURRENT_BINARY_DIR}/${libname}.syms") target_link_libraries(${lib} PRIVATE "-exported_symbols_list ${libname}.syms") elseif (UNIX) # Assume GNU ld. file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/${libname}.ver" "{ global:\n") foreach (symbol IN LISTS symbols) file(APPEND "${CMAKE_CURRENT_BINARY_DIR}/${libname}.ver" " ${symbol};\n") endforeach () file(APPEND "${CMAKE_CURRENT_BINARY_DIR}/${libname}.ver" "local:\n *;\n};\n") target_link_libraries(${lib} PRIVATE "-Wl,--version-script=getdns.ver") else () message(WARNING "Unknown platform, ${lib} exports not set.") endif () endfunction () getdns-1.6.0/cmake/modules/TargetSharedLibraryVersion.cmake000066400000000000000000000026031362622307100240070ustar00rootroot00000000000000# Add version to given shared library linkage. function(target_shared_library_version lib version_current version_revision version_age) if (APPLE) # Follow libtool. Add one to major version, as version 0 doesn't work. # But tag dynlib name with current-age. math(EXPR major_version "${version_current}+1") math(EXPR dynlib_version "${version_current}-${version_age}") set_target_properties(${lib} PROPERTIES VERSION "${dynlib_version}") target_link_libraries(${lib} PRIVATE "-compatibility_version ${major_version}") target_link_libraries(${lib} PRIVATE "-current_version ${major_version}.${version_revision}") elseif (UNIX OR MINGW OR MSYS OR CYGWIN) # Assume GNU ld, and again follow libtool. Major version is current-age. math(EXPR compat_version "${version_current}-${version_age}") set_target_properties(${lib} PROPERTIES VERSION "${compat_version}.${version_age}.${version_revision}" SOVERSION "${compat_version}") elseif (WIN32) set(rc_template "${CMAKE_CURRENT_SOURCE_DIR}/cmake/include/${lib}_version.rc.in") if (EXISTS ${rc_template}) configure_file(${rc_template} ${lib}.rc @ONLY) target_sources(${lib} PRIVATE ${lib}.rc) endif () target_link_libraries(${lib} PRIVATE "-VERSION:${version_current}.${version_revision}") else () message(WARNING "Unknown platform, ${lib} will not be versioned.") endif () endfunction () getdns-1.6.0/cmake/tests/000077500000000000000000000000001362622307100152265ustar00rootroot00000000000000getdns-1.6.0/cmake/tests/test___func__.c000066400000000000000000000000671362622307100201630ustar00rootroot00000000000000int main (int ac, char *av[]) { char *s = __func__; } getdns-1.6.0/cmake/tests/test_poll.c000066400000000000000000000002461362622307100174010ustar00rootroot00000000000000#ifdef HAVE_SYS_POLL_H #include #else #include #endif int main (int ac, char *av[]) { int rc; rc = poll((struct pollfd *)(0), 0, 0); } getdns-1.6.0/cmake/tests/test_uv_cb.c000066400000000000000000000002271362622307100175300ustar00rootroot00000000000000#include void test_cb(uv_timer_t *handle) { (void) handle; } int main(int ac, char *av[]) { uv_timer_cb cb = test_cb; (*cb)(0); } getdns-1.6.0/doc/000077500000000000000000000000001362622307100135515ustar00rootroot00000000000000getdns-1.6.0/doc/getdns_address.3.in000066400000000000000000000127421362622307100172410ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_address 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_address, .B getdns_address_sync -- get ip address(es) for a name .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_address (getdns_context *context, .RS 3 const char *name, .br getdns_dict *extensions, .br void *userarg, .br getdns_transaction_t *transaction_id, .br getdns_callback_t callbackfn) .RE getdns_return_t .br .B getdns_address_sync (getdns_context *context, .RS 3 const char *name, .br getdns_dict *extensions, .br getdns_dict **response) .RE .SH DESCRIPTION .LP The getdns_address(3) and getdns_address_sync functions provide public entry points into the getdns API library to retrieve the address given a host name. They always returns both IPv4 and IPv6 addresses. This function will use all of the namespaces from the context (to better emulate getaddrinfo (3)). .HP 3 .I context A pointer to the previously created DNS context that is to be used with this DNS request. see getdns_context (3) .HP 3 .I name the host name to resolve to an address (note that an IP address is considered invalid) .HP 3 .I extensions extensions for this request, NULL if no extensions, see libgetdns (3) for a detailed description of extensions .HP 3 .I userarg returned to the callback function untouched, can be NULL .HP 3 .I transaction_id populated by the API and used to identify the callback (for example to getdns_cancel_callback), can be NULL, set to 0 if the function fails .HP 3 .I callbackfn non-NULL pointer to a callback function defined by the application, typically used to process the response. Only the asynchronous signature accepts a callback function, the synchronous signature does not include a callback. See libgetdns (3) for a more detailed discussion of callback functions. .HP 3 .I response A getdns_dict type is returned in response and always contains at least three names: replies_full (a list containing the DNS response as binary data), replies_tree (a list containing the parsed DNS response data) and status (an int). The storage associated with this must be freed by a call to getdns_free_sync_request_memory (3). .HP .SH "RETURN VALUES" Upon successful completion the functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid or the context has internal deficiencies .LP .B GETDNS_RETURN_BAD_DOMAIN_NAME if the domain name passed to the function is invalid .LP .B GETDNS_RETURN_EXTENSION_MISFORMAT if the data type specified in one or more of the extensions does not match the specifications .LP .B GETDNS_RETURN_GENERIC_ERROR if some problem was encountered in the function not addressed by one of the more specific return codes .LP .B GETDNS_RETURN_INVALID PARAMETER if one or more parameters has an invalid value .LP .B GETDNS_RETURN_MEMORY_ERROR if unable to allocate the memory required .LP .B GETDNS_RETURN_NO_SUCH_EXTENSION if one or more of the strings specified in the extensions are not valid The values of status included in the response parameter are: .LP .B GETDNS_RESPSTATUS_GOOD if at least one response was returned .LP .B GETDNS_RESPSTATUS_NO_NAME if queries for the name yielded all negative responses .LP .B GETDNS_RESPSTATUS_ALL_TIMEOUT if all queries for the name timed out .LP .B GETDNS_RESPSTATUS_NO_SECURE_ANSWERS if only secure replies accepted (per context) and at least one response was received but no DNS responses were secure through DNSSEC .LP For a more detailed explanation of the response object see .I libgetdns (3) .SH EXAMPLES TBD .SH FILES .br /etc/hosts .br /etc/resolv.conf .SH SEE ALSO .BR libgetdns (3), .BR getdns_context (3), .BR getdns_free_sync_request_memory (3), .BR getdns_general (3), .BR getdns_general_sync (3), .BR getdns_hostname (3), .BR getdns_hostname_sync (3), .BR getdns_service (3), .BR getdns_service_sync (3) getdns-1.6.0/doc/getdns_cancel_callback.3.in000066400000000000000000000062161362622307100206540ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_cancel_callback 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_cancel_callback -- cancel an outstanding asyn getdns request .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_cancel_callback (getdns_context_t context, .RS 3 .br getdns_transaction_t *transaction_id) .RE .SH DESCRIPTION .LP To cancel an outstanding callback, use getdns_cancel_callback. This causes the API to call the callback with a callback_type of GETDNS_CALLBACK_CANCEL if the callback for this transaction_id has not already been called. The callback code for cancellation should clean up any memory related to the identified call, such as to deallocate the memory for the userarg. getdns_cancel_callback() may return immediately, even before the callback finishes its work and returns. .HP 3 .I context see getdns_context (3) .HP 3 .I transaction_id populated by the API and used to identify the callback (for example to getdns_cancel_callback), can be NULL, set to 0 if the function fails .HP .SH "RETURN VALUES" Upon successful completion the functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_INVALID_PARAMETER if context == NULL .LP .B GETDNS_RETURN_UNKNOWN_TRANSACTION if the transaction_id that is unknown or belongs to a callback that has already been called .SH EXAMPLES TBD .SH FILES .br /etc/hosts .br /etc/resolv.conf .SH SEE ALSO .BR libgetdns (3), .BR getdns_context (3), .BR getdns_general (3), .BR getdns_hostname (3), .BR getdns_service (3), getdns-1.6.0/doc/getdns_context.3.in000066400000000000000000000223101362622307100172700ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_context 3 "@date@" "getdns @version@" getdns .ad l .SH NAME .B getdns_context, .B getdns_context_create, .B getdns_context_create_with_memory_functions, .B getdns_context_create_with_extended_memory_functions, .B getdns_context_destroy, .B getdns_context_get_api_information -- getdns context create and destroy routines .ad n .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_context_create (getdns_context ** context, .RS 3 .br int set_from_os) .RE getdns_return_t .br .B getdns_context_create_with_memory_functions (getdns_context ** context, .RS 3 .br int set_from_os, .br void *(*malloc) (size_t), .br void *(*realloc) (void *, size_t), .br void (*free) (void *)) .RE getdns_return_t .br .B getdns_context_create_with_extended_memory_functions (getdns_context **context, .RS 3 .br int set_from_os, .br void *userarg, .br void *(*malloc) (void *userarg, size_t), .br void *(*realloc) (void *userarg, void *, size_t), .br void (*free) (void *userarg, void *)) .RE void .br .B getdns_context_destroy (getdns_context *context) getdns_dict * .br .B getdns_context_get_api_information (getdns_context *context) .SH DESCRIPTION .LP Calls to getdns functions require a DNS context, which is a group of API settings that affect how DNS calls are made. For most applications, a default context is sufficient. .LP To create a new DNS context, use the function: .RS 3 .br getdns_return_t .B getdns_context_create (getdns_context_t *context, bool set_from_os) .RE .LP The call to getdns_context_create immediately returns a context that can be used with other API calls; that context contains the API's default values. Most applications will want set_from_os set to true. .LP To clean up the context, including cleaning up all outstanding transactions that were called using this context, use the function: .RS 3 .br void .B getdns_context_destroy (getdns_context_t context) .RE .LP When getdns_context_destroy() returns, the application knows that all outstanding transactions associated with this context will have been called; callbacks that had not been called before getdns_context_destroy() was called will be called with a callback_type of GETDNS_CALLBACK_CANCEL. getdns_context_destroy() returns after all of the needed cleanup is done and callbacks are made. .LP If you are using getdns in a multi-threaded manner, you are then of course using the underlying OpenSSL library multi-threaded and the version of that library in use might have a requirements on this issue. You may need to provide one or two functions to allow it to function properly. For example before you call getdns_context_create() you may need to use the openssl functions CRYPTO_set_id_callback and CRYPTO_set_locking_callback to set up asynchronous operation (the application calls these functions once for initialisation). Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function. .HP 3 .I context Used to return the pointer to an opaque structure. The caller passes the address of a pointer (decl: getdns_context *context; passed as &context) which will be populated as a result of returning from the function. The result is a newly allocated and initialized context (if there are no errors). In the getdns_destroy_context function this is the context whose associated memory will be released. .HP 3 .I set_from_os If set_from_os is 0 then the caller must provide forwarding name servers if running in stub mode. If set_from_os is 1 then the system files are used to initialize the context. /etc/resolv.conf is used to populate forwarders when running as a stub resolver (only "nameserver" lines are recognized). If set_from_os is 1 /etc/hosts entries are preferred before resorting to a DNS query. Errors in the system files will not prevent the context form being constructed. .HP 3 .I userarg In the extended use case this argument is passed unchanged to each of the memory management functions each time they are called. .HP 3 .I malloc The function that will be used for creating response dicts (and the members within the response dicts). By default the system malloc is used. .HP 3 .I realloc The function that will be used for creating response dicts (and the members within the response dicts). By default the system realloc is used. .HP 3 .I free The function that will be used for releasing storage for response dicts (and the members within the response dicts). By default the system free is used. .SH DESCRIPTION (LONG) .LP Many calls in the DNS API require a DNS context. A DNS context contains the information that the API needs in order to process DNS calls, such as the locations of upstream DNS servers, DNSSEC trust anchors, and so on. The internal structure of the DNS context is opaque, and might be different on each OS. When a context is passed to any function, it must be an allocated context; the context must not be NULL. .LP A typical application using this API doesn't need to know anything about contexts. Basically, the application creates a default context, uses it in the functions that require a context, and then deallocates it when done. Context manipulation is available for more DNS-aware programs, but is unlikely to be of interest to applications that just want the results of lookups for A, AAAA, SRV, and PTR records. .LP It is expected that contexts in implementations of the API will not necessarily be thread-safe, but they will not be thread-hostile. A context should not be used by multiple threads: create a new context for use on a different thread. It is just fine for an application to have many contexts, and some DNS-heavy applications will certainly want to have many even if the application uses a single thread. .LP When the context is used in the API for the first time and set_from_os is 1, the API starts replacing some of the values with values from the OS, such as those that would be found in res_query(3), /etc/resolv.conf, and so on, then proceeds with the new function. Some advanced users will not want the API to change the values to the OS's defaults; if set_from_os is 0, the API will not do any updates to the initial values based on changes in the OS. For example, this might be useful if the API is acting as a stub resolver that is using a specific upstream recursive resolver chosen by the application, not the one that might come back from DHCP. .HP .SH "RETURN VALUES" Upon successful completion each of these functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_GENERIC_ERROR memory allocation failed or some other untoward thing happened while initializing the context .LP .B GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid (getdns_context_destroy) .LP The getdns_dict returned by getdns_context_get_api_information must be destroyed by the called and includes the following name/value pairs: .IP version_string a bindata containing a printable string of the version of the DNS API implemented by this library .IP implementation_string a bindata containing a printable string set by the implementation .IP resolution_type an int equal to GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB .IP all_context a getdns_dict with names for all the types of context, feed it to getdns_pretty_print_dict (3) for something easily readable .SH EXAMPLES TBD .SH FILES .br /etc/hosts .br /etc/resolv.conf .SH SEE ALSO .BR libgetdns (3), .BR getdns_address (3), .BR getdns_address_sync (3), .BR getdns_context_set (3), .BR getdns_context_set_context_update_callback (3), .BR getdns_general (3), .BR getdns_general_sync (3), .BR getdns_hostname (3), .BR getdns_hostname_sync (3), .BR getdns_service (3), .BR getdns_service_sync (3). getdns-1.6.0/doc/getdns_context_set.3.in000066400000000000000000000240241362622307100201470ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_context_set 3 "@date@" "getdns @version@" getdns .ad l .SH NAME .B getdns_context_set_append_name, .B getdns_context_set_context_update_callback, .B getdns_context_set_dns_root_servers, .B getdns_context_set_dns_transport, .B getdns_context_set_dnssec_trust_anchors, .B getdns_context_set_dnssec_allowed_skew, .B getdns_context_set_follow_redirects, .B getdns_context_set_limit_outstanding_queries, .B getdns_context_set_namespaces, .B getdns_context_set_resolution_type, .B getdns_context_set_suffix, .B getdns_context_set_timeout, -- getdns context manipulation routines .ad n .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_context_set_append_name (getdns_context_t context, .RS 3 .br getdns_append_name_t when_to_append) .RE getdns_return_t .br .B getdns_context_set_context_update_callback (getdns_context_t context, .RS 3 .br (*callback)(struct getdns_context *context, uint16_t changed_item)) .RE getdns_return_t .br .B getdns_context_set_dns_root_servers (getdns_context_t context, .RS 3 .br getdns_list *root_addresses) .RE getdns_return_t .br .B getdns_context_set_dns_transport (getdns_context_t context, .RS 3 .br uint16_t transport) .RE getdns_return_t .br .B getdns_contet_set_dnssec_allowed_skew (getdns_context *context, .RS 3 uint32_t skew_seconds) .RE getdns_return_t .br .B getdns_contet_set_dnssec_trust_anchors (getdns_context *context, .RS 3 getdns_list *trust_anchors) .RE getdns_return_t .br .B getdns_context_set_follow_redirects (getdns_context_t context, .RS 3 .br getdns_redirects_t followredir) .RE getdns_return_t .br .B getdns_context_set_limit_outstanding_queries (getdns_context_t context, .RS 3 .br uint16_t limit) .RE getdns_return_t .br .B getdns_context_set_namespaces (getdns_context_t context, .RS 3 .br size_t namespace_count, .br uint16_t *namespaces) .RE getdns_return_t .br .B getdns_context_set_resolution_type (getdns_context_t context, .RS 3 uint16_t restype) .RE getdns_return_t .br .B getdns_context_set_suffix (getdns_context *context, .RS 3 getdns_list *suffixes) .RE getdns_return_t .br .B getdns_context_set_timeout (getdns_context_t context, .RS 3 uint16_t timeout) .RE .SH DESCRIPTION .LP These functions are used to manipulate a previously allocated and initialized context, see getdns_context (3) for more details on the functions used to allocate, initialized and destroy contexts and for a more detailed discussion of the getdns_context in general. .LP .B getdns_context_set_append_name Specifies whether to append a suffix supplied via getdns_context_set_suffix (3) to the query string before the API starts resolving a name. .LP .B getdns_context_set_context_update_callback sets a function that will be called if changes to the system files (for example /etc/resolv.conf and /etc/hosts). .LP .B getdns_context_set_dns_transport specifies the transport used for DNS lookups, the default is to use UDP and fall back to TCP as needed. .LP .B getdns_context_set_dnssec_trust_anchors allows the caller to specify trust anchors as alternatives to the default trust anchors .LP .B getdns_context_set_dnssec_allowed_skew set the number of seconds skew allowed in either direction when checking an RRSIGs expiration and inception fields, the default is 0. .LP .B getdns_context_set_limit_outstanding_queries specifies the maximum number of outstanding DNS queries, the API will queue queries over this limit until current queries are answers and will then automatically issue the queries on the queue. .LP .B getdns_context_set_dns_root_servers provides an alternate set of addresses to use to look up the top level domains. The default (if this function is not called) is the list of IANA root servers (think of this as the root hints). .LP .B getdns_context_set_follow_redirects specifies whether or not DNS queries follow redirects (CNAME and DNAME), the default behavior is to follow redirects and return the eventual target. .LP .B getdns_context_set_namespaces sets the namespaces to be used by the resolver, the default is DNS and then local files. Future implementations will support netbios, mdns, and nis. .LP .B getdns_context_set_resolution_type specifies whether DNS queries are performed with non-recursive lookups or as a stub resolver. .LP .B getdns_context_set_suffix Append suffixes to domain names prior to executing the lookup based on getdns_context_set_append_name. .LP .B getdns_context_set_timeout specifies the number of milliseconds the API will wait for a response. .HP 3 .I context a previously allocated and initialized getdns_context .HP 3 .I callback a callback function that will be called when changes are made to the system files (/etc/resolv.conf and /etc/hosts) for contexts created with set_from_os = 1. When this function is called the changed_item parameter indicates which item in the context has changed. .HP 3 .I root_addresses This is a list of getdns_dict types that each identify a single root server to use to look up top level domains. Each dictionary includes two names, .I address_type , a bindata containing the string "IPv4" or "IPv6" and .I address_data a bindata containing the IP address. .HP 3 .I transport may be one of GETDNS_CONTEXT_UDP_FIRST_AND_FALL_BACK_TO_TCP, GETDNS_CONTEXT_UDP_ONLY, GETDNS_CONTEXT_TCP_ONLY, GETDNS_CONTEXT_TCP_ONLY_KEEP_CONNECTIONS_OPEN. If you need more information on what each of these means reread the mnemonic and take a guess ;) .HP 3 .I followredir If set to GETDNS_REDIRECTS_FOLLOW (the default) then the eventual target of the redirect is returned. If set to GETDNS_REDIRECTS_DO_NOT_FOLLOW then the CNAME or DNAME is returned and NOT the eventual target. .HP 3 .I limit the maximum number of concurrent outstanding (unanswered) DNS queries, if exceeded the API will queue queries and issue them as the number of outstanding queries drops. A value of 0 indicates that there is no limit. .ad l .HP 3 .I namespaces The namespaces array contains an ordered list of namespaces that will be queried. Important: this context setting is ignored for the getdns_general and getdns_general_sync functions; it is used for the other functions. The values are GETDNS_CONTEXT_NAMESPACE_DNS, GETDNS_CONTEXT_NAMESPACE_LOCALNAMES, GETDNS_CONTEXT_NAMESPACE_NETBIOS, GETDNS_CONTEXT_NAMESPACE_MDNS, and GETDNS_CONTEXT_NAMESPACE_NIS. When a normal lookup is done, the API does the lookups in the order given and stops when it gets the first result; a different method with the same result would be to run the queries in parallel and return when it gets the first result. Because lookups might be done over different mechanisms because of the different namespaces, there can be information leakage that is similar to that seen with getaddrinfo(). The default is determined by the OS. .ad n .HP 3 .I restype can be set to either GETDNS_CONTEXT_RECURSIVE (the default) or GETDNS_CONTEXT_STUB (requires that forwarders be specified by the caller). .HP 3 .I seconds_skew the number of seconds skew allowed in either direction when checking an RRSIGs expiration and inception fields. .HP 3 .I suffixes A list of bindatas that are strings that are to be appended based on getdns_context_set_append_name. The values here follow the rules in section 2.1 of RFC 4343 to allow non-ASCII octets and special characters in labels. .HP 3 .I timeout the number of milliseconds the API will wait for a response, after which the callback will be invoked (or the synchronous function will return) with a timeout error. .HP 3 .I trust_anchors list of bindatas that are the DNSSEC trust anchors expressed as RDATA from the DNSKEY resource records, the default are supplied by the IANA root. .HP 3 .I when_to_append The value is .RS .IP \(bu 3 GETDNS_APPEND_NAME_ALWAYS, .IP \(bu 3 GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE, .IP \(bu 3 GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE, or .IP \(bu 3 GETDNS_APPEND_NAME_NEVER. .RE .HP .SH "RETURN VALUES" Upon successful completion the functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid .LP .B GETDNS_RETURN_CONTEXT_UPDATE_FAIL if there was a problem updating the context .SH EXAMPLES TBD .SH FILES .br /etc/hosts .br /etc/resolv.conf .SH SEE ALSO .BR libgetdns (3), .BR getdns_address (3), .BR getdns_address_sync (3), .BR getdns_context (3), .BR getdns_general (3), .BR getdns_general_sync (3), .BR getdns_hostname (3), .BR getdns_hostname_sync (3), .BR getdns_service (3), .BR getdns_service_sync (3). getdns-1.6.0/doc/getdns_context_set_context_update_callback.3.in000066400000000000000000000056301362622307100250730ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_context_set_context_update_callback 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_context_set_context_update_callback -- get informed on getdns context updates .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_context_set_context_update_callback (getdns_context ** context, .RS 3 .br void (*cbfun)(getdns_context *context, getdns_context_code_t changed_item) .RE .SH DESCRIPTION .LP Changes to the context such as in response to system files that affect the contet (/etc/resolv.conf etc.) trigger a call to the callback function specified as .B cbfun .HP 3 .I context a previously initialized context .HP 3 .I cbfun callback function to invoked when the specified context changes. If this argument is NULL then updates to the context will not invoke a callback. .HP .SH "RETURN VALUES" Upon successful completion each of these functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_GENERIC_ERROR memory allocation failed or some other untoward thing happened .LP .B GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid .SH EXAMPLES TBD .SH SEE ALSO .BR libgetdns (3), .BR getdns_context_create (3), .BR getdns_context_set (3), .BR getdns_context_set_context_update_callback (3), getdns-1.6.0/doc/getdns_convert.3.in000066400000000000000000000071741362622307100172770ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_convert 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_convert, .B getdns_convert_dns_name_to_fqdn, .B getdns_convert_fqdn_to_dns_name -- convert dname between presentation- and wire-format .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_convert_dns_name_to_fqdn (const getdns_bindata *dns_name_wire_fmt, .br .RS 3 char **fqdn_as_string) .RE getdns_return_t .br .B getdns_convert_fqdn_to_dns_name (char *fqdn_as_string, .br .RS 3 const getdns_bindata **dns_name_wire_fmt) .RE .SH DESCRIPTION .LP Names in DNS fields are stored in a fashion very different from the normal presentation format normally used in applications. The DNS format is described in the first paragraph in Section 3.1 of RFC 1035; the presentation format here is a null-terminated string with interior dots. These helper functions only work with names in the DNS format that are not compressed. They are useful for converting domain names in the replies_tree to and from the FQDN presentation format. getdns_convert_dns_name_to_fqdn() converts a domain name in DNS format to the presentation format. For example, the hex sequence 03 77 77 77 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 would be converted to "www.example.com". getdns_convert_fqdn_to_dns_name() does the reverse: it converts a null-terminated string in FQDN format to bytes in DNS format. .HP 3 .I dns_name_wire_fmt The non-compressed DNS wire format name (per RFC 1035) in a bindata structure that will be converted to/from an fqdn. In getdns_convert_fqdn_to_dns_name storage is allocated using the system allocator (malloc) and must be freed by the caller. .HP 3 .I fqdn_as_string a null terminated string to be converted to/from non-compressed DNS wire format name (per RFC 1035). In getdns_convert_dns_name_to_fqdn storage is allocated using the system allocator (malloc) and must be freed by the caller. .HP .SH "RETURN VALUES" Upon successful completion the function returns .B GETDNS_RETURN_GOOD .SH EXAMPLES TBD .SH SEE ALSO .BR libgetdns (3) getdns-1.6.0/doc/getdns_dict.3.in000066400000000000000000000071001362622307100165270ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_dict 3 "@date@" "getdns @version@" getdns .ad l .SH NAME .B getdns_dict, .B getdns_dict_create, .B getdns_dict_create_with_extended_memory_functions, .B getdns_dict_create_with_memory_functions, .B getdns_dict_destroy -- getdns dict create and destroy routines .ad n .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_dict * .br .B getdns_dict_create () getdns_dict * .br .B getdns_dict_create_with_extended_memory_functions .RS 3 (void *userarg, .br void *(*malloc)(void *userarg, size_t sz), .br void *(*realloc)(void *userarg, void *buf, size_t sz), .br void (*free)(void *userarg, void *buf) .RE 3 getdns_dict * .br .B getdns_dict_create_with_memory_functions .RS 3 (void *(*malloc)(size_t sz), .br void *(*realloc)(void *buf, size_t sz), .br void (*free)(void *buf) .RE 3 void .br .B getdns_dict_destroy (getdns_dict *this_dict) .SH DESCRIPTION .LP The getdns_dict type is used to manage name/value pairs in which the names are strings and the data types of the values are heterogeneous and include .RS 3 .br getdns_bindata .br getdns_dict .br getdns_list .br uint32_t .RE .LP The destroy function performs a "deep" destroy, freeing storage for all of the members of the dictionary before destroying the dictionary. There are a number of helper functions that provide access to the dictionary object, see their respective man pages. .LP .I userarg pass this argument to the user specified memory management functions for operations on lists created using extended memory functions .LP .I this_dict the dictionary to destroy .SH "RETURN VALUES" Upon successful completion the getdns_dict_create function returns a valid (empty) dictionary structure that should be freed via a call to getdns_dict_destroy. If a parameter in invalid or in the event of some error getdns_dict_create returns NULL. .SH EXAMPLES TBD .SH SEE ALSO .BR libgetdns (3), .BR getdns_dict_get (3), .BR getdns_dict_set (3), .BR getdns_list (3), .BR getdns_pretty_print_dict (3). getdns-1.6.0/doc/getdns_dict_get.3.in000066400000000000000000000075021362622307100173740ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_dict_get 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_dict_get, .B getdns_dict_get_bindata, .B getdns_dict_get_data_type, .B getdns_dict_get_dict, .B getdns_dict_get_int, .B getdns_dict_get_list, .B getdns_dict_get_names -- get value by name from a getdns dict .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_dict_get_bindata (getdns_dict *this_dict, .RS 3 char *name, .br getdns_bindata **answer) .RE getdns_return_t .br .B getdns_dict_get_data_type (getdns_dict *this_dict, .RS 3 char *name, .br getdns_data_type *answer) .RE getdns_return_t .br .B getdns_dict_get_dict (getdns_dict *this_dict, .RS 3 char *name, .br getdns_dict **answer) .RE getdns_return_t .br .B getdns_dict_get_int (getdns_dict *this_dict, .RS 3 char *name, .br uint32_t *answer) .RE getdns_return_t .br .B getdns_dict_get_list (getdns_dict *this_dict, .RS 3 char *name, .br getdns_list **answer) .RE getdns_return_t .br .B getdns_dict_get_names (getdns_dict *this_dict, .RS 3 getdns_list **answer) .RE .SH DESCRIPTION .LP The getdns_dict type is used to manage name/value pairs in which the names are strings and the data types of the values are heterogeneous and include .RS 3 .br getdns_bindata .br getdns_dict .br getdns_list .br uint32_t .RE .LP .I this_dict the dictionary from which to retrieve the list of names .LP .I name the name whose associated value is to be returned in answer .LP .I answer the list of all names in the dictionary, note that the caller must free storage allocated to the list via a call to .B getdns_list_destroy(3) .SH "RETURN VALUES" Upon successful completion the functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_GENERIC_ERROR if this_dict is not a valid dictionary .LP .B GETDNS_RETURN_NO_SUCH_DICT_NAME if the name argument doesn't exist in the dictionary .LP .B GETDNS_RETURN_WRONG_TYPE_REQUESTED if the requested data type doesn't match the contents of the indexed argument or name .SH EXAMPLES TBD .SH SEE ALSO .BR libgetdns (3), .BR getdns_address (3), .BR getdns_dict (3), .BR getdns_dict_set (3), .BR getdns_general (3), .BR getdns_hostname (3), .BR getdns_list (3), .BR getdns_service (3), getdns-1.6.0/doc/getdns_dict_set.3.in000066400000000000000000000066411362622307100174130ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_dict_set 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_dict_set, .B getdns_dict_set_bindata, .B getdns_dict_set_dict, .B getdns_dict_set_int, .B getdns_dict_set_list, -- set a value by name in a getdns dict .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_dict_set_bindata (getdns_dict *this_dict, .RS 3 char *name, .br getdns_bindata *child_bindata) .RE getdns_return_t .br .B getdns_dict_set_dict (getdns_dict *this_dict, .RS 3 char *name, .br getdns_dict *child_dict) .RE getdns_return_t .br .B getdns_dict_set_int (getdns_dict *this_dict, .RS 3 char *name, .br uint32_t child_uint32_t) .RE getdns_return_t .br .B getdns_dict_set_list (getdns_dict *this_dict, .RS 3 char *name, .br getdns_list *child_list) .RE .SH DESCRIPTION .LP The getdns_dict type is used to manage name/value pairs in which the names are strings and the data types of the values are heterogeneous and include .RS 3 .br getdns_bindata .br getdns_dict .br getdns_list .br uint32_t .RE .LP .I this_dict the dictionary in which to add/update the name/value pair .LP .I name the name whose associated value is to be set. If the name exists in the dictionary the value associated with that name is replaced, if the name does not exist in the dictionary a new item is added to the dictionary. .LP .I child_bindata .I child_dict .I child_list .I child_uint32 value to assign the name .SH "RETURN VALUES" Upon successful completion the functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_GENERIC_ERROR if this_dict is not a valid dictionary .SH EXAMPLES TBD .SH SEE ALSO .BR libgetdns (3), .BR getdns_address (3), .BR getdns_dict (3), .BR getdns_dict_get (3), .BR getdns_general (3), .BR getdns_hostname (3), .BR getdns_service (3) getdns-1.6.0/doc/getdns_display_ip_address.3.in000066400000000000000000000046141362622307100214550ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_display_ip_address 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_display_ip_address -- convert an getdns ip address to string .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include char * .br .B getdns_display_ip_address (const getdns_bindata *ipv4_or_ipv6_addr) .SH DESCRIPTION .LP This helper function returns a nicely formatted string representation of the IPv4 or IPv6 address. The length of the bindata is used to determine whether the address is IPv4 or IPv6. .HP 3 .I ipv4_or_ipv6_addr bindata of the address to print .HP .SH "RETURN VALUES" Returns a string representation of the IP address (allocated using the system allocator - malloc), the caller is responsible for freeing the storage using free(). .SH EXAMPLES TBD .SH SEE ALSO .BR libgetdns (3) getdns-1.6.0/doc/getdns_general.3.in000066400000000000000000000160351362622307100172300ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_general 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_general, .B getdns_general_sync -- do a getdns DNS lookup .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_general (getdns_context *context, .RS 3 const char *name, .br uint16_t request_type .br getdns_dict *extensions, .br void *userarg, .br getdns_transaction_t *transaction_id, .br getdns_callback_t callbackfn) .RE getdns_return_t .br .B getdns_general_sync (getdns_context *context, .RS 3 const char *name, .br uint16_t request_type .br getdns_dict *extensions, .br getdns_dict **response) .RE .SH DESCRIPTION .LP The getdns_general(3) and getdns_general_sync functions provide public entry points into the getdns API library to retrieve any valid responses to a query from the DNS (note that other namespaces in the context are not used). Most typical use cases for applications are probably satisifed via calls to getdns_address(3) which would replace getaddrinfo(3). .HP 3 .I context A pointer to the previsouly created DNS context that is to be used with this DNS request. see getdns_context (3) .HP 3 .I name The ASCII-based domain name looked up as a string. This can also be an IPv4 or IPv6 address for request types that take addresses instead of domain names, such as PTR. The values here follow the rules in section 2.1 of RFC 4343 to allow non-ASCII octets and special characters in labels. .HP 3 .I request_type Specifies the RRtype for the query; the RRtype numbers are listed in the IANA registry. For example, to get the NS records, request_type would be 2. The API also has defined macros for most of the RRtypes by name; the definition names all start with "GETDNS_RRTYPE_". For example, to get the NS records, you can also set the request_type to GETDNS_RRTYPE_NS. .HP 3 .I extensions extensions for this request, NULL if no extensions, see libgetnds (3) for a detailed description of extensions .HP 3 .I userarg returned to the callback function untouched, can be NULL .HP 3 .I transaction_id populated by the API and used to identify the callback (for example to getdns_cancel_callback), can be NULL, set to 0 if the function fails .HP 3 .I callbackfn non-NULL pointer to a callback function defined by the application, typically used to process the response. Only the asynchronous signature accepts a callback function, the synchronous signature does not include a callback. See libgetdns (3) for a more detailed discussion of callback functions. .HP 3 .I response A getdns_dict type is returned in response and always contains at least three names: replies_full (a list containing the DNS response as binary data), replies_tree (a list containing the parsed DNS response data) and status (an int). The storage associated with this must be freed by a call to getdns_free_sync_request_memory (3). .HP .SH "RETURN VALUES" Upon successful completion the functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid or the context has internal deficiencies .LP .B GETDNS_RETURN_BAD_DOMAIN_NAME if the domain name passed to the function is invalid .LP .B GETDNS_RETURN_EXTENSION_MISFORMAT if the data type specified in one or more of the extensions does not match the specifications .LP .B GETDNS_RETURN_GENERIC_ERROR if some problem was encountered in the function not addressed by one of the more specific return codes .LP .B GETDNS_RETURN_INVALID PARAMETER if one or more parameters has an invalid value .LP .B GETDNS_RETURN_MEMORY_ERROR if unable to allocate the memory required .LP .B GETDNS_RETURN_NO_SUCH_EXTENSION if one or more of the strings specified in the extensions are not valid The values of status included in the response parameter are: .LP .B GETDNS_RESPSTATUS_GOOD if at least one response was returned .LP .B GETDNS_RESPSTATUS_NO_NAME if queries for the name yielded all negative responses .LP .B GETDNS_RESPSTATUS_ALL_TIMEOUT if all queries for the name timed out .LP .B GETDNS_RESPSTATUS_NO_SECURE_ANSWERS if only secure replies accepted (per context) and at least one response was received but no DNS responses were secure through DNSSEC .LP For a more detailed explanation of the response object see .I libgetdns (3) .SH REQUEST TYPES This is a list of the most common request types, a full list of request types in more detail is available at http://www.iana.org/assignments/dns-parameters/dns-parameters.xml .RS 3 .TP 11 .B A Host address .TP .B AAAA IPv6 address .TP .B CAA Certificate Authority Authorization .TP .B CNAME Canonical name for an alias .TP .B DLV DNSSEC lookaside validation .TP .B DNAME DNAME .TP .B DS Delegation signer .TP .B HINFO Host information .TP .B KEY Security key .TP .B MINFO Mailbox or mail list information .TP .B MX Mail exchange .TP .B NS Authoritative name server .TP .B NSEC Next secure record .TP .B NSEC3 Next secure record (hashed) .TP .B NSEC3PARAM NSEC3PARAM .TP .B PTR Domain name pointer .TP .B RRSIG Signature for a record set .TP .B SIG Security signature .TP .B SOA Marks the start of a zone of authority .TP .B SRV Server selection .TP .B TA DNSSEC trust authorities .TP .B TKEY Transaction key .TP .B TLSA TLSA .TP .B TSIG Transaction signature .TP .B TXT Text strings .RE .SH EXAMPLES TBD .SH FILES .br /etc/hosts .br /etc/resolv.conf .SH SEE ALSO .BR libgetdns (3), .BR getdns_address (3), .BR getdns_context (3), .BR getdns_free_sync_request_memory (3), .BR getdns_hostname (3), .BR getdns_service (3), getdns-1.6.0/doc/getdns_hostname.3.in000066400000000000000000000125011362622307100174230ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_hostname 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_hostname, .B getdns_hostname_sync -- get hostname by address .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_hostname (getdns_context *context, .RS 3 getdns_dict *address, .br getdns_dict *extensions, .br void *userarg, .br getdns_transaction_t *transaction_id, .br getdns_callback_t callbackfn) .RE getdns_return_t .br .B getdns_hostname_sync (getdns_context *context, .RS 3 getdns_dict *address, .br getdns_dict *extensions, .br getdns_dict **response) .RE .SH DESCRIPTION .LP The getdns_hostname(3) and getdns_hostname_sync functions provide public entry points into the getdns API library to retrieve the host name given an address. .HP 3 .I context A pointer to the previously created DNS context that is to be used with this DNS request. see getdns_context (3) .HP 3 .I address a getdns_dict structure containing two names: address_type (whose value is bindata and is either "IPv4" or "IPv6") and address_data whose value is bindata .HP 3 .I extensions extensions for this request, NULL if no extensions, see libgetdns (3) for a detailed description of extensions .HP 3 .I userarg returned to the callback function untouched, can be NULL .HP 3 .I transaction_id populated by the API and used to identify the callback (for example to getdns_cancel_callback), can be NULL, set to 0 if the function fails .HP 3 .I callbackfn non-NULL pointer to a callback function defined by the application, typically used to process the response. Only the asynchronous signature accepts a callback function, the synchronous signature does not include a callback. See libgetdns (3) for a more detailed discussion of callback functions. .HP 3 .I response A getdns_dict type is returned in response and always contains at least three names: replies_full (a list containing the DNS response as binary data), replies_tree (a list containing the parsed DNS response data) and status (an int). The storage associated with this must be freed by a call to getdns_free_sync_request_memory (3). .HP .SH "RETURN VALUES" Upon successful completion the functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid or the context has internal deficiencies .LP .B GETDNS_RETURN_BAD_DOMAIN_NAME if the domain name passed to the function is invalid .LP .B GETDNS_RETURN_EXTENSION_MISFORMAT if the data type specified in one or more of the extensions does not match the specifications .LP .B GETDNS_RETURN_GENERIC_ERROR if some problem was encountered in the function not addressed by one of the more specific return codes .LP .B GETDNS_RETURN_INVALID PARAMETER if one or more parameters has an invalid value .LP .B GETDNS_RETURN_MEMORY_ERROR if unable to allocate the memory required .LP .B GETDNS_RETURN_NO_SUCH_EXTENSION if one or more of the strings specified in the extensions are not valid The values of status included in the response parameter are: .LP .B GETDNS_RESPSTATUS_GOOD if at least one response was returned .LP .B GETDNS_RESPSTATUS_NO_NAME if queries for the name yielded all negative responses .LP .B GETDNS_RESPSTATUS_ALL_TIMEOUT if all queries for the name timed out .LP .B GETDNS_RESPSTATUS_NO_SECURE_ANSWERS if only secure replies accepted (per context) and at least one response was received but no DNS responses were secure through DNSSEC .LP For a more detailed explanation of the response object see .I libgetdns (3) .SH EXAMPLES TBD .SH FILES .br /etc/hosts .br /etc/resolv.conf .SH SEE ALSO .BR libgetdns (3), .BR getdns_context (3), .BR getdns_free_sync_request_memory (3), .BR getdns_general (3), .BR getdns_address (3), .BR getdns_service (3), getdns-1.6.0/doc/getdns_list.3.in000066400000000000000000000070021362622307100165600ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_list 3 "@date@" "getdns @version@" getdns .ad l .SH NAME .B getdns_list, .B getdns_list_create, .B getdns_list_create_with_extended_memory_functions, .B getdns_list_create_with_memory_functions, .B getdns_list_destroy -- getdns list create and destroy routines .ad n .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_list * .br .B getdns_list_create () getdns_list * .br .B getdns_list_create_with_extended_memory_functions .RS 3 (void *userarg, .br void *(*malloc)(void *userarg, size_t sz), .br void *(*realloc)(void *userarg, void *buf, size_t sz), .br void (*free)(void *userarg, void *buf) .RE 3 getdns_list * .br .B getdns_list_create_with_memory_functions .RS 3 (void *userarg, .br void *(*malloc)(size_t sz), .br void *(*realloc)(void *buf, size_t sz), .br void (*free)(void *buf) .RE 3 void .br .B getdns_list_destroy (getdns_list *this_dict) .SH DESCRIPTION .LP The getdns_list type is used to manage heterogeneous indexed lists name/value pairs in which the data types of the values include .RS 3 .br getdns_bindata .br getdns_dict .br getdns_list .br uint32_t .RE .LP The destroy function performs a "deep" destroy, freeing storage for all of the members of the list before destroying the list. There are a number of helper functions that provide access to the list object, see their respective man pages. .LP .I userarg pass this argument to the user specified memory management functions for operations on lists created using extended memory functions .LP .I this_list the list to destroy .SH "RETURN VALUES" Upon successful completion the getdns_list_create function returns a valid (empty) list structure that should be freed via a call to getdns_list_destroy. If a parameter in invalid or in the event of some error getdns_list_create returns NULL. .SH EXAMPLES TBD .SH SEE ALSO .BR libgetdns (3), .BR getdns_dict (3), .BR getdns_list_get (3), .BR getdns_list_set (3) getdns-1.6.0/doc/getdns_list_get.3.in000066400000000000000000000073671362622307100174350ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_list 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_list_get, .B getdns_list_get_bindata, .B getdns_list_get_data_type, .B getdns_list_get_dict, .B getdns_list_get_length, .B getdns_list_get_list, .B getdns_list_get_int -- get a value by index from a getdns list .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_list_get_bindata (getdns_list *this_list, .RS 3 size_t index, .br getdns_bindata **answer) .RE getdns_return_t .br .B getdns_list_get_data_type (getdns_list *this_list, .RS 3 size_t index, .br getdns_data_type *answer) .RE getdns_return_t .br .B getdns_list_get_dict (getdns_list *this_list, .RS 3 size_t index, .br getdns_dict **answer) .RE getdns_return_t .br .B getdns_list_get_length (getdns_list *this_list, .RS 3 size_t *answer) .RE getdns_return_t .br .B getdns_list_get_list (getdns_list *this_list, .RS 3 size_t index, .br getdns_list **answer) .RE getdns_return_t .br .B getdns_list_get_int (getdns_list *this_list, .RS 3 size_t index, .br uint32_t *answer) .RE .SH DESCRIPTION .LP The getdns_list type is used to manage heterogeneous lists in which the objects are each one of the data types: .RS 3 .br getdns_bindata .br getdns_dict .br getdns_list .br uint32_t .RE .LP .I this_list the list from which to retrieve the object .LP .I index the numeric index (0 based) of the item in the list you would like copied to answer .LP .I answer a copy of the object in the list is placed in answer, the caller is responsible for freeing the storage associated with that object by calling the appropriate destroy function. .SH "RETURN VALUES" Upon successful completion the functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_GENERIC_ERROR if this_list is not a valid list .LP .B GETDNS_RETURN_NO_SUCH_LIST_ITEM if index is out of range .LP .B GETDNS_RETURN_WRONG_TYPE_REQUESTED if the requested data type doesn't match the contents of the indexed argument .SH EXAMPLES TBD .SH SEE ALSO .BR libgetdns (3), .BR getdns_address (3), .BR getdns_dict (3), .BR getdns_general (3), .BR getdns_hostname (3), .BR getdns_service (3), getdns-1.6.0/doc/getdns_list_set.3.in000066400000000000000000000066751362622307100174520ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_list_set 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_list_set, .B getdns_list_set_bindata, .B getdns_list_set_dict, .B getdns_list_set_int, .B getdns_list_set_list, -- set a value by index from a getdns list .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_list_set_bindata (getdns_list *this_list, .RS 3 size_t index, .br getdns_bindata *child_bindata) .RE getdns_return_t .br .B getdns_list_set_dict (getdns_list *this_list, .RS 3 size_t index, .br getdns_dict *child_dict) .RE getdns_return_t .br .B getdns_list_set_int (getdns_list *this_list, .RS 3 size_t index, .br uint32_t child_uint32_t) .RE getdns_return_t .br .B getdns_list_set_list (getdns_list *this_list, .RS 3 size_t index, .br getdns_list *child_list) .RE .SH DESCRIPTION .LP The getdns_list type is used to manage a heterogeneous indexed list of values that include: .RS 3 .br getdns_bindata .br getdns_dict .br getdns_list .br uint32_t .RE .LP .I this_list the list in which to add/update the indexed item .LP .I index the index whose associated value is to be set. If the index exists in the list the value associated with that index is replaced, if the index does not exist in the list a new item is added to the list at the specified index. .LP .I child_bindata .I child_dict .I child_list .I child_uint32 value to assign the indexed element .SH "RETURN VALUES" Upon successful completion the functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index is out of range .LP .B GETDNS_RETURN_GENERIC_ERROR if this_list is not a valid list .SH EXAMPLES TBD .SH SEE ALSO .BR libgetdns (3), .BR getdns_address (3), .BR getdns_list (3), .BR getdns_list_get (3), .BR getdns_general (3), .BR getdns_hostname (3), .BR getdns_service (3), getdns-1.6.0/doc/getdns_pretty_print_dict.3.in000066400000000000000000000045141362622307100213600ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_pretty_print_dict 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_pretty_print_dict -- return a string representation of a getdns dict .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include char * .br .B getdns_pretty_print_dict (const getdns_dict *this_dict) .SH DESCRIPTION .LP Helper function that returns a string of nicely formatted data including all of the elements in the dict. .HP 3 .I this_dict the dictionary to render as a string .HP .SH "RETURN VALUES" Returns a string that the calling function must free (it is allocated using the system allocator not the user defined allocator). Returns NULL if there is an error. .SH EXAMPLES TBD .SH SEE ALSO .BR getdns_dict (3) .BR libgetdns (3) getdns-1.6.0/doc/getdns_root_trust_anchor.3.in000066400000000000000000000053431362622307100213710ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_root_trust_anchor 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_root_trust_anchor -- return the getdns list of default root trust anchors .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_list * .br .B getdns_root_trust_anchor (time_t *utc_date_of_anchor) .SH DESCRIPTION .LP If an application wants the API to perform DNSSEC validation without using the extensions, it can use the getdns_validate_dnssec() helper function. The API will use the resource records in bundle_of_support_records to construct the validation chain and the DNSKEY or DS records in trust_anchor_records as trust anchors. The default list of trust anchor records that is used by the library to validate DNSSEC can be retrieved by using the getdns_root_trust_anchor helper function. .HP 3 .I utc_date_of_anchor time the trust anchors were obtained in epoch seconds (on success) .HP .SH "RETURN VALUES" Returns the default list of trust anchor records used by the library to validate DNSSEC or NULL if no default trust anchors are available. .SH EXAMPLES TBD .SH SEE ALSO .BR getdns_validate_dnssec (3) .BR libgetdns (3) getdns-1.6.0/doc/getdns_service.3.in000066400000000000000000000122631362622307100172520ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLNet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_service 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_service, .B getdns_service_sync -- getdns lookup of a service .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_service (getdns_context *context, .RS 3 const char *name, .br getdns_dict *extensions, .br void *userarg, .br getdns_transaction_t *transaction_id, .br getdns_callback_t callbackfn) .RE getdns_return_t .br .B getdns_service_sync (getdns_context *context, .RS 3 const char *name, .br getdns_dict *extensions, .br getdns_dict **response) .RE .SH DESCRIPTION .LP The getdns_service (3) and getdns_service_sync functions provide public entry points into the getdns API library to retrieve the SRV information given a name. .HP 3 .I context A pointer to the previously created DNS context that is to be used with this DNS request. see getdns_context (3) .HP 3 .I name the service name to resolve .HP 3 .I extensions extensions for this request, NULL if no extensions, see libgetdns (3) for a detailed description of extensions .HP 3 .I userarg returned to the callback function untouched, can be NULL .HP 3 .I transaction_id populated by the API and used to identify the callback (for example to getdns_cancel_callback), can be NULL, set to 0 if the function fails .HP 3 .I callbackfn non-NULL pointer to a callback function defined by the application, typically used to process the response. Only the asynchronous signature accepts a callback function, the synchronous signature does not include a callback. See libgetdns (3) for a more detailed discussion of callback functions. .HP 3 .I response A getdns_dict type is returned in response and always contains at least three names: replies_full (a list containing the DNS response as binary data), replies_tree (a list containing the parsed DNS response data) and status (an int). The storage associated with this must be freed by a call to getdns_free_sync_request_memory (3). .HP .SH "RETURN VALUES" Upon successful completion the functions return .B GETDNS_RETURN_GOOD , otherwise the following error values are returned: .LP .B GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid or the context has internal deficiencies .LP .B GETDNS_RETURN_BAD_DOMAIN_NAME if the domain name passed to the function is invalid .LP .B GETDNS_RETURN_EXTENSION_MISFORMAT if the data type specified in one or more of the extensions does not match the specifications .LP .B GETDNS_RETURN_GENERIC_ERROR if some problem was encountered in the function not addressed by one of the more specific return codes .LP .B GETDNS_RETURN_INVALID PARAMETER if one or more parameters has an invalid value .LP .B GETDNS_RETURN_MEMORY_ERROR if unable to allocate the memory required .LP .B GETDNS_RETURN_NO_SUCH_EXTENSION if one or more of the strings specified in the extensions are not valid The values of status included in the response parameter are: .LP .B GETDNS_RESPSTATUS_GOOD if at least one response was returned .LP .B GETDNS_RESPSTATUS_NO_NAME if queries for the name yielded all negative responses .LP .B GETDNS_RESPSTATUS_ALL_TIMEOUT if all queries for the name timed out .LP .B GETDNS_RESPSTATUS_NO_SECURE_ANSWERS if only secure replies accepted (per context) and at least one response was received but no DNS responses were secure through DNSSEC .LP For a more detailed explanation of the response object see .I libgetdns (3) .SH EXAMPLES TBD .SH FILES .br /etc/hosts .br /etc/resolv.conf .SH SEE ALSO .BR libgetdns (3), .BR getdns_context (3), .BR getdns_free_sync_request_memory (3), .BR getdns_general (3), .BR getdns_hostname (3), .BR getdns_address (3), getdns-1.6.0/doc/getdns_validate_dnssec.3.in000066400000000000000000000062051362622307100207410ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH getdns_validate_dnssec 3 "@date@" "getdns @version@" getdns .SH NAME .B getdns_validate_dnssec -- DNSSEC validate a given getdns record .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS #include getdns_return_t .br .B getdns_validate_dnssec (getdns_list *record_to_validate, .br .RS 3 getdns_list *bundle_of_support_records, .br getdns_list *trust_anchor_records) .RE .SH DESCRIPTION .LP If an application wants the API to perform DNSSEC validation without using the extensions, it can use the getdns_validate_dnssec() helper function. The API will use the resource records in bundle_of_support_records to construct the validation chain and the DNSKEY or DS records in trust_anchor_records as trust anchors. The default list of trust anchor records that is used by the library to validate DNSSEC can be retrieved by using the getdns_root_trust_anchor helper function. .HP 3 .I record_to_validate the resource record being validated .HP 3 .I bundle_of_support_records records used to construct the validation chain .HP 3 .I trust_anchor_records trust anchor records to use for the validation .HP .SH "RETURN VALUES" .LP .B GETDNS_DNSSEC_BOGUS the DNSSEC signature is bogus .LP .B GETDNS_DNSSEC_INDETERMINATE validation could not be completed .LP .B GETDNS_DNSSEC_INSECURE one or more pieces of the validation chain are demonstrably incorrect .LP .B GETDNS_DNSSEC_SECURE validation succeeded .LP .B GETDNS_RETURN_MEMORY_ERROR an attempt to allocate memory failed .SH EXAMPLES TBD .SH SEE ALSO .BR getdns_root_trust_anchor (3) .BR libgetdns (3) getdns-1.6.0/doc/libgetdns.3.in000066400000000000000000000626011362622307100162220ustar00rootroot00000000000000.\" The "BSD-New" License .\" .\" Copyright (c) 2013, NLnet Labs, Verisign, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions are met: .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" * Neither the names of the copyright holders nor the .\" names of its contributors may be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .TH libgetdns 3 "@date@" "getdns @version@" getdns .SH NAME libgetdns -- an implementation of a modern asynchronous DNS API by and for application developers .SH LIBRARY DNS Resolver library (libgetdns, \-lgetdns) .SH SYNOPSIS .B libgetdns This man page describes the getdns library, the general concepts behind the API and some of the common elements of the public interface to the library. Each of the public entry points and more complex data types are captured in separate man pages. .SH DESCRIPTION .LP getdns is modern asynchronous DNS API intended to be useful to application developers and operating system distributors as a way of making all types of DNS information easily available in many types of programs. The major features of this new API are: .RS 3 Full support for event-driven programming Supports DNSSEC in multiple ways Mirroring of the resolution in getaddrinfo() Easily supports all RRtypes, even those yet to be defined .RE .LP Each of the entry points is offered with both asynchronous and synchronous signatures. The asynchronous functions rely on event handling and callback via libevent. Functions are thread safe. .LP A context structure maintains DNS query and response data and is used to maintain state during calls to the public entry points. .LP The project page for this implementation is at .IP http://getdnsapi.net .LP The specification is maintained at .IP http://getdnsapi.net/spec .LP The git repository for this implementation is at .IP http://github.com/getdnsapi/getdns .SH DATA STRUCTURES .LP The API uses a few data structures to pass data into and return data from the public entry points. .IP list an ordered list, the members of the list can be any of the four data types. .IP dict a name-value pair. The name is a string literal, and the value can be any of the four data types. The order of the name-value pairs in a dict is not important. .IP int an integer compatible with uint32_t. .IP bindata a struct used to hold binary data defined as { size_t size; uint8_t *binary_stuff; }. .SH ASYNCHRONOUS USE .LP The getdns specification emphasizes the asynchronous nature of the API and allows implementations to define their own approach. This page documents this implementation's decisions and facilities provided to the developer. .LP This implementation provides asynchronous support via the following mechanisms: .RS 3 File Descriptor Polling .br Event Loop Integrations: .RS 3 libevent .br libuv .br libev .RE Custom Event Loop Integrations .RE .LP All functions and types discussed in this page are declared in getdns_extra.h .SS "Build-in Event loop" The library has an built in event loop that can be used if none of the extensions for external event loops are used. The library will execute requests and dispatch callbacks with a call to .I getdns_context_run(). If an event loop extension is used, this will run the extension's eventloop. .HP 3 void getdns_context_run(getdns_context *context) Run the context's event loop until nothing more to do. .HP 3 uint32_t getdns_context_get_num_pending_requests(getdns_context* context, struct timeval* next_timeout) Get the number of outstanding asynchronous requests for a given context as well as the the amount of time until the next timeout. The next_timeout struct can be NULL. If supplied and the number of outstanding requests is > 0, then the timeout represents the relative time until the next timeout. .HP 3 getdns_return_t getdns_context_process_async(getdns_context* context) Inform the context to process its outstanding requests. Users should call this when either a timeout has occurred or the file descriptor signals that it is ready. User callbacks are fired during this call. .SS "Included Event Loop Integrations" .LP A number of applications achieve asynchronous behavior by leveraging event loop abstraction libraries. If the build system discovers a supported event loop, the event loop extension is built in addition to the getdns library. Extensions are built as an additional shared library. The following event loop libraries are supported: .B libevent1 and libevent2 .LP The libevent extension allows a context to attach to a event_base. The event loop is then run like any other application using libevent via event_base_dispatch or event_base_loop and expect getdns callbacks to fire. .LP Note that if both libevent1 and libevent2 reside on system, the extension uses libevent2. .RS 3 Extension library: libgetdns_ext_event.[shared_lib_ext] .br Extension header: getdns/getdns_ext_libevent.h .RE .B libuv .LP The libuv extension allows a context to attach to a uv_loop_s. The event loop can then be run like any other application using libuv via uv_run and expect getdns callbacks to fire. .RS 3 Extension library: libgetdns_ext_uv.[shared_lib_ext] .br Extension header: getdns_ext_libuv.h .RE .B libev .LP The libev extension allows a context to attach to a ev_loop. The event loop can then be run like any other application using libev via ev_run and expect getdns callbacks to fire. .RS 3 Extension library: libgetdns_ext_ev.[shared_lib_ext] .br Extension header: getdns_ext_libev.h .RE .SS "getdns_context event loop extension functions" .LP The following are functions used by the extension entry point to attach to a particular context. .LP The application sets an event loop extension on a context. The extension_data is optional data that is passed into the extension methods. If an event loop is already set on a context then it is cleaned up. All outstanding requests are also canceled. .IP getdns_return_t getdns_extension_set_eventloop(struct getdns_context* context, getdns_eventloop_extension* extension, void* extension_data); .LP The application gets the extension data associated with a context. .IP void* getdns_context_get_extension_data(struct getdns_context* context); .LP When no more work must be done the application detaches an event loop from a context .IP getdns_return_t getdns_extension_detach_eventloop(struct getdns_context* context); .SH SYNCHRONOUS USE .LP There are four synchronous functions parallel to the four getdns async functions, except that there is no callback parameter. When an application calls one of these synchronous functions, the API gathers all the required information and then returns the result. The value returned is exactly the same as the response returned in the callback if you had used the async version of the function. .LP When you are done with the data in the response, call getdns_free_sync_request_memory so that the API can free the memory from its internal pool. .SH EXTENSIONS Applications may populate an extension dictionary when making a call to the public entry points. To use an extension add it to the extension dictionary prior to making the call to the public entry point and set the value depending on the behavior you expect. These extensions include: .HP 3 "dnssec_return_status" (int) Set to GETDNS_EXTENSION_TRUE to include the DNSSEC status for each DNS record in the replies_tree .HP 3 "dnssec_return_only_secure" (int) Set to GETDNS_EXTENSION_TRUE to cause only records that the API can validate as secure with DNSSEC to be returned in the .I replies_tree and .I replies_full lists .HP 3 "dnssec_return_validation_chain" (int) Set to GETDNS_EXTENSION_TRUE to cause the set of additional DNSSEC-related records needed for validation to be returned in the response object as the list named .I additional_dnssec at the top level of the response object .HP 3 "return_both_v4_and_v6" (int) Set to GETDNS_EXTENSION_TRUE to cause the results of both A and AAAA records for the queried name to be included in the response object. .HP 3 "add_opt_parameters" (dict) TBD (complicated) .HP 3 "add_warning_for_bad_dns" Set to GETDNS_EXTENSION_TRUE to cause each reply in the .I replies_tree to contain an additional name whose data type is a list, .I bad_dns which contains zero or more ints that indicate the types of bad DNS found in the reply. .RS 6 .br GETDNS_BAD_DNS_CNAME_IN_TARGET: query type does not allow a CNAME pointed to a CNAME .br GETDNS_BAD_DNS_ALL_NUMERIC_LABEL: one or more labels is all numeric .br GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE: query type for other than CNAME returned a CNAME .RE .HP 3 "specify_class" (int) Set to the DNS class number (other than Internet (IN) class desired in query. .HP 3 "return_call_reporting" (int) Set to GETDNS_EXTENSION_TRUE to add the name .I call_reporting (list) to the top level of the response object that includes a dict for each call made to the API. TBD: more detail .LP This implementation of the getdns API is licensed under the BSD license. .SH DNSSEC .LP If an application wants the API to do DNSSEC validation for a request, it must set one or more DNSSEC-related extensions. Note that the default is for none of these extensions to be set and the API will not perform DNSSEC. Note that getting DNSSEC results can take longer in a few circumstances. .LP To return the DNSSEC status for each DNS record in the replies_tree list, use the dnssec_return_status extension. The extension's value (an int) is set to GETDNS_EXTENSION_TRUE to cause the returned status to have the name dnssec_status (an int) added to the other names in the record's dict ("header", "question", and so on). The values for that name are GETDNS_DNSSEC_SECURE, GETDNS_DNSSEC_BOGUS, GETDNS_DNSSEC_INDETERMINATE, and GETDNS_DNSSEC_INSECURE. Thus, a reply might look like: .EX { # This is the first reply "dnssec_status": GETDNS_DNSSEC_INDETERMINATE, "header": { "id": 23456, "qr": 1, "opcode": 0, ... }, . . . .EE .LP If instead of returning the status, you want to only see secure results, use the dnssec_return_only_secure extension. The extension's value (an int) is set to GETDNS_EXTENSION_TRUE to cause only records that the API can validate as secure with DNSSEC to be returned in the replies_tree and replies_full lists. No additional names are added to the dict of the record; the change is that some records might not appear in the results. When this context option is set, if the API receives DNS replies but none are determined to be secure, the error code at the top level of the response object is GETDNS_RESPSTATUS_NO_SECURE_ANSWERS. .LP Applications that want to do their own validation will want to have the DNSSEC-related records for a particular response. Use the dnssec_return_validation_chain extension. The extension's value (an int) is set to GETDNS_EXTENSION_TRUE to cause a set of additional DNSSEC-related records needed for validation to be returned in the response object. This set comes as validation_chain (a list) at the top level of the response object. This list includes all resource record dicts for all the resource records (DS, DNSKEY and their RRSIGs) that are needed to perform the validation from the root up. Thus, a reply might look like: .EX { # This is the response object "validation_chain": [ { "name": , "type": GETDNS_RRTYPE_DNSKEY, "rdata": { "flags": 256, . . . }, . . . }, { "name": , "type": GETDNS_RRTYPE_DNSKEY, "rdata": { "flags": 257, . . . }, . . . }, { "name": , "type": GETDNS_RRTYPE_RRSIG, "rdata": { "signers_name": , "type_covered": GETDNS_RRTYPE_DNSKEY, . . . }, }, { "name": , "type": GETDNS_RRTYPE_DS, . . . }, { "name": , "type": GETDNS_RRTYPE_RRSIG "rdata": { "signers_name": , "type_covered": GETDNS_RRTYPE_DS, . . . }, . . . }, { "name": , "type": GETDNS_RRTYPE_DNSKEY "rdata": { "flags": 256, . . . }, . . . }, { "name": , "type": GETDNS_RRTYPE_DNSKEY "rdata": { "flags": 257, . . . }, . . . }, { "name": , "type": GETDNS_RRTYPE_RRSIG "rdata": { "signers_name": , "type_covered": GETDNS_RRTYPE_DNSKEY, . . . }, . . . }, { "name": , "type": GETDNS_RRTYPE_DS, . . . }, { "name": , "type": GETDNS_RRTYPE_RRSIG "rdata": { "signers_name": , "type_covered": GETDNS_RRTYPE_DS, . . . }, . . . }, { "name": , "type": GETDNS_RRTYPE_DNSKEY "rdata": { "flags": 257, ... }, . . . }, . . . ] "replies_tree": [ . . . .EE .LP If a request is using a context in which stub resolution is set, and that request also has any of the dnssec_return_status, dnssec_return_only_secure, or dnssec_return_validation_chain extensions specified, the API will not perform the request and will instead return an error of GETDNS_RETURN_DNSSEC_WITH_STUB_DISALLOWED. .SH OPT RESOURCE RECORDS .LP For lookups that need an OPT resource record in the Additional Data section, use the add_opt_parameters extension. The extension's value (a dict) contains the parameters; these are described in more detail in RFC 2671. They are: .HP 3 .I maximum_udp_payload_size (an int) between 512 and 65535; if not specified, this defaults to those from the DNS context .HP 3 .I extended_rcode (an int) between 0 and 255; if not specified, this defaults to those from the DNS context .HP 3 .I version (an int) between 0 and 255; if not specified, this defaults to 0 .HP 3 .I do_bit (an int) between 0 and 1; if not specified, this defaults to those from the DNS context .HP 3 .I options (a list) contains dicts for each option to be specified. Each list time contains two names: option_code (an int) and option_data (a bindata). The API marshalls the entire set of options into a properly-formatted RDATA for the resource record. .LP It is very important to note that the OPT resource record specified in the add_opt_parameters extension might not be the same the one that the API sends in the query. For example, if the application also includes any of the DNSSEC extensions, the API will make sure that the OPT resource record sets the resource record appropriately, making the needed changes to the settings from the add_opt_parameters extension. .LP The use of this extension can conflict with the values in the DNS context. For example, the default for an OS might be a maximum payload size of 65535, but the extension might specify 1550. In such a case, the API will honor the values stated in the extension, but will honor the values from the DNS context if values are not given in the extension. .SH RESPONSE DATA .LP The callback function contains a pointer to a response object. A response object is always a dict. The response object always contains at least three names: replies_full (a list) and replies_tree (a list), and status (an int). replies_full is a list of DNS replies (each is bindata) as they appear on the wire. replies_tree is a list of DNS replies (each is a dict) with the various part of the reply parsed out. status is a status code for the query. .LP Because the API might be extended in the future, a response object might also contain names other than replies_full, replies_tree, and status. Similarly, any of the dicts described here might be extended in later versions of the API. Thus, an application using the API must not assume that it knows all possible names in a dict. .LP The following lists the status codes for response objects. Note that, if the status is that there are no responses for the query, the lists in replies_full and replies_tree will have zero length. .HP 3 .B GETDNS_RESPSTATUS_GOOD At least one response was returned .HP 3 .B GETDNS_RESPSTATUS_NO_NAME Queries for the name yielded all negative responses .HP 3 .B GETDNS_RESPSTATUS_ALL_TIMEOUT All queries for the name timed out .HP 3 .B GETDNS_RESPSTATUS_NO_SECURE_ANSWERS The context setting for getting only secure responses was specified, and at least one DNS response was received, but no DNS response was determined to be secure through DNSSEC. .LP The top level of replies_tree can optionally have the following names: canonical_name (a bindata), intermediate_aliases (a list), answer_ipv4_address (a bindata), answer_ipv6_address (a bindata), and answer_type (an int). .LP The value of canonical_name is the name that the API used for its lookup. It is in FQDN presentation format. The values in the intermediate_aliases list are domain names from any CNAME or unsynthesized DNAME found when resolving the original query. The list might have zero entries if there were no CNAMEs in the path. These may be useful, for example, for name comparisons when following the rules in RFC 6125. The value of answer_ipv4_address and answer_ipv6_address are the addresses of the server from which the answer was received. The value of answer_type is the type of name service that generated the response. The values are: .RS 3 GETDNS_NAMETYPE_DNS Normal DNS (RFC 1035) GETDNS_NAMETYPE_WINS The WINS name service (some reference needed) .RE .LP If the call was getdns_address or getdns_address_sync, the top level of replies_tree has an additional name, just_address_answers (a list). The value of just_address_answers is a list that contains all of the A and AAAA records from the answer sections of any of the replies, in the order they appear in the replies. Each item in the list is a dict with at least two names: address_type (whose value is a bindata; it is currently either "IPv4" or "IPv6") and address_data (whose value is a bindata). Note that the dnssec_return_only_secure extension affects what will appear in the just_address_answers list. If the DNS returns other address types, those types will appear in this list as well. .LP The API can make service discovery through SRV records easier. If the call was getdns_service or getdns_service_sync, the top level of replies_tree has an additional name, srv_addresses (a list). The list is ordered by priority and weight based on the weighting algorithm in RFC 2782, lowest priority value first. Each element of the list is dict has at least two names: port and domain_name. If the API was able to determine the address of the target domain name (such as from its cache or from the Additional section of responses), the dict for an element will also contain address_type (whose value is a bindata; it is currently either "IPv4" or "IPv6") and address_data (whose value is a bindata). Note that the dnssec_return_only_secure extension affects what will appear in the srv_addresses list. .SH STRUCTURE OF DNS REPLIES_TREE .LP The names in each entry in the the replies_tree list for DNS responses include header (a dict), question (a dict), answer (a list), authority (a list), and additional (a list), corresponding to the sections in the DNS message format. The answer, authority, and additional lists each contain zero or more dicts, with each dict in each list representing a resource record. .LP The names in the header dict are all the fields from Section 4.1.1. of RFC 1035. They are: id, qr, opcode, aa, tc, rd, ra, z, rcode, qdcount, ancount, nscount, and arcount. All are ints. .LP The names in the question dict are the three fields from Section 4.1.2. of RFC 1035: qname (a bindata), qtype (an int), and qclass (an int). .LP Resource records are a bit different than headers and question sections in that the RDATA portion often has its own structure. The other names in the resource record dicts are name (a bindata), type (an int), class (an int), ttl (an int) and rdata (a dict); there is no name equivalent to the RDLENGTH field. .LP The rdata dict has different names for each response type. There is a complete list of the types defined in the API. For names that end in "-obsolete" or "-unknown", the bindata is the entire RDATA field. For example, the rdata for an A record has a name ipv4_address (a bindata); the rdata for an SRV record has the names priority (an int), weight (an int), port (an int), and target (a bindata). .LP Each rdata dict also has a rdata_raw field (a bindata). This is useful for types not defined in this version of the API. It also might be of value if a later version of the API allows for additional parsers. Thus, doing a query for types not known by the API still will return a result: an rdata with just a rdata_raw. .LP It is expected that later extensions to the API will give some DNS types different names. It is also possible that later extensions will change the names for some of the DNS types listed above. .SH CALLBACK FUNCTIONS .LP A call to the async getdns functions typically returns before any network or file I/O occurs. After the API marshalls all the needed information, it calls the callback function that was passed by the application. The callback function might be called at any time, even before the calling function has returned. The API guarantees that the callback will be called exactly once unless the calling function returned an error, in which case the callback function is never called. The getdns calling function calls the callback with the parameters defined as follows: .br typedef void (*getdns_callback_t)( .RS 3 getdns_context_t context, .br uint16_t callback_type, .br getdns_dict *response, .br void *userarg, .br getdns_transaction_t transaction_id) .RE .HP 3 .I context see getdns_context (3) .HP 3 .I callback_type Supplies the reason for the callback. .RS 3 .LP .B GETDNS_CALLBACK_COMPLETE The response has the requested data in it .LP .B GETDNS_CALLBACK_CANCEL The calling program canceled the callback; response is NULL .LP .B GETDNS_CALLBACK_TIMEOUT The requested action timed out; response is NULL .LP .B GETDNS_CALLBACK_ERROR The requested action had an error; response is NULL .RE .HP 3 .I response A response object with the response data. This is described in the section titled "RESPONSE DATA" elsewhere in this manual page. The response object is part of the API's memory space, and will be freed by the API with the callback returns. .HP 3 .I userarg Identical to the userarg passed to the calling function. .HP 3 .I transaction_id The transaction identified assigned by the calling function, used to associate a DNS response to a specific DNS request. .LP To cancel an outstanding callback, use the following function. .RS 3 .br getdns_return_t .br .B getdns_cancel_callback (getdns_context_t context, getdns_transaction_t transaction_id) .RE .LP This causes the API to call the callback with a callback_type of GETDNS_CALLBACK_CANCEL if the callback for this transaction_id has not already been called. The callback code for cancellation should clean up any memory related to the identified call, such as to deallocate the memory for the userarg. getdns_cancel_callback() may return immediately, even before the callback finishes its work and returns. Calling getdns_cancel_callback() with a transaction_id of a callback that has already been called or an unknown transaction_id returns GETDNS_RETURN_UNKNOWN_TRANSACTION; otherwise, getdns_cancel_callback() returns GETDNS_RETURN_GOOD. .SH FILES .br /etc/hosts .br /etc/resolv.conf .SH EXAMPLES TBD .SH DIAGNOSTICS TBD .SH "SEE ALSO" .BR getdns_address (3), .BR getdns_bindata (3), .BR getdns_context (3), .BR getdns_convert (3), .BR getdns_dict (3), .BR getdns_general (3), .BR getdns_hostname (3), .BR getdns_list (3), .BR getdns_root_trust_anchor (3) .BR getdns_service (3) .BR getdns_validate_dnssec (3) .SH REPORTING PROBLEMS Bug reports should be sent to the getdns-bugs@getdns.net .SH AUTHORS The getdns API was documented by Paul Hoffman. This implementation of the getdns API was written by: .LP .RS 3 .br Craig Despeaux, Verisign Inc. .br John Dickinson, Sinodun .br Sara Dickinson, Sinodun .br Neel Goyal, Verisign Inc. .br Shumon Huque, Verisign Labs .br Olaf Kolkman, NLnet Labs .br Allison Mankin, Verisign Inc. - Verisign Labs. .br Melinda Shore, No Mountain Software LLC .br Willem Toorop, NLnet Labs .br Gowri Visweswaran, Verisign Labs .br Wouter Wijngaards, NLnet Labs .br Glen Wiley, Verisign Inc. .RE getdns-1.6.0/doc/manpgaltnames000077500000000000000000000034551362622307100163350ustar00rootroot00000000000000#!/bin/sh # generate list of alternate names for the specified man page # used to generate alternative man pages # # Copyright (c) 2013, Verisign, Inc., NLnet Labs # All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # * Neither the names of the copyright holders nor the # names of its contributors may be used to endorse or promote products # derived from this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE # DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY # DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES # (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; # LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND # ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [ ! -f $1 ] && exit 0 main=${1%.[0-9]} sect=${1#*.} sed -n '/.SH NAME/,/.SH LIBRARY/p' $1 |grep "^.B " | sed 's/.B //g' | sed 's/ *$//g' | sed 's/,//g' | grep -v "^$main\$" | sed "s/\$/.$sect/" getdns-1.6.0/getdns.pc.in000066400000000000000000000003511362622307100152200ustar00rootroot00000000000000prefix=@prefix@ exec_prefix=${prefix} libdir=${exec_prefix}/lib includedir=${prefix}/include Name: getdns Version: @GETDNS_VERSION@ Description: A modern asynchronous DNS library Libs: -L${libdir} -lgetdns Cflags: -I${includedir} getdns-1.6.0/getdns_ext_event.pc.in000066400000000000000000000003751362622307100173070ustar00rootroot00000000000000prefix=@prefix@ exec_prefix=${prefix} libdir=${exec_prefix}/lib includedir=${prefix}/include Name: getdns_ext_event Version: @GETDNS_VERSION@ Description: A modern asynchronous DNS library Libs: -L${libdir} -lgetdns_ext_event Cflags: -I${includedir} getdns-1.6.0/spec/000077500000000000000000000000001362622307100137365ustar00rootroot00000000000000getdns-1.6.0/spec/example/000077500000000000000000000000001362622307100153715ustar00rootroot00000000000000getdns-1.6.0/spec/example/example-all-functions.c000066400000000000000000000166461362622307100217610ustar00rootroot00000000000000#include #include #include #include #include #include #define UNUSED_PARAM(x) ((void)(x)) /* The return values */ getdns_return_t retregular; char * retcharstar; /* The args */ int boolarg; char * charstararg; char ** charstarptrarg; getdns_callback_t callbackarg; uint16_t regulararg; uint16_t *regularptrarg; getdns_transaction_t txidarg; getdns_transaction_t * txidptrarg; getdns_namespace_t *namespaceptrarg; getdns_resolution_t resolutionarg; getdns_redirects_t redirectsarg; getdns_transport_t transportarg; getdns_append_name_t appendnamearg; getdns_data_type * datatypeptrarg; getdns_bindata ** bindataptrarg; getdns_dict * dictarg; getdns_bindata * bindataarg; getdns_list * listarg; getdns_dict ** dictptrarg; getdns_list ** listptrarg; size_t sizetarg; size_t * sizetptrarg; getdns_context *contextarg = NULL; uint8_t uint8arg; uint16_t uint16arg; uint32_t uint32arg; uint8_t * uint8ptrarg; uint16_t * uint16ptrarg; uint32_t * uint32ptrarg; void * arrayarg; void * userarg; void * allocfunctionarg(size_t foo) {UNUSED_PARAM(foo); return NULL; } void * reallocfunctionarg(void* foo, size_t bar) {UNUSED_PARAM(foo); UNUSED_PARAM(bar); return NULL; } void deallocfunctionarg(void* foo) {UNUSED_PARAM(foo);} void * extendedallocfunctionarg(void* userarg, size_t foo) {UNUSED_PARAM(userarg); UNUSED_PARAM(foo); return NULL; } void * extendedreallocfunctionarg(void* userarg, void* foo, size_t bar) {UNUSED_PARAM(userarg); UNUSED_PARAM(foo); UNUSED_PARAM(bar); return NULL; } void extendeddeallocfunctionarg(void* userarg, void* foo) {UNUSED_PARAM(userarg); UNUSED_PARAM(foo);} void setcallbackfunctionarg(getdns_context *foo1, getdns_context_code_t foo2) {UNUSED_PARAM(foo1);UNUSED_PARAM(foo2);} int main() { retregular = getdns_general( contextarg, charstararg, uint16arg, dictarg, arrayarg, txidptrarg, callbackarg ); retregular = getdns_address( contextarg, charstararg, dictarg, arrayarg, txidptrarg, callbackarg ); retregular = getdns_hostname( contextarg, dictarg, dictarg, arrayarg, txidptrarg, callbackarg ); retregular = getdns_service( contextarg, charstararg, dictarg, arrayarg, txidptrarg, callbackarg ); retregular = getdns_context_create( &contextarg, boolarg ); retregular = getdns_context_create_with_memory_functions( &contextarg, boolarg, allocfunctionarg, reallocfunctionarg, deallocfunctionarg ); retregular = getdns_context_create_with_extended_memory_functions( &contextarg, boolarg, userarg, extendedallocfunctionarg, extendedreallocfunctionarg, extendeddeallocfunctionarg ); getdns_context_destroy( contextarg ); retregular = getdns_cancel_callback( contextarg, txidarg ); retregular = getdns_general_sync( contextarg, charstararg, uint16arg, dictarg, &dictarg ); retregular = getdns_address_sync( contextarg, charstararg, dictarg, &dictarg ); retregular = getdns_hostname_sync( contextarg, dictarg, dictarg, &dictarg ); retregular = getdns_service_sync( contextarg, charstararg, dictarg, &dictarg ); retregular = getdns_list_get_length(listarg, sizetptrarg); retregular = getdns_list_get_data_type(listarg, sizetarg, datatypeptrarg); retregular = getdns_list_get_dict(listarg, sizetarg, dictptrarg); retregular = getdns_list_get_list(listarg, sizetarg, listptrarg); retregular = getdns_list_get_bindata(listarg, sizetarg, bindataptrarg); retregular = getdns_list_get_int(listarg, sizetarg, uint32ptrarg); retregular = getdns_dict_get_names(dictarg, listptrarg); retregular = getdns_dict_get_data_type(dictarg, charstararg, datatypeptrarg); retregular = getdns_dict_get_dict(dictarg, charstararg, dictptrarg); retregular = getdns_dict_get_list(dictarg, charstararg, listptrarg); retregular = getdns_dict_get_bindata(dictarg, charstararg, bindataptrarg); retregular = getdns_dict_get_int(dictarg, charstararg, uint32ptrarg); listarg = getdns_list_create(); listarg = getdns_list_create_with_context(contextarg); listarg = getdns_list_create_with_memory_functions( allocfunctionarg, reallocfunctionarg, deallocfunctionarg ); listarg = getdns_list_create_with_extended_memory_functions( userarg, extendedallocfunctionarg, extendedreallocfunctionarg, extendeddeallocfunctionarg ); getdns_list_destroy(listarg); retregular = getdns_list_set_dict(listarg, sizetarg, dictarg); retregular = getdns_list_set_list(listarg, sizetarg, listarg); retregular = getdns_list_set_bindata(listarg, sizetarg, bindataarg); retregular = getdns_list_set_int(listarg, sizetarg, uint32arg); dictarg = getdns_dict_create(); dictarg = getdns_dict_create_with_context(contextarg); dictarg = getdns_dict_create_with_memory_functions( allocfunctionarg, reallocfunctionarg, deallocfunctionarg ); dictarg = getdns_dict_create_with_extended_memory_functions( userarg, extendedallocfunctionarg, extendedreallocfunctionarg, extendeddeallocfunctionarg ); getdns_dict_destroy(dictarg); retregular = getdns_dict_set_dict(dictarg, charstararg, dictarg); retregular = getdns_dict_set_list(dictarg, charstararg, listarg); retregular = getdns_dict_set_bindata(dictarg, charstararg, bindataarg); retregular = getdns_dict_set_int(dictarg, charstararg, uint32arg); retregular = getdns_dict_remove_name(dictarg, charstararg); retregular = getdns_convert_fqdn_to_dns_name( charstararg, bindataptrarg ); retregular = getdns_convert_dns_name_to_fqdn( bindataarg, charstarptrarg ); retcharstar = getdns_convert_ulabel_to_alabel( charstararg ); retcharstar = getdns_convert_alabel_to_ulabel( charstararg ); retregular = getdns_validate_dnssec( listarg, listarg, listarg ); retcharstar = getdns_pretty_print_dict( dictarg ); retcharstar = getdns_display_ip_address( bindataarg ); retregular = getdns_context_set_context_update_callback( contextarg, setcallbackfunctionarg ); retregular = getdns_context_set_resolution_type( contextarg, resolutionarg ); retregular = getdns_context_set_namespaces( contextarg, sizetarg, namespaceptrarg ); retregular = getdns_context_set_dns_transport( contextarg, transportarg ); retregular = getdns_context_set_limit_outstanding_queries( contextarg, uint16arg ); retregular = getdns_context_set_timeout( contextarg, uint16arg ); retregular = getdns_context_set_follow_redirects( contextarg, redirectsarg ); retregular = getdns_context_set_dns_root_servers( contextarg, listarg ); retregular = getdns_context_set_append_name( contextarg, appendnamearg ); retregular = getdns_context_set_suffix( contextarg, listarg ); retregular = getdns_context_set_dnssec_trust_anchors( contextarg, listarg ); retregular = getdns_context_set_dnssec_allowed_skew( contextarg, uint16arg ); retregular = getdns_context_set_upstream_recursive_servers( contextarg, listarg ); retregular = getdns_context_set_edns_maximum_udp_payload_size( contextarg, uint16arg ); retregular = getdns_context_set_edns_extended_rcode( contextarg, uint8arg ); retregular = getdns_context_set_edns_version( contextarg, uint8arg ); retregular = getdns_context_set_edns_do_bit( contextarg, uint8arg ); retregular = getdns_context_set_memory_functions( contextarg, allocfunctionarg, reallocfunctionarg, deallocfunctionarg ); retregular = getdns_context_set_extended_memory_functions( contextarg, userarg, extendedallocfunctionarg, extendedreallocfunctionarg, extendeddeallocfunctionarg ); return(0); } /* End of main() */ getdns-1.6.0/spec/example/example-reverse.c000066400000000000000000000072501362622307100206450ustar00rootroot00000000000000#include #include #include #include /* Set up the callback function, which will also do the processing of the results */ void callback(getdns_context *context, getdns_callback_type_t callback_type, getdns_dict *response, void *userarg, getdns_transaction_t transaction_id) { getdns_return_t r; /* Holder for all function returns */ getdns_list *answer; size_t n_answers, i; (void) context; (void) userarg; /* unused parameters */ switch(callback_type) { case GETDNS_CALLBACK_CANCEL: printf("Transaction with ID %"PRIu64" was cancelled.\n", transaction_id); return; case GETDNS_CALLBACK_TIMEOUT: printf("Transaction with ID %"PRIu64" timed out.\n", transaction_id); return; case GETDNS_CALLBACK_ERROR: printf("An error occurred for transaction ID %"PRIu64".\n", transaction_id); return; default: break; } assert( callback_type == GETDNS_CALLBACK_COMPLETE ); if ((r = getdns_dict_get_list(response, "/replies_tree/0/answer", &answer))) fprintf(stderr, "Could not get \"answer\" section from first reply in the response"); else if ((r = getdns_list_get_length(answer, &n_answers))) fprintf(stderr, "Could not get replies_tree\'s length"); else for (i = 0; i < n_answers && r == GETDNS_RETURN_GOOD; i++) { getdns_dict *rr; getdns_bindata *dname; char *dname_str; if ((r = getdns_list_get_dict(answer, i, &rr))) fprintf(stderr, "Could not get rr %zu from answer section", i); else if (getdns_dict_get_bindata(rr, "/rdata/ptrdname", &dname)) continue; /* Not a PTR */ else if ((r = getdns_convert_dns_name_to_fqdn(dname, &dname_str))) fprintf(stderr, "Could not convert PTR dname to string"); else { printf("The dname is %s\n", dname_str); free(dname_str); } } if (r) { assert( r != GETDNS_RETURN_GOOD ); fprintf(stderr, ": %d\n", r); } getdns_dict_destroy(response); } int main() { getdns_return_t r; /* Holder for all function returns */ getdns_context *context = NULL; struct event_base *event_base = NULL; getdns_bindata address_type = { 4, (void *)"IPv4" }; getdns_bindata address_data = { 4, (void *)"\x08\x08\x08\x08" }; getdns_dict *address = NULL; getdns_dict *extensions = NULL; /* Could add things here to help identify this call */ char *userarg = NULL; getdns_transaction_t transaction_id; if ((r = getdns_context_create(&context, 1))) fprintf(stderr, "Trying to create the context failed"); else if (!(event_base = event_base_new())) fprintf(stderr, "Trying to create the event base failed.\n"); else if ((r = getdns_extension_set_libevent_base(context, event_base))) fprintf(stderr, "Setting the event base failed"); else if (!(address = getdns_dict_create())) fprintf(stderr, "Could not create address dict.\n"); else if ((r = getdns_dict_set_bindata(address, "address_type", &address_type))) fprintf(stderr, "Could not set address_type in address dict.\n"); else if ((r = getdns_dict_set_bindata(address, "address_data", &address_data))) fprintf(stderr, "Could not set address_data in address dict.\n"); else if ((r = getdns_hostname( context, address, extensions , userarg, &transaction_id, callback))) fprintf(stderr, "Error scheduling asynchronous request"); else if (event_base_dispatch(event_base) < 0) fprintf(stderr, "Error dispatching events\n"); /* Clean up */ if (event_base) event_base_free(event_base); if (context) getdns_context_destroy(context); /* Assuming we get here, leave gracefully */ exit(EXIT_SUCCESS); } getdns-1.6.0/spec/example/example-simple-answers.c000066400000000000000000000070021362622307100221360ustar00rootroot00000000000000#include #include #include #include /* Set up the callback function, which will also do the processing of the results */ void callback(getdns_context *context, getdns_callback_type_t callback_type, getdns_dict *response, void *userarg, getdns_transaction_t transaction_id) { getdns_return_t r; /* Holder for all function returns */ uint32_t status; getdns_bindata *address_data; char *first = NULL, *second = NULL; (void) context; /* unused parameter */ printf( "Callback for query \"%s\" with request ID %"PRIu64".\n" , (char *)userarg, transaction_id ); switch(callback_type) { case GETDNS_CALLBACK_CANCEL: printf("Transaction with ID %"PRIu64" was cancelled.\n", transaction_id); return; case GETDNS_CALLBACK_TIMEOUT: printf("Transaction with ID %"PRIu64" timed out.\n", transaction_id); return; case GETDNS_CALLBACK_ERROR: printf("An error occurred for transaction ID %"PRIu64".\n", transaction_id); return; default: break; } assert( callback_type == GETDNS_CALLBACK_COMPLETE ); if ((r = getdns_dict_get_int(response, "status", &status))) fprintf(stderr, "Could not get \"status\" from response"); else if (status != GETDNS_RESPSTATUS_GOOD) fprintf(stderr, "The search had no results, and a return value of %"PRIu32".\n", status); else if ((r = getdns_dict_get_bindata(response, "/just_address_answers/0/address_data", &address_data))) fprintf(stderr, "Could not get first address"); else if (!(first = getdns_display_ip_address(address_data))) fprintf(stderr, "Could not convert first address to string\n"); else if ((r = getdns_dict_get_bindata(response, "/just_address_answers/1/address_data", &address_data))) fprintf(stderr, "Could not get second address"); else if (!(second = getdns_display_ip_address(address_data))) fprintf(stderr, "Could not convert second address to string\n"); if (first) { printf("The address is %s\n", first); free(first); } if (second) { printf("The address is %s\n", second); free(second); } if (r) { assert( r != GETDNS_RETURN_GOOD ); fprintf(stderr, ": %d\n", r); } getdns_dict_destroy(response); } int main() { getdns_return_t r; /* Holder for all function returns */ getdns_context *context = NULL; struct event_base *event_base = NULL; getdns_dict *extensions = NULL; char *query_name = "www.example.com"; /* Could add things here to help identify this call */ char *userarg = query_name; getdns_transaction_t transaction_id; if ((r = getdns_context_create(&context, 1))) fprintf(stderr, "Trying to create the context failed"); else if (!(event_base = event_base_new())) fprintf(stderr, "Trying to create the event base failed.\n"); else if ((r = getdns_extension_set_libevent_base(context, event_base))) fprintf(stderr, "Setting the event base failed"); else if ((r = getdns_address( context, query_name, extensions , userarg, &transaction_id, callback))) fprintf(stderr, "Error scheduling asynchronous request"); else { printf("Request with transaction ID %"PRIu64" scheduled.\n", transaction_id); if (event_base_dispatch(event_base) < 0) fprintf(stderr, "Error dispatching events\n"); } /* Clean up */ if (event_base) event_base_free(event_base); if (context) getdns_context_destroy(context); /* Assuming we get here, leave gracefully */ exit(EXIT_SUCCESS); } getdns-1.6.0/spec/example/example-synchronous.c000066400000000000000000000037131362622307100215640ustar00rootroot00000000000000#include #include #include int main() { getdns_return_t r; /* Holder for all function returns */ getdns_context *context = NULL; getdns_dict *response = NULL; getdns_dict *extensions = NULL; getdns_bindata *address_data; char *first = NULL, *second = NULL; /* Create the DNS context for this call */ if ((r = getdns_context_create(&context, 1))) fprintf(stderr, "Trying to create the context failed"); else if (!(extensions = getdns_dict_create())) fprintf(stderr, "Could not create extensions dict.\n"); else if ((r = getdns_dict_set_int(extensions, "return_both_v4_and_v6", GETDNS_EXTENSION_TRUE))) fprintf(stderr, "Trying to set an extension do both IPv4 and IPv6 failed"); else if ((r = getdns_general_sync(context, "example.com", GETDNS_RRTYPE_A, extensions, &response))) fprintf(stderr, "Error scheduling synchronous request"); else if ((r = getdns_dict_get_bindata(response, "/just_address_answers/0/address_data", &address_data))) fprintf(stderr, "Could not get first address"); else if (!(first = getdns_display_ip_address(address_data))) fprintf(stderr, "Could not convert first address to string\n"); else if ((r = getdns_dict_get_bindata(response, "/just_address_answers/1/address_data", &address_data))) fprintf(stderr, "Could not get second address"); else if (!(second = getdns_display_ip_address(address_data))) fprintf(stderr, "Could not convert second address to string\n"); if (first) { printf("The address is %s\n", first); free(first); } if (second) { printf("The address is %s\n", second); free(second); } /* Clean up */ if (response) getdns_dict_destroy(response); if (extensions) getdns_dict_destroy(extensions); if (context) getdns_context_destroy(context); if (r) { assert( r != GETDNS_RETURN_GOOD ); fprintf(stderr, ": %d\n", r); exit(EXIT_FAILURE); } /* Assuming we get here, leave gracefully */ exit(EXIT_SUCCESS); } getdns-1.6.0/spec/example/example-tree.c000066400000000000000000000076221362622307100201340ustar00rootroot00000000000000#include #include #include #include /* Set up the callback function, which will also do the processing of the results */ void callback(getdns_context *context, getdns_callback_type_t callback_type, getdns_dict *response, void *userarg, getdns_transaction_t transaction_id) { getdns_return_t r; /* Holder for all function returns */ getdns_list *replies_tree; size_t n_replies, i; (void) context; (void) userarg; /* unused parameters */ switch(callback_type) { case GETDNS_CALLBACK_CANCEL: printf("Transaction with ID %"PRIu64" was cancelled.\n", transaction_id); return; case GETDNS_CALLBACK_TIMEOUT: printf("Transaction with ID %"PRIu64" timed out.\n", transaction_id); return; case GETDNS_CALLBACK_ERROR: printf("An error occurred for transaction ID %"PRIu64".\n", transaction_id); return; default: break; } assert( callback_type == GETDNS_CALLBACK_COMPLETE ); if ((r = getdns_dict_get_list(response, "replies_tree", &replies_tree))) fprintf(stderr, "Could not get \"replies_tree\" from response"); else if ((r = getdns_list_get_length(replies_tree, &n_replies))) fprintf(stderr, "Could not get replies_tree\'s length"); else for (i = 0; i < n_replies && r == GETDNS_RETURN_GOOD; i++) { getdns_dict *reply; getdns_list *answer; size_t n_answers, j; if ((r = getdns_list_get_dict(replies_tree, i, &reply))) fprintf(stderr, "Could not get address %zu from just_address_answers", i); else if ((r = getdns_dict_get_list(reply, "answer", &answer))) fprintf(stderr, "Could not get \"address_data\" from address"); else if ((r = getdns_list_get_length(answer, &n_answers))) fprintf(stderr, "Could not get answer section\'s length"); else for (j = 0; j < n_answers && r == GETDNS_RETURN_GOOD; j++) { getdns_dict *rr; getdns_bindata *address = NULL; if ((r = getdns_list_get_dict(answer, j, &rr))) fprintf(stderr, "Could net get rr %zu from answer section", j); else if (getdns_dict_get_bindata(rr, "/rdata/ipv4_address", &address) == GETDNS_RETURN_GOOD) printf("The IPv4 address is "); else if (getdns_dict_get_bindata(rr, "/rdata/ipv6_address", &address) == GETDNS_RETURN_GOOD) printf("The IPv6 address is "); if (address) { char *address_str; if (!(address_str = getdns_display_ip_address(address))) { fprintf(stderr, "Could not convert second address to string"); r = GETDNS_RETURN_MEMORY_ERROR; break; } printf("%s\n", address_str); free(address_str); } } } if (r) { assert( r != GETDNS_RETURN_GOOD ); fprintf(stderr, ": %d\n", r); } getdns_dict_destroy(response); } int main() { getdns_return_t r; /* Holder for all function returns */ getdns_context *context = NULL; struct event_base *event_base = NULL; getdns_dict *extensions = NULL; char *query_name = "www.example.com"; /* Could add things here to help identify this call */ char *userarg = NULL; getdns_transaction_t transaction_id; if ((r = getdns_context_create(&context, 1))) fprintf(stderr, "Trying to create the context failed"); else if (!(event_base = event_base_new())) fprintf(stderr, "Trying to create the event base failed.\n"); else if ((r = getdns_extension_set_libevent_base(context, event_base))) fprintf(stderr, "Setting the event base failed"); else if ((r = getdns_address( context, query_name, extensions , userarg, &transaction_id, callback))) fprintf(stderr, "Error scheduling asynchronous request"); else if (event_base_dispatch(event_base) < 0) fprintf(stderr, "Error dispatching events\n"); /* Clean up */ if (event_base) event_base_free(event_base); if (context) getdns_context_destroy(context); /* Assuming we get here, leave gracefully */ exit(EXIT_SUCCESS); } getdns-1.6.0/spec/example/getdns_core_only.h000066400000000000000000000030611362622307100210770ustar00rootroot00000000000000/* * Copyright (c) 2013, NLNet Labs, Verisign, Inc. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * Neither the names of the copyright holders nor the * names of its contributors may be used to endorse or promote products * derived from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include getdns-1.6.0/spec/example/getdns_libevent.h000066400000000000000000000036271362622307100207260ustar00rootroot00000000000000/* * Copyright (c) 2013, NLNet Labs, Verisign, Inc. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * Neither the names of the copyright holders nor the * names of its contributors may be used to endorse or promote products * derived from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL Verisign, Inc. BE LIABLE FOR ANY * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #include "config.h" #include #include #ifdef HAVE_EVENT2_EVENT_H #include #else #include #endif #ifndef HAVE_EVENT_BASE_FREE #define event_base_free(x) /* nop */ #endif #ifndef HAVE_EVENT_BASE_NEW #define event_base_new event_init #endif #ifndef HAVE_U_CHAR typedef unsigned char u_char; #endif getdns-1.6.0/spec/index.html000066400000000000000000004637771362622307100157630ustar00rootroot00000000000000 DNS API Description

Description of the getdns API

Originally edited by Paul Hoffman

Currently maintained by the getdns team

Document version: "getdns December 2015"

This document describes a modern asynchronous DNS API. This new API is intended to be useful to application developers and operating system distributors as a way of making all types of DNS information easily available in many types of programs. The major features of this new API are:

  • Full support for event-driven programming
  • Supports DNSSEC in multiple ways
  • Mirroring of the resolution in getaddrinfo()
  • Easily supports all RRtypes, even those yet to be defined

There is more background into the design and future goals of this API later in this document.

This document was discussed on the getdns-api mailing list; future versions of the API might be discussed there as well. (If you want to contact the editors off-list, please send mail to team@getdnsapi.net.)

1. The getdns Async Functions

The API has four async functions:

  • getdns_address for doing getaddrinfo()-like address lookups
  • getdns_hostname for doing getnameinfo()-like name lookups
  • getdns_service for getting results from SRV lookups
  • getdns_general for looking up any type of DNS record

1.1 getdns_general()

getdns_return_t getdns_general( getdns_context *context, const char *name, uint16_t request_type, getdns_dict *extensions, void *userarg, getdns_transaction_t *transaction_id, getdns_callback_t callbackfn );

context

A pointer to the DNS context that is to be used with this call. DNS contexts are described later in this document. Note that a context must be created before calling the function.

*name

This is a null-terminted string consisting of an ASCII-based domain name to be looked up. The values here follow the rules in section 2.1 of RFC 4343 to allow non-ASCII octets and special characters in labels.

request_type

Specifies the RRtype for the query; the RRtype numbers are listed in the IANA registry. For example, to get the NS records, request_type would be 2. The API also has defined macros for most of the RRtypes by name; the definition names all start with "GETDNS_RRTYPE_". For example, to get the NS records, you can also set the request_type to GETDNS_RRTYPE_NS. (The full list of request types is always here.)

*extensions

Specifies the extensions for this request; the value may be NULL if there are no extensions. See the section below for information on how to specify the extensions used for a request.

*userarg

A void* that is passed to the function, which the function returns to the callback function untouched. userarg can be used by the callback function for any user-specific data needed. This can be NULL.

*transaction_id

A pointer to a value that is filled in by the function to identify the callback being made. This pointer can be NULL, in which case it is ignored and no value is assigned. The getdns_cancel_callback() function uses the transaction_id to determine which callback is to be cancelled. If the function fails, transaction_id is set to 0.

*callbackfn

A pointer to a callback function that is defined by the application. Typically, the callback function will do all the processing on the results from the API. The parameters of the callback are defined below. This really needs to be a pointer to a function (and not something like NULL); otherwise, the results are unpredictable.

The async getdns functions return GETDNS_RETURN_GOOD if the call was properly formatted. It returns GETDNS_RETURN_BAD_DOMAIN_NAME if the API determines that the name passed to the function was bad, GETDNS_RETURN_BAD_CONTEXT if the context has internal deficiencies, GETDNS_RETURN_NO_SUCH_EXTENSION if one or more extensions do not exist, or GETDNS_RETURN_EXTENSION_MISFORMAT if the contents of one or more of the extensions is incorrect. All of the return values are given later in this document.

1.2 getdns_address()

getdns_return_t getdns_address( getdns_context *context, const char *name, getdns_dict *extensions, void *userarg, getdns_transaction_t *transaction_id, getdns_callback_t callbackfn );

There are three critical differences between getdns_address() and getdns_general() beyond the missing request_type argument:

  • In getdns_address(), the name argument can only take a host name.
  • You do not need to include a return_both_v4_and_v6 extension with the call in getdns_address(): it will always return both IPv4 and IPv6 addresses.
  • getdns_address() always uses all of namespaces from the context (to better emulate getaddrinfo()), while getdns_general() only uses the DNS namespace.

1.3 getdns_hostname()

getdns_return_t getdns_hostname( getdns_context *context, getdns_dict *address, getdns_dict *extensions, void *userarg, getdns_transaction_t *transaction_id, getdns_callback_t callbackfn );

The address is given as a getdns_dict data structure (defined below). The list must have two names: address_type (whose value is a bindata; it is currently either "IPv4" or "IPv6" (which are case-sensitive)) and address_data (whose value is a bindata).

1.4 getdns_service()

getdns_return_t getdns_service( getdns_context *context, const char *name, getdns_dict *extensions, void *userarg, getdns_transaction_t *transaction_id, getdns_callback_t callbackfn );

name must be a domain name for an SRV lookup; the call returns the relevant SRV information for the name.

1.5 Callback Functions for getdns

A call to the async getdns functions typically returns before any network or file I/O occurs. After the API marshalls all the needed information, it calls the callback function that was passed by the application. The callback function might be called at any time, even before the calling function has returned. The API guarantees that the callback will be called exactly once unless the calling function returned an error, in which case the callback function is never called.

The getdns calling function calls the callback with the parameters defined as follows:

typedef void (*getdns_callback_t)( getdns_context *context, getdns_callback_type_t callback_type, getdns_dict *response, void *userarg, getdns_transaction_t transaction_id);

context

The DNS context that was used in the calling function. See below for a description of the basic use of contexts, and later for more advanced use.

callback_type

Supplies the reason for the callback. See below for the codes and reasons.

*response

A response object with the response data. This is described below. The application is responsible for cleaning up the response object with getdns_dict_destroy.

*userarg

Identical to the *userarg passed to the calling function.

transaction_id

The transaction identifier that was assigned by the calling function.

The following are the values for callback_type.

GETDNS_CALLBACK_COMPLETE

The response has the requested data in it

GETDNS_CALLBACK_CANCEL

The calling program cancelled the callback; response is NULL

GETDNS_CALLBACK_TIMEOUT

The requested action timed out; response is filled in with empty structures

GETDNS_CALLBACK_ERROR

The requested action had an error; response is NULL

1.6 Setting Up The DNS Context

Calls to getdns functions require a DNS context, which is a group of API settings that affect how DNS calls are made. For most applications, a default context is sufficient.

To create a new DNS context, use the function:

getdns_return_t getdns_context_create( getdns_context **context, int set_from_os );

The call to getdns_context_create immediately returns a context that can be used with other API calls; that context contains the API's default values. Most applications will want set_from_os set to 1.

getdns_return_t getdns_context_create_with_memory_functions( getdns_context **context, int set_from_os, void *(*malloc)(size_t), void *(*realloc)(void *, size_t), void (*free)(void *) ); getdns_return_t getdns_context_create_with_extended_memory_functions( getdns_context **context, int set_from_os, void *userarg, void *(*malloc)(void *userarg, size_t), void *(*realloc)(void *userarg, void *, size_t), void (*free)(void *userarg, void *) );

To clean up the context, including cleaning up all outstanding transactions that were called using this context, use the function:

void getdns_context_destroy( getdns_context *context );

When getdns_context_destroy() returns, the application knows that all outstanding transactions associated with this context will have been called; callbacks that had not been called before getdns_context_destroy() was called will be called with a callback_type of GETDNS_CALLBACK_CANCEL. getdns_context_destroy() returns after all of the needed cleanup is done and callbacks are made.

1.7 Canceling a Callback

To cancel an outstanding callback, use the following function.

getdns_return_t getdns_cancel_callback( getdns_context *context, getdns_transaction_t transaction_id );

This causes the API to call the callback with a callback_type of GETDNS_CALLBACK_CANCEL if the callback for this transaction_id has not already been called. This will cancel the callback regardless of what the original call was doing (such as in the middle of a DNS request, while DNSSEC validation is happening, and so on). The callback code for cancellation should clean up any memory related to the identified call, such as to deallocate the memory for the userarg. getdns_cancel_callback() may return immediately, even before the callback finishes its work and returns. Calling getdns_cancel_callback() with a transaction_id of a callback that has already been called or an unknown transaction_id returns GETDNS_RETURN_UNKNOWN_TRANSACTION; otherwise, getdns_cancel_callback() returns GETDNS_RETURN_GOOD.

1.8 Event-driven Programs

Event-driven programs (sometimes called "async programs") require an event base and event loop (among other things). Different event libraries have different structures or the event base. Because of this, there is no standard method to set the event base in the DNS API: those are all added as extensions. The API is distributed as a core package and one or more sets of extensions to align with event libraries. It is mandatory to use one of the extension functions to set the event base in the DNS context; this is required before calling any event-driven calls like the getdns functions.

Each implementation of the DNS API will specify an extension function that tells the DNS context which event base is being used. For example, one implementation of this API that uses the libevent event library might name this function "getdns_extension_set_libevent_base()" while another might name it "getdns_extension_set_eventbase_for_libevent()"; the two extension functions could have very different calling patterns and return values. Thus, the application developer must read the API documentation (not just this design document) in order to determine what extension function to use to tell the API the event base to use.

The structure of a typical event-driven application might look like the following pseudocode. The code in italics is specific to the event mechanism.

Includes for one or more regular C libraries
An include for the getdns library specific to the event library you use
Definition of your callback function
    Get the DNS data from the allocated pointer
    Process that data
    Check for errors
Definition of main()
    Create context
    Set up your event base
    Point the context to your event base
    Set up the getdns call arguments
    Make the getdns call
    Check if the getdns return is good
    Destroy the context
    Exit

The API does not have direct support for a polling interface. Instead, the callback interface is specifically designed to allow an application that wants to process results in polling instead of in callbacks to be able to create its own polling interface fairly trivially. Such a program would create a data structure for the calls, including their transaction_id and userarg. The userarg could be the polling data structure or have a pointer to it. The application would have just one callback function for all requests, and that function would copy the response into application memory, update the data structure based on the transaction_id index, and return from the callback. The polling code could then check the data structure for any updates at its leisure.

1.9 Calling the API Synchronously (Without Events)

There are functions parallel to the four getdns async functions, except that there is no callback. That is, when an application calls one of these synchronous functions, the API gathers all the required information and then returns the result. The value returned is exactly the same as the response returned in the callback if you had used the async version of the function.

getdns_return_t getdns_general_sync( getdns_context *context, const char *name, uint16_t request_type, getdns_dict *extensions, getdns_dict **response );
getdns_return_t getdns_address_sync( getdns_context *context, const char *name, getdns_dict *extensions, getdns_dict **response );
getdns_return_t getdns_hostname_sync( getdns_context *context, getdns_dict *address, getdns_dict *extensions, getdns_dict **response );
getdns_return_t getdns_service_sync( getdns_context *context, const char *name, getdns_dict *extensions, getdns_dict **response );

When you are done with the data in the response, use the following function so that the API can free the memory from its internal pool.

void getdns_dict_destroy( getdns_dict *response );

2. Data structures in the API

The API returns data structures. The data structure is not a representational language like JSON: it is really just a data structure. Data structures can have four types of members:

  • list is an ordered list, like JSON and Python lists. The members of the list can be any of the four data types.
  • dict is a name-value pair, like a JSON object or Python dict. The name is a string literal, and the value can be any of the four data types. The order of the name-value pairs in a dict is not important.
  • int is an integer compatible with uint32_t.
  • bindata is a struct to hold binary data. It is defined as { size_t size; uint8_t *binary_stuff; }.

The API comes with helper functions to get data from the list and dict data types:

/* Lists: get the length, get the data_type of the value at a given position, and get the data at a given position */ getdns_return_t getdns_list_get_length(const getdns_list *list, size_t *answer); getdns_return_t getdns_list_get_data_type(const getdns_list *list, size_t index, getdns_data_type *answer); getdns_return_t getdns_list_get_dict(const getdns_list *list, size_t index, getdns_dict **answer); getdns_return_t getdns_list_get_list(const getdns_list *list, size_t index, getdns_list **answer); getdns_return_t getdns_list_get_bindata(const getdns_list *list, size_t index, getdns_bindata **answer); getdns_return_t getdns_list_get_int(const getdns_list *list, size_t index, uint32_t *answer); /* Dicts: get the list of names, get the data_type of the value at a given name, and get the data at a given name */ getdns_return_t getdns_dict_get_names(const getdns_dict *dict, getdns_list **answer); getdns_return_t getdns_dict_get_data_type(const getdns_dict *dict, const char *name, getdns_data_type *answer); getdns_return_t getdns_dict_get_dict(const getdns_dict *dict, const char *name, getdns_dict **answer); getdns_return_t getdns_dict_get_list(const getdns_dict *dict, const char *name, getdns_list **answer); getdns_return_t getdns_dict_get_bindata(const getdns_dict *dict, const char *name, getdns_bindata **answer); getdns_return_t getdns_dict_get_int(const getdns_dict *dict, const char *name, uint32_t *answer);

All of these helper getter functions return GETDNS_RETURN_GOOD if the call is successful. The list functions will return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index argument is out of range; the dict functions will return GETDNS_RETURN_NO_SUCH_DICT_NAME if the name argument doesn't exist in the dict. The functions also return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the requested data type doesn't match the contents of the indexed argument or name.

This document uses graphical representations of data structures. It is important to note that this is only a graphical representation; the brackets, commas, quotation marks, comments, and so on are not part of the data. Also, this document uses macro names instead of some of the int arguments; of course, the data structures have the actual int in them.

The getdns_dict_get_names helper function creates a newly created list containing the names in a dict. The caller is responsible for disposing this list.

The helper getter functions return references to getdns_dict, getdns_list and getdns_bindata data structures. The user must not directly destroy these retrieved "child" data structures; instead, they will automatically be destroyed when the containing "parent" data structure is destroyed. Because of this, retrieved "child" data structures cannot be used any more after the containing "parent" data structure has been destroyed.

When the name parameter to the getdns_dict_get_ functions, starts with a '/' (%x2F) character, it is interpreted as a JSON Pointer as described in RFC 6901, and will then be used to dereference the nested data structures to get to the requested data type.

2.1 Creating Data Structures

Some of the features of the API require that you create your own data structures to be used in arguments passed to the API. For example, if you want to use any extensions for the calling functions, you need to create a dict. The requisite functions are:

/* Lists: create, destroy, and set the data at a given position */ getdns_list * getdns_list_create(); getdns_list * getdns_list_create_with_context( getdns_context *context ); getdns_list * getdns_list_create_with_memory_functions( void *(*malloc)(size_t), void *(*realloc)(void *, size_t), void (*free)(void *) ); getdns_list * getdns_list_create_with_extended_memory_functions( void *userarg, void *(*malloc)(void *userarg, size_t), void *(*realloc)(void *userarg, void *, size_t), void (*free)(void *userarg, void *) ); void getdns_list_destroy(getdns_list *list); getdns_return_t getdns_list_set_dict(getdns_list *list, size_t index, const getdns_dict *child_dict); getdns_return_t getdns_list_set_list(getdns_list *list, size_t index, const getdns_list *child_list); getdns_return_t getdns_list_set_bindata(getdns_list *list, size_t index, const getdns_bindata *child_bindata); getdns_return_t getdns_list_set_int(getdns_list *list, size_t index, uint32_t child_uint32); /* Dicts: create, destroy, and set the data at a given name */ getdns_dict * getdns_dict_create(); getdns_dict * getdns_dict_create_with_context( getdns_context *context ); getdns_dict * getdns_dict_create_with_memory_functions( void *(*malloc)(size_t), void *(*realloc)(void *, size_t), void (*free)(void *) ); getdns_dict * getdns_dict_create_with_extended_memory_functions( void *userarg, void *(*malloc)(void *userarg, size_t), void *(*realloc)(void *userarg, void *, size_t), void (*free)(void *userarg, void *) ); void getdns_dict_destroy(getdns_dict *dict); getdns_return_t getdns_dict_set_dict(getdns_dict *dict, const char *name, const getdns_dict *child_dict); getdns_return_t getdns_dict_set_list(getdns_dict *dict, const char *name, const getdns_list *child_list); getdns_return_t getdns_dict_set_bindata(getdns_dict *dict, const char *name, const getdns_bindata *child_bindata); getdns_return_t getdns_dict_set_int(getdns_dict *dict, const char *name, uint32_t child_uint32); getdns_return_t getdns_dict_remove_name(getdns_dict *dict, const char *name);

Lists are extended with the getdns_list_set_ calls with the index set to the size of the list (such as 0 for an empty list). Dicts are extended with the getdns_dict_set_ calls with the name set to a name that does not yet exist. Name-value pairs are removed with getdns_dict_remove_name().

These helper setter functions return GETDNS_RETURN_GOOD if the call is successful. The functions return GETDNS_RETURN_WRONG_TYPE_REQUESTED if the requested data type doesn't match the contents of the indexed argument or name. The list functions will return GETDNS_RETURN_NO_SUCH_LIST_ITEM if the index argument is higher than the length of the list. getdns_dict_remove_name() will return GETDNS_RETURN_NO_SUCH_DICT_NAME if the name argument doesn't exist in the dict.

The helper setter functions store copies of the given "child" values. It is the responsibility of the caller to dispose of the original values.

When the name parameter to the getdns_dict_set_ functions, starts with a '/' (%x2F) character, it is interpreted as a JSON Pointer as described in RFC 6901, and will then be used to dereference the nested data structures to set the given value at the specified name or list index.

3. Extensions

Extensions are dict data structures. The names in the dict are the names of the extensions. The definition of each extension describes the value associated with the name. For most extensions, it is an on-off boolean, and the value is GETDNS_EXTENSION_TRUE. (There is not currently a good reason to specify an extension name and give it a value of GETDNS_EXTENSION_FALSE, but that is allowed by the API.)

For example, to create a dict for extensions and specify the extension to only return results that have been validated with DNSSEC, you might use:

/* . . . */
getdns_dict * extensions = getdns_dict_create();
ret = getdns_dict_set_int(extensions, "dnssec_return_only_secure", GETDNS_EXTENSION_TRUE);
/* . . . Do some processing with the extensions and results . . . */
/* Remember to clean up memory*/
getdns_dict_destroy(extensions);

The extensions described in this section are are:

  • dnssec_return_status
  • dnssec_return_only_secure
  • dnssec_return_validation_chain
  • return_both_v4_and_v6
  • add_opt_parameters
  • add_warning_for_bad_dns
  • specify_class
  • return_call_reporting

3.1 Extensions for DNSSEC

If an application wants the API to do DNSSEC validation for a request, it must set one or more DNSSEC-related extensions. Note that the default is for none of these extensions to be set and the API will not perform DNSSEC. Note that getting DNSSEC results can take longer in a few circumstances.

To return the DNSSEC status for each DNS record in the replies_tree list, use the dnssec_return_status extension. The extension's value (an int) is set to GETDNS_EXTENSION_TRUE to cause the returned status to have the name dnssec_status (an int) added to the other names in the record's dict ("header", "question", and so on). The values for that name are GETDNS_DNSSEC_SECURE, GETDNS_DNSSEC_BOGUS, GETDNS_DNSSEC_INDETERMINATE, and GETDNS_DNSSEC_INSECURE. Thus, a reply might look like:

    {     # This is the first reply
      "dnssec_status": GETDNS_DNSSEC_INDETERMINATE,
      "header": { "id": 23456, "qr": 1, "opcode": 0, ... },
      . . .

If instead of returning the status, you want to only see secure results, use the dnssec_return_only_secure extension. The extension's value (an int) is set to GETDNS_EXTENSION_TRUE to cause only records that the API can validate as secure with DNSSEC to be returned in the replies_tree and replies_full lists. No additional names are added to the dict of the record; the change is that some records might not appear in the results. When this context option is set, if the API receives DNS replies but none are determined to be secure, the error code at the top level of the response object is GETDNS_RESPSTATUS_NO_SECURE_ANSWERS.

Applications that want to do their own validation will want to have the DNSSEC-related records for a particular response. Use the dnssec_return_validation_chain extension. The extension's value (an int) is set to GETDNS_EXTENSION_TRUE to cause a set of additional DNSSEC-related records needed for validation to be returned in the response object. This set comes as validation_chain (a list) at the top level of the response object. This list includes all resource record dicts for all the resource records (DS, DNSKEY and their RRSIGs) that are needed to perform the validation from the root up. Thus, a reply might look like:

{     # This is the response object
  "validation_chain":
  [ { "name": <bindata for .>,
      "type": GETDNS_RRTYPE_DNSKEY,
      "rdata": { "flags": 256, . . . },
      . . . 
    },
    { "name": <bindata for .>,
      "type": GETDNS_RRTYPE_DNSKEY,
      "rdata": { "flags": 257, . . . },
      . . .
    },
    { "name": <bindata for .>,
      "type": GETDNS_RRTYPE_RRSIG,
      "rdata": { "signers_name": <bindata for .>,
                 "type_covered": GETDNS_RRTYPE_DNSKEY,
                 . . .
               },
    },
    { "name": <bindata for com.>,
      "type": GETDNS_RRTYPE_DS,
      . . .
    },
    { "name": <bindata for com.>,
      "type": GETDNS_RRTYPE_RRSIG
      "rdata": { "signers_name": <bindata for .>,
                 "type_covered": GETDNS_RRTYPE_DS,
                 . . .
               },
      . . .
    },
    { "name": <bindata for com.>,
      "type": GETDNS_RRTYPE_DNSKEY
      "rdata": { "flags": 256, . . . },
      . . .
    },
    { "name": <bindata for com.>,
      "type": GETDNS_RRTYPE_DNSKEY
      "rdata": { "flags": 257, . . . },
      . . .
    },
    { "name": <bindata for com.>,
      "type": GETDNS_RRTYPE_RRSIG
      "rdata": { "signers_name": <bindata for com.>,
                 "type_covered": GETDNS_RRTYPE_DNSKEY,
                 . . .
               },
      . . .
    },
    { "name": <bindata for example.com.>,
      "type": GETDNS_RRTYPE_DS,
      . . .
    },
    { "name": <bindata for example.com.>,
      "type": GETDNS_RRTYPE_RRSIG
      "rdata": { "signers_name": <bindata for com.>,
                 "type_covered": GETDNS_RRTYPE_DS,
                 . . .
               },
      . . .
    },
    { "name": <bindata for example.com.>,
      "type": GETDNS_RRTYPE_DNSKEY
      "rdata": { "flags": 257, ... },
      . . .
    },
    . . .
  ]
  "replies_tree":
  [
  . . .

Implementations not capable of performing DNSSEC in stub resolution mode may indicate this by not performing a request and instead return an error of GETDNS_RETURN_DNSSEC_WITH_STUB_DISALLOWED when using a context in which stub resolution is set, and having any of the dnssec_return_status, dnssec_return_only_secure, or dnssec_return_validation_chain extensions specified.

3.2 Returning Both IPv4 and IPv6 Responses

Many applications want to get both IPv4 and IPv6 addresses in a single call so that the results can be processed together. The getdns_address and getdns_address_sync functions are able to do this automatically. If you are using the getdns_general or getdns_general_sync function, you can enable this with the return_both_v4_and_v6 extension. The extension's value (an int) is set to GETDNS_EXTENSION_TRUE to cause the results to be the lookup of either A or AAAA records to include any A and AAAA records for the queried name (otherwise, the extension does nothing). These results are expected to be used with Happy Eyeballs systems that will find the best socket for an application.

3.3 Setting Up OPT Resource Records

For lookups that need an OPT resource record in the Additional Data section, use the add_opt_parameters extension. The extension's value (a dict) contains the parameters; these are described in more detail in RFC 6891. They are:

  • maximum_udp_payload_size (an int), a value between 512 and 65535; if not specified, this defaults to those from the DNS context
  • extended_rcode (an int), a value between 0 and 255; if not specified, this defaults to those from the DNS context
  • version (an int), a value between 0 and 255; if not specified, this defaults to 0
  • do_bit (an int), a value between 0 and 1; if not specified, this defaults to those from the DNS context
  • options (a list) contains dicts for each option to be specified. Each list time contains two names: option_code (an int) and option_data (a bindata). The API marshalls the entire set of options into a properly-formatted RDATA for the resource record.

It is very important to note that the OPT resource record specified in the add_opt_parameters extension might not be the same the one that the API sends in the query. For example, if the application also includes any of the DNSSEC extensions, the API will make sure that the OPT resource record sets the resource record appropriately, making the needed changes to the settings from the add_opt_parameters extension.

The use of this extension can conflict with the values in the DNS context. For example, the default for an OS might be a maximum payload size of 65535, but the extension might specify 1550. In such a case, the API will honor the values stated in the extension, but will honor the values from the DNS context if values are not given in the extension.

3.4 Getting Warnings for Responses that Violate the DNS Standard

To receive a warning if a particular response violates some parts of the DNS standard, use the add_warning_for_bad_dns extension. The extension's value (an int) is set to GETDNS_EXTENSION_TRUE to cause each reply in the replies_tree to contain an additional name, bad_dns (a list). The list is zero or more ints that indicate types of bad DNS found in that reply. The list of values is:

GETDNS_BAD_DNS_CNAME_IN_TARGET

A DNS query type that does not allow a target to be a CNAME pointed to a CNAME

GETDNS_BAD_DNS_ALL_NUMERIC_LABEL

One or more labels in a returned domain name is all-numeric; this is not legal for a hostname

GETDNS_BAD_DNS_CNAME_RETURNED_FOR_OTHER_TYPE

A DNS query for a type other than CNAME returned a CNAME response

3.5 Using Other Class Types

The vast majority of DNS requests are made with the Internet (IN) class. To make a request in a different DNS class, use, the specify_class extension. The extension's value (an int) contains the class number. Few applications will ever use this extension.

3.6 Extensions Relating to the API

An application might want to see debugging information for queries such as the length of time it takes for each query to return to the API. Use the return_call_reporting extension. The extension's value (an int) is set to GETDNS_EXTENSION_TRUE to add the name call_reporting (a list) to the top level of the response object. Each member of the list is a dict that represents one call made for the call to the API. Each member has the following names:

  • query_name (a bindata) is the name that was sent
  • query_type (an int) is the type that was queried for
  • query_to (a bindata) is the address to which the query was sent
  • run_time/ms (a bindata) is the difference between the time the successful query started and ended in milliseconds, represented as a uint32_t (this does not include time taken for connection set up or transport fallback)
  • entire_reply (a bindata) is the entire response received
  • dnssec_result (an int) is the DNSSEC status, or GETDNS_DNSSEC_NOT_PERFORMED if DNSSEC validation was not performed

4. Response Data from Queries

The callback function contains a pointer to a response object. A response object is always a dict. The response object always contains at least three names: replies_full (a list) and replies_tree (a list), and status (an int). replies_full is a list of DNS replies (each is bindata) as they appear on the wire. replies_tree is a list of DNS replies (each is a dict) with the various part of the reply parsed out. status is a status code for the query.

Because the API might be extended in the future, a response object might also contain names other than replies_full, replies_tree, and status. Similarly, any of the dicts described here might be extended in later versions of the API. Thus, an application using the API must not assume that it knows all possible names in a dict.

The following lists the status codes for response objects. Note that, if the status is that there are no responses for the query, the lists in replies_full and replies_tree will have zero length.

GETDNS_RESPSTATUS_GOOD

At least one response was returned

GETDNS_RESPSTATUS_NO_NAME

Queries for the name yielded all negative responses

GETDNS_RESPSTATUS_ALL_TIMEOUT

All queries for the name timed out

GETDNS_RESPSTATUS_NO_SECURE_ANSWERS

The context setting for getting only secure responses was specified, and at least one DNS response was received, but no DNS response was determined to be secure through DNSSEC.

GETDNS_RESPSTATUS_ALL_BOGUS_ANSWERS

The context setting for getting only secure responses was specified, and at least one DNS response was received, but all received responses for the requested name were bogus.

The top level of replies_tree can optionally have the following names: canonical_name (a bindata), intermediate_aliases (a list), answer_ipv4_address (a bindata), answer_ipv6_address (a bindata), and answer_type (an int).

  • The value of canonical_name is the name that the API used for its lookup. It is in FQDN presentation format.
  • The values in the intermediate_aliases list are domain names from any CNAME or unsynthesized DNAME found when resolving the original query. The list might have zero entries if there were no CNAMEs in the path. These may be useful, for example, for name comparisons when following the rules in RFC 6125.
  • The value of answer_ipv4_address and answer_ipv6_address are the addresses of the server from which the answer was received.
  • The value of answer_type is the type of name service that generated the response. The values are:

GETDNS_NAMETYPE_DNS

Normal DNS (RFC 1035)

GETDNS_NAMETYPE_WINS

The WINS name service (some reference needed)

If the call was getdns_address or getdns_address_sync, the top level of replies_tree has an additional name, just_address_answers (a list). The value of just_address_answers is a list that contains all of the A and AAAA records from the answer sections of any of the replies, in the order they appear in the replies. Each item in the list is a dict with at least two names: address_type (whose value is a bindata; it is currently either "IPv4" or "IPv6") and address_data (whose value is a bindata). Note that the dnssec_return_only_secure extension affects what will appear in the just_address_answers list. Also note if later versions of the DNS return other address types, those types will appear in this list as well.

The API can make service discovery through SRV records easier. If the call was getdns_service or getdns_service_sync, the top level of replies_tree has an additional name, srv_addresses (a list). The list is ordered by priority and weight based on the weighting algorithm in RFC 2782, lowest priority value first. Each element of the list is dict has at least two names: port and domain_name. If the API was able to determine the address of the target domain name (such as from its cache or from the Additional section of responses), the dict for an element will also contain address_type (whose value is a bindata; it is currently either "IPv4" or "IPv6") and address_data (whose value is a bindata). Note that the dnssec_return_only_secure extension affects what will appear in the srv_addresses list.

4.1 Structure of DNS replies_tree

The names in each entry in the the replies_tree list for DNS responses include header (a dict), question (a dict), answer (a list), authority (a list), and additional (a list), corresponding to the sections in the DNS message format. The answer, authority, and additional lists each contain zero or more dicts, with each dict in each list representing a resource record.

The names in the header dict are all the fields from Section 4.1.1. of RFC 1035. They are: id, qr, opcode, aa, tc, rd, ra, z, rcode, qdcount, ancount, nscount, and arcount. All are ints.

The names in the question dict are the three fields from Section 4.1.2. of RFC 1035: qname (a bindata), qtype (an int), and qclass (an int).

Resource records are a bit different than headers and question sections in that the RDATA portion often has its own structure. The other names in the resource record dicts are name (a bindata), type (an int), class (an int), ttl (an int) and rdata (a dict); there is no name equivalent to the RDLENGTH field. The OPT resource record does not have the class and the ttl name, but in stead provides udp_payload_size (an int), extended_rcode (an int), version (an int), do (an int), and z (an int).

The rdata dict has different names for each response type. There is a complete list of the types defined in the API. For names that end in "-obsolete" or "-unknown", the bindata is the entire RDATA field. For example, the rdata for an A record has a name ipv4_address (a bindata); the rdata for an SRV record has the names priority (an int), weight (an int), port (an int), and target (a bindata).

Each rdata dict also has a rdata_raw field (a bindata). This is useful for types not defined in this version of the API. It also might be of value if a later version of the API allows for additional parsers. Thus, doing a query for types not known by the API still will return a result: an rdata with just a rdata_raw.

It is expected that later extensions to the API will give some DNS types different names. It is also possible that later extensions will change the names for some of the DNS types listed above.

For example, a response to a getdns_address() call for www.example.com would look something like this:

{     # This is the response object
  "replies_full": [ <bindata of the first response>, <bindata of the second response> ],
  "just_address_answers":
  [
    {
      "address_type": <bindata of "IPv4">,
      "address_data": <bindata of 0x0a0b0c01>,
    },
    {
      "address_type": <bindata of "IPv6">,
      "address_data": <bindata of 0x33445566334455663344556633445566>
    }
  ],
  "canonical_name": <bindata of "www.example.com">,
  "answer_type": GETDNS_NAMETYPE_DNS,
  "intermediate_aliases": [],
  "replies_tree":
  [
    {     # This is the first reply
      "header": { "id": 23456, "qr": 1, "opcode": 0, ... },
      "question": { "qname": <bindata of "www.example.com">, "qtype": 1, "qclass": 1 },
      "answer":
      [
        {
          "name": <bindata of "www.example.com">,
          "type": 1,
          "class": 1,
          "ttl": 33000,
          "rdata":
          {
            "ipv4_address": <bindata of 0x0a0b0c01>
            "rdata_raw": <bindata of 0x0a0b0c01>
          }
        }
      ],
      "authority":
      [
        {
          "name": <bindata of "ns1.example.com">,
          "type": 1,
          "class": 1,
          "ttl": 600,
          "rdata":
          {
            "ipv4_address": <bindata of 0x65439876>
            "rdata_raw": <bindata of 0x65439876>
          }
        }
      ]
      "additional": [],
      "canonical_name": <bindata of "www.example.com">,
      "answer_type": GETDNS_NAMETYPE_DNS
    },
    {     # This is the second reply
      "header": { "id": 47809, "qr": 1, "opcode": 0, ... },
      "question": { "qname": <bindata of "www.example.com">, "qtype": 28, "qclass": 1 },
      "answer":
      [
        {
          "name": <bindata of "www.example.com">,
          "type": 28,
          "class": 1,
          "ttl": 1000,
          "rdata":
          {
            "ipv6_address": <bindata of 0x33445566334455663344556633445566>
            "rdata_raw": <bindata of 0x33445566334455663344556633445566>
          }
       }
      ],
      "authority": [  # Same as for other record... ]
      "additional": [],
    },
  ]
}

In DNS responses, domain names are treated special. RFC 1035 describes a form of name compression that requires that the entire record be available for analysis. The API deals with this by converting compressed names into full names when returning names in the replies_tree. This conversion happens for qname in question; name in the answer, authority, and additional; and in domain names in the data in names under rdata where the response type is AFSDB, CNAME, MX, NS, PTR, RP, RT, and SOA.

4.2 Converting Domain Names

Names in DNS fields are stored in a fashion very different from the normal presentation format normally used in applications. The DNS format is described in the first paragraph in Section 3.1 of RFC 1035; the presentation format here is a null-terminated string with interior dots. These helper functions only work with names in the DNS format that are not compressed. They are useful for converting domain names in the replies_tree to and from the FQDN presentation format.

getdns_convert_dns_name_to_fqdn() converts a domain name in DNS format to the presentation format. For example, the hex sequence 03 77 77 77 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 would be converted to "www.example.com". getdns_convert_fqdn_to_dns_name() does the reverse: it converts a null-terminated string in FQDN format to bytes in DNS format.

getdns_return_t getdns_convert_dns_name_to_fqdn( const getdns_bindata *dns_name_wire_fmt, char **fqdn_as_string ); getdns_return_t getdns_convert_fqdn_to_dns_name( const char *fqdn_as_string, getdns_bindata **dns_name_wire_fmt );

The returned values are allocated with the default system allocator, namely malloc. The caller is responsible of disposing these allocations with free.

5. Additional Definitions and Descriptions

5.1 A Few Needed Definitions

typedef struct getdns_context getdns_context; typedef uint64_t getdns_transaction_t; typedef enum getdns_data_type { t_dict, t_list, t_int, t_bindata } getdns_data_type; typedef struct getdns_bindata { size_t size; uint8_t *data; } getdns_bindata; typedef struct getdns_dict getdns_dict; typedef struct getdns_list getdns_list;

5.2 Return Codes

The return codes for all the functions are:

GETDNS_RETURN_GOOD

Good

GETDNS_RETURN_GENERIC_ERROR

Generic error

GETDNS_RETURN_BAD_DOMAIN_NAME

Badly-formed domain name in first argument

GETDNS_RETURN_BAD_CONTEXT

The context has internal deficiencies

GETDNS_RETURN_CONTEXT_UPDATE_FAIL

Did not update the context

GETDNS_RETURN_UNKNOWN_TRANSACTION

An attempt was made to cancel a callback with a transaction_id that is not recognized

GETDNS_RETURN_NO_SUCH_LIST_ITEM

A helper function for lists had an index argument that was too high.

GETDNS_RETURN_NO_SUCH_DICT_NAME

A helper function for dicts had a name argument that for a name that is not in the dict.

GETDNS_RETURN_WRONG_TYPE_REQUESTED

A helper function was supposed to return a certain type for an item, but the wrong type was given.

GETDNS_RETURN_NO_SUCH_EXTENSION

A name in the extensions dict is not a valid extension.

GETDNS_RETURN_EXTENSION_MISFORMAT

One or more of the extensions have a bad format.

GETDNS_RETURN_DNSSEC_WITH_STUB_DISALLOWED

A query was made with a context that is using stub resolution and a DNSSEC extension specified.

GETDNS_RETURN_MEMORY_ERROR

Unable to allocate the memory required.

GETDNS_RETURN_INVALID_PARAMETER

A required parameter had an invalid value.

GETDNS_RETURN_NOT_IMPLEMENTED

The library did not have the requested API feature implemented.

5.3 Types of RDATA Returned in the API

The names in the rdata dicts in replies are:

A (1)

ipv4_address (a bindata)

NS (2)

nsdname (a bindata)

MD (3)

madname (a bindata)

MF (4)

madname (a bindata)

CNAME (5)

cname (a bindata)

SOA (6)

mname (a bindata), rname (a bindata), serial (an int), refresh (an int), refresh (an int), retry (an int), and expire (an int)

MB (7)

madname (a bindata)

MG (8)

mgmname (a bindata)

MR (9)

newname (a bindata)

NULL (10)

anything (a bindata)

WKS (11)

address (a bindata), protocol (an int), and bitmap (a bindata)

PTR (12)

ptrdname (a bindata)

HINFO (13)

cpu (a bindata) and os (a bindata)

MINFO (14)

rmailbx (a bindata) and emailbx (a bindata)

MX (15)

preference (an int) and exchange (a bindata)

TXT (16)

txt_strings (a list) which contains zero or more bindata elements that are text strings

RP (17)

mbox_dname (a bindata) and txt_dname (a bindata)

AFSDB (18)

subtype (an int) and hostname (a bindata)

X25 (19)

psdn_address (a bindata)

ISDN (20)

isdn_address (a bindata) and sa (a bindata)

RT (21)

preference (an int) and intermediate_host (a bindata)

NSAP (22)

nsap (a bindata)

SIG (24)

sig_obsolete (a bindata)

KEY (25)

key_obsolete (a bindata)

PX (26)

preference (an int), map822 (a bindata), and mapx400 (a bindata)

GPOS (27)

longitude (a bindata), latitude (a bindata), and altitude (a bindata)

AAAA (28)

ipv6_address (a bindata)

LOC (29)

loc_obsolete (a bindata)

NXT (30)

nxt_obsolete (a bindata)

EID (31)

eid_unknown (a bindata)

NIMLOC (32)

nimloc_unknown (a bindata)

SRV (33)

priority (an int), weight (an int), port (an int), and target (a bindata)

ATMA (34)

format (an int) and address (a bindata)

NAPTR (35)

order (an int), preference (an int), flags (a bindata), service (a bindata), regexp (a bindata), and replacement (a bindata).

KX (36)

preference (an int) and exchanger (a bindata)

CERT (37)

type (an int), key_tag (an int), algorithm (an int), and certificate_or_crl (a bindata)

A6 (38)

a6_obsolete (a bindata)

DNAME (39)

target (a bindata)

SINK (40)

sink_unknown (a bindata)

OPT (41)

options (a list). Each element of the options list is a dict with two names: option_code (an int) and option_data (a bindata).

APL (42)

apitems (a list). Each element of the apitems list is a dict with four names: address_family (an int), prefix (an int), n (an int), and afdpart (a bindata)

DS (43)

key_tag (an int), algorithm (an int), digest_type (an int), and digest (a bindata)

SSHFP (44)

algorithm (an int), fp_type (an int), and fingerprint (a bindata)

IPSECKEY (45)

algorithm (an int), gateway_type (an int), precedence (an int), gateway, and public_key (a bindata)

RRSIG (46)

type_covered (an int), algorithm (an int), labels (an int), original_ttl (an int), signature_expiration (an int), signature_inception (an int), key_tag (an int), signers_name (a bindata), and signature (a bindata)

NSEC (47)

next_domain_name (a bindata) and type_bit_maps (a bindata)

DNSKEY (48)

flags (an int), protocol (an int), algorithm (an int), and public_key (a bindata)

DHCID (49)

dhcid_opaque (a bindata)

NSEC3 (50)

hash_algorithm (an int), flags (an int), iterations (an int), salt (a bindata), next_hashed_owner_name (a bindata), and type_bit_maps (a bindata)

NSEC3PARAM (51)

hash_algorithm (an int), flags (an int), iterations (an int), and salt (a bindata)

TLSA (52)

certificate_usage (an int), selector (an int), matching_type (an int), and certificate_association_data (a bindata).

HIP (55)

pk_algorithm (an int), hit (a bindata), public_key (a bindata), and rendezvous_servers (a list) with each element a bindata with the dname of the rendezvous_server.

NINFO (56)

ninfo_unknown (a bindata)

RKEY (57)

rkey_unknown (a bindata)

TALINK (58)

talink_unknown (a bindata)

CDS (59)

key_tag (an int), algorithm (an int), digest_type (an int), and digest (a bindata)

CDNSKEY (60)

flags (an int), protocol (an int), algorithm (an int), and public_key (a bindata)

OPENPGPKEY (61)

openpgpkey_unknown (a bindata)

CSYNC (62)

serial (an int), flags (an int), and type_bit_maps (a bindata)

SPF (99)

text (a bindata)

UINFO (100)

uinfo_unknown (a bindata)

UID (101)

uid_unknown (a bindata)

GID (102)

gid_unknown (a bindata)

UNSPEC (103)

unspec_unknown (a bindata)

NID (104)

preference (an int) and node_id (a bindata)

L32 (105)

preference (an int) and locator32 (a bindata)

L64 (106)

preference (an int) and locator64 (a bindata)

LP (107)

preference (an int) and fqdn (a bindata)

EUI48 (108)

eui48_address (a bindata)

EUI64 (109)

eui64_address (a bindata)

TKEY (249)

algorithm (a bindata), inception (an int), expiration (an int), mode (an int), error (an int), key_data (a bindata), and other_data (a bindata)

TSIG (250)

algorithm (a bindata), time_signed (a bindata), fudge (an int), mac (a bindata), original_id (an int), error (an int), and other_data (a bindata)

MAILB (253)

mailb-unknown (a bindata)

MAILA (254)

maila-unknown (a bindata)

URI (256)

priority (an int), weight (an int), and target (a bindata)

CAA (257)

flags (an int), tag (a bindata), and value (a bindata)

TA (32768)

ta_unknown (a bindata)

DLV (32769)

Identical to DS (43)

6. Examples

This section gives examples of code that calls the API to do many common tasks. The purpose of the code here is to give application developers a quick hands-on demo of using the API.

Note that the examples here all use getdns_libevent.h as the include that will call in the API code as well as calling in libevent as the event library. They also use getdns_context_set_libevent_base() as the name of the function to set the event base in the DNS context. If you are using a different event library, you will of course use a different #include at the beginning of your code, and a different name for the event base function.

6.1 Get Both IPv4 and IPv6 Addresses for a Domain Name Using Quick Results

This is an example of a common call to getdns_address().


#include <assert.h>
#include <inttypes.h>
#include <stdio.h>
#include <getdns_libevent.h>

/* Set up the callback function, which will also do the processing of the results */
void callback(getdns_context        *context,
              getdns_callback_type_t callback_type,
              getdns_dict           *response, 
              void                  *userarg,
              getdns_transaction_t   transaction_id)
{
    getdns_return_t r;  /* Holder for all function returns */
    uint32_t        status;
    getdns_bindata  *address_data;
    char            *first = NULL, *second = NULL;

    (void) context; /* unused parameter */

    printf( "Callback for query \"%s\" with request ID %"PRIu64".\n"
          , (char *)userarg, transaction_id );

    switch(callback_type) {
    case GETDNS_CALLBACK_CANCEL:
        printf("Transaction with ID %"PRIu64" was cancelled.\n", transaction_id);
        return;
    case GETDNS_CALLBACK_TIMEOUT:
        printf("Transaction with ID %"PRIu64" timed out.\n", transaction_id);
        return;
    case GETDNS_CALLBACK_ERROR:
        printf("An error occurred for transaction ID %"PRIu64".\n", transaction_id);
        return;
    default: break;
    }
    assert( callback_type == GETDNS_CALLBACK_COMPLETE );

    if ((r = getdns_dict_get_int(response, "status", &status)))
        fprintf(stderr, "Could not get \"status\" from response");

    else if (status != GETDNS_RESPSTATUS_GOOD)
        fprintf(stderr, "The search had no results, and a return value of %"PRIu32".\n", status);

    else if ((r = getdns_dict_get_bindata(response, "/just_address_answers/0/address_data", &address_data)))
        fprintf(stderr, "Could not get first address");

    else if (!(first = getdns_display_ip_address(address_data)))
        fprintf(stderr, "Could not convert first address to string\n");

    else if ((r = getdns_dict_get_bindata(response, "/just_address_answers/1/address_data", &address_data)))
        fprintf(stderr, "Could not get second address");

    else if (!(second = getdns_display_ip_address(address_data)))
        fprintf(stderr, "Could not convert second address to string\n");

    if (first) {
        printf("The address is %s\n", first);
        free(first);
    }
    if (second) {
        printf("The address is %s\n", second);
        free(second);
    }
    if (r) {
        assert( r != GETDNS_RETURN_GOOD );
        fprintf(stderr, ": %d\n", r);
    }
    getdns_dict_destroy(response); 
}

int main()
{
    getdns_return_t      r;  /* Holder for all function returns */
    getdns_context      *context    = NULL;
    struct event_base   *event_base = NULL;
    getdns_dict         *extensions = NULL;
    char                *query_name = "www.example.com";
    /* Could add things here to help identify this call */
    char                *userarg    = query_name;
    getdns_transaction_t transaction_id;

    if ((r = getdns_context_create(&context, 1)))
        fprintf(stderr, "Trying to create the context failed");

    else if (!(event_base = event_base_new()))
        fprintf(stderr, "Trying to create the event base failed.\n");

    else if ((r = getdns_extension_set_libevent_base(context, event_base)))
        fprintf(stderr, "Setting the event base failed");

    else if ((r = getdns_address( context, query_name, extensions
                                , userarg, &transaction_id, callback)))
        fprintf(stderr, "Error scheduling asynchronous request");

    else {
        printf("Request with transaction ID %"PRIu64" scheduled.\n", transaction_id);
        if (event_base_dispatch(event_base) < 0)
            fprintf(stderr, "Error dispatching events\n");
    }

    /* Clean up */
    if (event_base)
        event_base_free(event_base);

    if (context)
        getdns_context_destroy(context);

    /* Assuming we get here, leave gracefully */
    exit(EXIT_SUCCESS);
}

6.2 Get IPv4 and IPv6 Addresses for a Domain Name

This example is similar to the previous one, except that it retrieves more information than just the addresses, so it traverses the replies_tree. In this case, it gets both the addresses and their TTLs.


#include <assert.h>
#include <inttypes.h>
#include <stdio.h>
#include <getdns_libevent.h>

/* Set up the callback function, which will also do the processing of the results */
void callback(getdns_context        *context,
              getdns_callback_type_t callback_type,
              getdns_dict           *response, 
              void                  *userarg,
              getdns_transaction_t   transaction_id)
{
    getdns_return_t r;  /* Holder for all function returns */
    getdns_list    *replies_tree;
    size_t          n_replies, i;

    (void) context; (void) userarg; /* unused parameters */

    switch(callback_type) {
    case GETDNS_CALLBACK_CANCEL:
        printf("Transaction with ID %"PRIu64" was cancelled.\n", transaction_id);
        return;
    case GETDNS_CALLBACK_TIMEOUT:
        printf("Transaction with ID %"PRIu64" timed out.\n", transaction_id);
        return;
    case GETDNS_CALLBACK_ERROR:
        printf("An error occurred for transaction ID %"PRIu64".\n", transaction_id);
        return;
    default: break;
    }
    assert( callback_type == GETDNS_CALLBACK_COMPLETE );

    if ((r = getdns_dict_get_list(response, "replies_tree", &replies_tree)))
        fprintf(stderr, "Could not get \"replies_tree\" from response");

    else if ((r = getdns_list_get_length(replies_tree, &n_replies)))
        fprintf(stderr, "Could not get replies_tree\'s length");

    else for (i = 0; i < n_replies && r == GETDNS_RETURN_GOOD; i++) {
        getdns_dict *reply;
        getdns_list *answer;
        size_t       n_answers, j;

        if ((r = getdns_list_get_dict(replies_tree, i, &reply)))
            fprintf(stderr, "Could not get address %zu from just_address_answers", i);

        else if ((r = getdns_dict_get_list(reply, "answer", &answer)))
            fprintf(stderr, "Could not get \"address_data\" from address");

        else if ((r = getdns_list_get_length(answer, &n_answers)))
            fprintf(stderr, "Could not get answer section\'s length");

        else for (j = 0; j < n_answers && r == GETDNS_RETURN_GOOD; j++) {
            getdns_dict    *rr;
            getdns_bindata *address = NULL;

            if ((r = getdns_list_get_dict(answer, j, &rr)))
                fprintf(stderr, "Could net get rr %zu from answer section", j);

            else if (getdns_dict_get_bindata(rr, "/rdata/ipv4_address", &address) == GETDNS_RETURN_GOOD)
                printf("The IPv4 address is ");

            else if (getdns_dict_get_bindata(rr, "/rdata/ipv6_address", &address) == GETDNS_RETURN_GOOD)
                printf("The IPv6 address is ");

            if (address) {
                char *address_str;
                if (!(address_str = getdns_display_ip_address(address))) {
                    fprintf(stderr, "Could not convert second address to string");
                    r = GETDNS_RETURN_MEMORY_ERROR;
                    break;
                }
                printf("%s\n", address_str);
                free(address_str);
            }
        }
    }
    if (r) {
        assert( r != GETDNS_RETURN_GOOD );
        fprintf(stderr, ": %d\n", r);
    }
    getdns_dict_destroy(response); 
}

int main()
{
    getdns_return_t      r;  /* Holder for all function returns */
    getdns_context      *context    = NULL;
    struct event_base   *event_base = NULL;
    getdns_dict         *extensions = NULL;
    char                *query_name = "www.example.com";
    /* Could add things here to help identify this call */
    char                *userarg    = NULL;
    getdns_transaction_t transaction_id;

    if ((r = getdns_context_create(&context, 1)))
        fprintf(stderr, "Trying to create the context failed");

    else if (!(event_base = event_base_new()))
        fprintf(stderr, "Trying to create the event base failed.\n");

    else if ((r = getdns_extension_set_libevent_base(context, event_base)))
        fprintf(stderr, "Setting the event base failed");

    else if ((r = getdns_address( context, query_name, extensions
                                , userarg, &transaction_id, callback)))
        fprintf(stderr, "Error scheduling asynchronous request");

    else if (event_base_dispatch(event_base) < 0)
        fprintf(stderr, "Error dispatching events\n");

    /* Clean up */
    if (event_base)
        event_base_free(event_base);

    if (context)
        getdns_context_destroy(context);

    /* Assuming we get here, leave gracefully */
    exit(EXIT_SUCCESS);
}

6.3 Get Addresses for a Domain Name And Their Associated DNSSEC Validation Status

This example shows how to check for secure DNSSEC results using the dnssec_return_status extension. In the innermost loop of the callback function, add a check for the DNSSEC status. It shows how to add two extensions to the extensions argument of the call.

getdns_dict *extensions = getdns_dict_create();
r = getdns_dict_set_int(extensions, "return_both_v4_and_v6", GETDNS_EXTENSION_TRUE);
r = getdns_dict_set_int(extensions, "dnssec_return_status", GETDNS_EXTENSION_TRUE);
. . .
if (rr_type == GETDNS_RRTYPE_A) {
    uint32_t dnssec_status;
    r = getdns_dict_get_int(answer, "dnssec_status", &dnssec_status);
    if (dnssec_status != GETDNS_DNSSEC_SECURE) {
        // Log the DNSSEC status somewhere

    } else {
        // Deal with the record however you were going to
    }
}
. . .

You can put the DNSSEC status check outside the check for the particular type of record you care about, but you will then get log messages for bad status on records you might not care about as well.

6.4 Using the API Synchronously with getdns_general_sync()

This example is the same as the earlier examples, but uses getdns_general_sync() and thus does not use the async code. Note that the processing of the answers is essentially the same as it is for the synchronous example, it is just done in main().


#include <stdio.h>
#include <assert.h>
#include <getdns_core_only.h>

int main()
{
    getdns_return_t  r; /* Holder for all function returns */
    getdns_context  *context    = NULL;
    getdns_dict     *response   = NULL;
    getdns_dict     *extensions = NULL;
    getdns_bindata  *address_data;
    char            *first = NULL, *second = NULL;

    /* Create the DNS context for this call */
    if ((r = getdns_context_create(&context, 1)))
        fprintf(stderr, "Trying to create the context failed");

    else if (!(extensions = getdns_dict_create()))
        fprintf(stderr, "Could not create extensions dict.\n");

    else if ((r = getdns_dict_set_int(extensions, "return_both_v4_and_v6", GETDNS_EXTENSION_TRUE)))
        fprintf(stderr, "Trying to set an extension do both IPv4 and IPv6 failed");

    else if ((r = getdns_general_sync(context, "example.com", GETDNS_RRTYPE_A, extensions, &response)))
        fprintf(stderr, "Error scheduling synchronous request");
    
    else if ((r = getdns_dict_get_bindata(response, "/just_address_answers/0/address_data", &address_data)))
        fprintf(stderr, "Could not get first address");

    else if (!(first = getdns_display_ip_address(address_data)))
        fprintf(stderr, "Could not convert first address to string\n");

    else if ((r = getdns_dict_get_bindata(response, "/just_address_answers/1/address_data", &address_data)))
        fprintf(stderr, "Could not get second address");

    else if (!(second = getdns_display_ip_address(address_data)))
        fprintf(stderr, "Could not convert second address to string\n");

    if (first) {
        printf("The address is %s\n", first);
        free(first);
    }
    if (second) {
        printf("The address is %s\n", second);
        free(second);
    }
    /* Clean up */
    if (response)
        getdns_dict_destroy(response); 

    if (extensions)
        getdns_dict_destroy(extensions);

    if (context)
        getdns_context_destroy(context);

    if (r) {
        assert( r != GETDNS_RETURN_GOOD );

        fprintf(stderr, ": %d\n", r);
        exit(EXIT_FAILURE);
    }
    /* Assuming we get here, leave gracefully */
    exit(EXIT_SUCCESS);
}

6.5 Getting Names from the Reverse Tree with getdns_hostname()

This example shows how to use getdns_hostname() to get names from the DNS reverse tree.


#include <assert.h>
#include <inttypes.h>
#include <stdio.h>
#include <getdns_libevent.h>

/* Set up the callback function, which will also do the processing of the results */
void callback(getdns_context        *context,
              getdns_callback_type_t callback_type,
              getdns_dict           *response, 
              void                  *userarg,
              getdns_transaction_t   transaction_id)
{
    getdns_return_t r;  /* Holder for all function returns */
    getdns_list    *answer;
    size_t          n_answers, i;

    (void) context; (void) userarg; /* unused parameters */

    switch(callback_type) {
    case GETDNS_CALLBACK_CANCEL:
        printf("Transaction with ID %"PRIu64" was cancelled.\n", transaction_id);
        return;
    case GETDNS_CALLBACK_TIMEOUT:
        printf("Transaction with ID %"PRIu64" timed out.\n", transaction_id);
        return;
    case GETDNS_CALLBACK_ERROR:
        printf("An error occurred for transaction ID %"PRIu64".\n", transaction_id);
        return;
    default: break;
    }
    assert( callback_type == GETDNS_CALLBACK_COMPLETE );

    if ((r = getdns_dict_get_list(response, "/replies_tree/0/answer", &answer)))
        fprintf(stderr, "Could not get \"answer\" section from first reply in the response");

    else if ((r = getdns_list_get_length(answer, &n_answers)))
        fprintf(stderr, "Could not get replies_tree\'s length");

    else for (i = 0; i < n_answers && r == GETDNS_RETURN_GOOD; i++) {
        getdns_dict    *rr;
        getdns_bindata *dname;
        char           *dname_str;

        if ((r = getdns_list_get_dict(answer, i, &rr)))
            fprintf(stderr, "Could not get rr %zu from answer section", i);

        else if (getdns_dict_get_bindata(rr, "/rdata/ptrdname", &dname))
            continue; /* Not a PTR */

        else if ((r = getdns_convert_dns_name_to_fqdn(dname, &dname_str)))
            fprintf(stderr, "Could not convert PTR dname to string");

        else {
            printf("The dname is %s\n", dname_str);
            free(dname_str);
        }
    }
    if (r) {
        assert( r != GETDNS_RETURN_GOOD );
        fprintf(stderr, ": %d\n", r);
    }
    getdns_dict_destroy(response); 
}

int main()
{
    getdns_return_t      r;  /* Holder for all function returns */
    getdns_context      *context      = NULL;
    struct event_base   *event_base   = NULL;
    getdns_bindata       address_type = { 4, (void *)"IPv4" };
    getdns_bindata       address_data = { 4, (void *)"\x08\x08\x08\x08" };
    getdns_dict         *address      = NULL;
    getdns_dict         *extensions   = NULL;
    /* Could add things here to help identify this call */
    char                *userarg      = NULL;
    getdns_transaction_t transaction_id;

    if ((r = getdns_context_create(&context, 1)))
        fprintf(stderr, "Trying to create the context failed");

    else if (!(event_base = event_base_new()))
        fprintf(stderr, "Trying to create the event base failed.\n");

    else if ((r = getdns_extension_set_libevent_base(context, event_base)))
        fprintf(stderr, "Setting the event base failed");

    else if (!(address = getdns_dict_create()))
        fprintf(stderr, "Could not create address dict.\n");

    else if ((r = getdns_dict_set_bindata(address, "address_type", &address_type)))
        fprintf(stderr, "Could not set address_type in address dict.\n");

    else if ((r = getdns_dict_set_bindata(address, "address_data", &address_data)))
        fprintf(stderr, "Could not set address_data in address dict.\n");

    else if ((r = getdns_hostname( context, address, extensions
                                 , userarg, &transaction_id, callback)))
        fprintf(stderr, "Error scheduling asynchronous request");

    else if (event_base_dispatch(event_base) < 0)
        fprintf(stderr, "Error dispatching events\n");

    /* Clean up */
    if (event_base)
        event_base_free(event_base);

    if (context)
        getdns_context_destroy(context);

    /* Assuming we get here, leave gracefully */
    exit(EXIT_SUCCESS);
}

7. More Helper Functions

The following two functions convert individual labels of IDNs between their Unicode encoding and their ASCII encoding. They follow the rules for IDNA 2008 described in RFC 5890-5892.

char * getdns_convert_ulabel_to_alabel( const char *ulabel );
char * getdns_convert_alabel_to_ulabel( const char *alabel );

If an application wants the API do perform DNSSEC validation without using the extensions, it can use the getdns_validate_dnssec() helper function.

getdns_return_t getdns_validate_dnssec( getdns_list *to_validate, getdns_list *bundle_of_support_records, getdns_list *trust_anchor_records );

The to_validate is a list of resource records being validated together with the associated signatures. The API will use the resource records in bundle_of_support_records to construct the validation chain and the DNSKEY or DS records in trust_anchor_records as trust anchors. The function returns one of GETDNS_DNSSEC_SECURE, GETDNS_DNSSEC_BOGUS, GETDNS_DNSSEC_INDETERMINATE, or GETDNS_DNSSEC_INSECURE.

The default list of trust anchor records that is used by the library to validate DNSSEC can be retrieved by using the getdns_root_trust_anchor helper function.

getdns_list * getdns_root_trust_anchor( time_t *utc_date_of_anchor );

When there are no default trust anchors NULL is returned. Upon successful return, the variable of type time_t, referenced by utc_date_of_anchor is set to the number of seconds since epoch the trust anchors were obtained.

There are two functions that help process data:

char * getdns_pretty_print_dict( const getdns_dict *some_dict );

This returns a string that is the nicely-formatted version of the dict and all of the named elements in it.

char * getdns_display_ip_address( const getdns_bindata *bindata_of_ipv4_or_ipv6_address );

This returns a string that is the nicely-formatted version of the IPv4 or IPv6 address in it. The API determines they type of address by the length given in the bindata.

All memory locations returned by these helper functions are allocated by the default system allocator, namely malloc. The caller is responsible of disposing these allocations with free.

8. DNS Contexts

Many calls in the DNS API require a DNS context. A DNS context contains the information that the API needs in order to process DNS calls, such as the locations of upstream DNS servers, DNSSEC trust anchors, and so on. The internal structure of the DNS context is opaque, and might be different on each OS. When a context is passed to any function, it must be an allocated context; the context must not be NULL.

A typical application using this API doesn't need to know anything about contexts. Basically, the application creates a default context, uses it in the functions that require a context, and then deallocates it when done. Context manipulation is available for more DNS-aware programs, but is unlikely to be of interest to applications that just want the results of lookups for A, AAAA, SRV, and PTR records.

It is expected that contexts in implementations of the API will not necessarily be thread-safe, but they will not be thread-hostile. A context should not be used by multiple threads: create a new context for use on a different thread. It is just fine for an application to have many contexts, and some DNS-heavy applications will certainly want to have many even if the application uses a single thread.

See above for the method for creating and destroying contexts. When the context is used in the API for the first time and set_from_os is 1, the API starts replacing some of the values with values from the OS, such as those that would be found in res_query(3), /etc/resolv.conf, and so on, then proceeds with the new function. Some advanced users will not want the API to change the values to the OS's defaults; if set_from_os is 0, the API will not do any updates to the initial values based on changes in the OS. For example, this might be useful if the API is acting as a stub resolver that is using a specific upstream recursive resolver chosen by the application, not the one that might come back from DHCP.

8.1 Updating the Context Automatically

The context returned by getdns_context_create() is updated by the API by default, such as when changes are made to /etc/resolv.conf. When there is a change, the callback function that is set in getdns_context_set_context_update_callback() (described below) is called.

Many of the defaults for a context come from the operating system under which the API is running. In specific, it is important that the implementation should try to replicate as best as possible the logic of a local getaddrinfo() when creating a new context. This includes making lookups in WINS for NetBIOS, mDNS lookups, nis names, and any other name lookup that getaddrinfo() normally does automatically. The API should look at nsswitch, the Windows resolver, and so on.

In the function definitions below, the choice listed in bold is the one used for the API default context.

8.2 Updating the Context Manually

Setting specific values in a context are done with value-specific functions shown here. The setting functions all return either GETDNS_RETURN_GOOD for success or GETDNS_RETURN_CONTEXT_UPDATE_FAIL for a failure to update the context.

An application can be notified when the context is changed.

getdns_return_t getdns_context_set_context_update_callback( getdns_context *context, void (*value)(getdns_context *context, getdns_context_code_t changed_item) );

The value is a pointer to the callback function that will be called when any context is changed. Such changes might be from automatic changes from the API (such as changes to /etc/resolv.conf), or might be from any of the API functions in this section being called. The second argument to the callback function specifies which of the context changed; the context codes are listed later in this document.

Calling getdns_context_set_context_update_callback with a second argument of NULL prevents updates to the context from causing callbacks.

8.3 Contexts for Basic Resolution

getdns_return_t getdns_context_set_resolution_type( getdns_context *context, getdns_resolution_t value );

Specifies whether DNS queries are performed with nonrecurive lookups or as a stub resolver. The value is GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB.

All implementations of this API can act as recursive resolvers, and that must be the default mode of the default context. Some implementations of this API are expected to also be able to act as stub resolvers. If an implementation of this API is only able to act as a recursive resolver, a call to getdns_context_set_resolution_type(somecontext, GETDNS_RESOLUTION_STUB) will return GETDNS_RETURN_CONTEXT_UPDATE_FAIL.

getdns_return_t getdns_context_set_namespaces( getdns_context *context, size_t namespace_count, getdns_namespace_t *namespaces );

The namespaces array contains an ordered list of namespaces that will be queried. Important: this context setting is ignored for the getdns_general and getdns_general_sync functions; it is used for the other funtions. The values are GETDNS_NAMESPACE_DNS, GETDNS_NAMESPACE_LOCALNAMES, GETDNS_NAMESPACE_NETBIOS, GETDNS_NAMESPACE_MDNS, and GETDNS_NAMESPACE_NIS. When a normal lookup is done, the API does the lookups in the order given and stops when it gets the first result; a different method with the same result would be to run the queries in parallel and return when it gets the first result. Because lookups might be done over different mechanisms because of the different namespaces, there can be information leakage that is similar to that seen with getaddrinfo(). The default is determined by the OS.

getdns_return_t getdns_context_set_dns_transport( getdns_context *context, getdns_transport_t value );

Specifies what transport is used for DNS lookups. The value is GETDNS_TRANSPORT_UDP_FIRST_AND_FALL_BACK_TO_TCP, GETDNS_TRANSPORT_UDP_ONLY, GETDNS_TRANSPORT_TCP_ONLY, or GETDNS_TRANSPORT_TCP_ONLY_KEEP_CONNECTIONS_OPEN.

getdns_return_t getdns_context_set_dns_transport_list( getdns_context *context, size_t transport_count, getdns_transport_list_t *transports );

The transports array contains an ordered list of transports that will be used for DNS lookups. If only one transport value is specified it will be the only transport used. Should it not be available basic resolution will fail. Fallback transport options are specified by including multiple values in the list. The values are GETDNS_TRANSPORT_UDP, GETDNS_TRANSPORT_TCP, or GETDNS_TRANSPORT_TLS. The default is a list containing GETDNS_TRANSPORT_UDP then GETDNS_TRANSPORT_TCP.

getdns_return_t getdns_context_set_idle_timeout( getdns_context *context, uint64_t timeout );

Specifies number of milliseconds the API will leave an idle TCP or TLS connection open for (idle means no outstanding responses and no pending queries). The default is 0.

getdns_return_t getdns_context_set_limit_outstanding_queries( getdns_context *context, uint16_t limit );

Specifies limit the number of outstanding DNS queries. The API will block itself from sending more queries if it is about to exceed this value, and instead keep those queries in an internal queue. The a value of 0 indicates that the number of outstanding DNS queries is unlimited.

getdns_return_t getdns_context_set_timeout( getdns_context *context, uint64_t timeout );

Specifies number of milliseconds the API will wait for request to return. The default is not specified.

8.4 Context for Recursive Resolvers

getdns_return_t getdns_context_set_follow_redirects( getdns_context *context, getdns_redirects_t value );

Specifies whether or not DNS queries follow redirects. The value is GETDNS_REDIRECTS_FOLLOW for normal following of redirects though CNAME and DNAME; or GETDNS_REDIRECTS_DO_NOT_FOLLOW to cause any lookups that would have gone through CNAME and DNAME to return the CNAME or DNAME, not the eventual target.

getdns_return_t getdns_context_set_dns_root_servers( getdns_context *context, getdns_list *addresses );

The list contains dicts that are addresses to be used for looking up top-level domains; the default is the list of "normal" IANA root servers. Each dict in the list contains at least two names: address_type (whose value is a bindata; it is currently either "IPv4" or "IPv6") and address_data (whose value is a bindata).

8.5 Context for Local Naming

getdns_return_t getdns_context_set_append_name( getdns_context *context, getdns_append_name_t value );

Specifies whether to append a suffix to the query string before the API starts resolving a name. The value is GETDNS_APPEND_NAME_ALWAYS, GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE, GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE, or GETDNS_APPEND_NAME_NEVER. This controls whether or not to append the suffix given by getdns_context_set_suffix

getdns_return_t getdns_context_set_suffix( getdns_context *context, getdns_list *value );

The value is a list of bindatas that are strings that are to be appended based on getdns_context_set_append_name; the default is an empty list. The values here follow the rules in section 2.1 of RFC 4343 to allow non-ASCII octets and special characters in labels.

8.6 Context for DNSSEC

These context settings affect queries that have extensions that specify the use of DNSSEC.

Applications that need to specify the DNSSEC trust anchors can use:

getdns_return_t getdns_context_set_dnssec_trust_anchors( getdns_context *context, getdns_list *value );

The value is a list of bindatas that are the DNSSEC trust anchors. The default is the trust anchors from the IANA root. The trust anchors are expressed as RDATAs from DNSKEY resource records.

In the rare case that an application needs to set the DNSSEC skew, it can:

getdns_return_t getdns_context_set_dnssec_allowed_skew( getdns_context *context, uint32_t value );

The value is the number of seconds of skew that is allowed in either direction when checking an RRSIG's Expiration and Inception fields. The default is 0.

8.7 Context Specific to Stub Resolvers

An application can change the quering mechanism of a context to be to act as a stub resolver. Such an application might first get the default information to make this change from the operating system, probably through DHCP.

Note that if a context is changed to being a stub resolver, this automatically prevents the application from using the extenstions for DNSSEC. An application that wants to both do DNSSEC and stub resolution must do its own DNSSEC processing, possibly with the getdns_validate_dnssec() function.

getdns_return_t getdns_context_set_upstream_recursive_servers( getdns_context *context, getdns_list *upstream_list );

The list of dicts define where a stub resolver will send queries. Each dict contains at least two names: address_type (whose value is a bindata; it is currently either "IPv4" or "IPv6") and address_data (whose value is a bindata). For IPv6 link-local addresses, a scope_id name (a bindata) can be provided. It might also contain port to specify which port to use to contact these DNS servers; the default is 53. If the stub and a recursive resolver both support TSIG (RFC 2845), the upstream_list entry can also contain tsig_algorithm (a bindata) that is the name of the TSIG hash algorithm, tsig_name (a bindata) that is the name of the TSIG key, and tsig_secret (a bindata) that is the TSIG key.

8.8 Context for EDNS

These context settings affect queries that have extensions that specify the use of OPT resource records. These come from RFC 6891.

getdns_return_t getdns_context_set_edns_maximum_udp_payload_size( getdns_context *context, uint16_t value );

The value is between 512 and 65535; when not set, outgoing values will adhere to the suggestions in RFC 6891 and may follow a scheme that uses multiple values to maximize receptivity.

getdns_return_t getdns_context_set_edns_extended_rcode( getdns_context *context, uint8_t value );

The value is between 0 and 255; the default is 0.

getdns_return_t getdns_context_set_edns_version( getdns_context *context, uint8_t value );

The value is between 0 and 255; the default is 0.

getdns_return_t getdns_context_set_edns_do_bit( getdns_context *context, uint8_t value );

The value is between 0 and 1; the default is 0.

8.9 Context Use of Custom Memory Management Functions

getdns_return_t getdns_context_set_memory_functions( getdns_context *context, void *(*malloc) (size_t), void *(*realloc) (void *, size_t), void (*free) (void *) );

The given memory management functions will be used for creating the response dicts. The response dicts inherit the custom memory management functions from the context and will deallocate themselves (and their members) with the custom deallocator. By default, the system malloc, realloc, and free are used.

getdns_return_t getdns_context_set_extended_memory_functions( getdns_context *context, void *userarg, void *(*malloc)(void *userarg, size_t sz), void *(*realloc)(void *userarg, void *ptr, size_t sz), void (*free)(void *userarg, void *ptr) );

The given extended memory management functions will be used for creating the response dicts. The value of userarg argument will be passed to the custom malloc, realloc, and free. The response dicts inherit the custom memory management functions and the value for userarg from the context and will deallocate themselves (and their members) with the custom deallocator.

8.10 Context Codes

The context codes for getdns_context_set_context_update_callback() are:

GETDNS_CONTEXT_CODE_NAMESPACES

Change related to getdns_context_set_namespaces

GETDNS_CONTEXT_CODE_RESOLUTION_TYPE

Change related to getdns_context_set_resolution_type

GETDNS_CONTEXT_CODE_FOLLOW_REDIRECTS

Change related to getdns_context_set_follow_redirects

GETDNS_CONTEXT_CODE_UPSTREAM_RECURSIVE_SERVERS

Change related to getdns_context_set_upstream_recursive_servers

GETDNS_CONTEXT_CODE_DNS_ROOT_SERVERS

Change related to getdns_context_set_dns_root_servers

GETDNS_CONTEXT_CODE_DNS_TRANSPORT

Change related to getdns_context_set_dns_transport

GETDNS_CONTEXT_CODE_LIMIT_OUTSTANDING_QUERIES

Change related to getdns_context_set_limit_outstanding_queries

GETDNS_CONTEXT_CODE_APPEND_NAME

Change related to getdns_context_set_append_name

GETDNS_CONTEXT_CODE_SUFFIX

Change related to getdns_context_set_suffix

GETDNS_CONTEXT_CODE_DNSSEC_TRUST_ANCHORS

Change related to getdns_context_set_dnssec_trust_anchors

GETDNS_CONTEXT_CODE_EDNS_MAXIMUM_UDP_PAYLOAD_SIZE

Change related to getdns_context_set_edns_maximum_udp_payload_size

GETDNS_CONTEXT_CODE_EDNS_EXTENDED_RCODE

Change related to getdns_context_set_edns_extended_rcode

GETDNS_CONTEXT_CODE_EDNS_VERSION

Change related to getdns_context_set_edns_version

GETDNS_CONTEXT_CODE_EDNS_DO_BIT

Change related to getdns_context_set_edns_do_bit

GETDNS_CONTEXT_CODE_DNSSEC_ALLOWED_SKEW

Change related to getdns_context_set_dnssec_allowed_skew

GETDNS_CONTEXT_CODE_MEMORY_FUNCTIONS

Change related to getdns_context_set_memory_functions

GETDNS_CONTEXT_CODE_TIMEOUT

Change related to getdns_context_set_timeout

GETDNS_CONTEXT_CODE_IDLE_TIMEOUT

Change related to getdns_context_set_idle_timeout

8.11 Getting API information and current Contexts

An application might want to see information about the API itself and inspect the current context. Use the getdns_context_get_api_information function.

getdns_dict * getdns_context_get_api_information( getdns_context *context );

The returned getdns_dict will contain the following name/value pairs:

  • version_string (a bindata) represents the version string for this version of the DNS API.
  • implementation_string (a bindata) is a string set by the API implementer. It might be human-readable, and it might have information in it useful to an application developer (but it doesn't have to).
  • resolution_type (an int) is the type of resolver that the API is acting as in this context: GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_STUB (it will be a recursing resolver unless the application changed this in a context.
  • all_context (a dict) with names for all the types of context. This can be used with getdns_pretty_print_dict() for debugging.

9. The Generated Files

There is a tarball that includes the .h files, the examples, and so on. The examples all make, even though there is no API implementation, based on a pseudo-implementation in the tarball; see make-examples-PLATFORM.sh. Note that this currently builds fine on the Macintosh and Ubuntu; help is definitely appreciated on making the build process work on more platforms if it fails there.

10. Commentary

The following description of the API may be of value to those who might implement the design, and those who are using an implementation of the design.

10.1 API Design Considerations

The genesis of this DNS API design was seeing other DNS API designs flounder. There are other DNS APIs already available (such as draft-hayatnagarkar-dnsext-validator-api, as well as DNSSEC APIs in BIND and Unbound), but there has been very little uptake of them. In talking to application developers, there was a consistent story: that they felt that the APIs were developed by and for DNS people, not applications developers.

This API design comes from talking to a small handful of applications developers about what they would want to see in a modern DNS API. Now that the API is public, it would be great to hear from many more application developers about whether it would meet their needs if it was implemented. My goal is to create a design that is a natural follow-on to getaddrinfo() that has all the capabilities that most application developers might want now or in the next few years: access to all types of DNS records (including those which are yet to be defined), full DNSSEC awareness, IDN handling, and parity for IPv4 and IPv6 addresses.

Note that this is just a design for a new API: there is no implementation of the design yet, but at least one is being worked on. The process of designing the API without implementing it at the same time has the huge advantage that major design changes could be made without any worry about "but we already coded it the other way". In the early revisions of this document, many fundamental design choices changed over and over, and even bike-shedding-like changes were allowed because they didn't involve any programming effort.

This work was done independently, not through the IETF because the IETF generally doesn't take on API work, and has explicitly avoided DNS API work in the past.

This API design has a Creative Commons license so that it can be used widely by potential API implementers. This also allows other people who want to fork the design to do so cleanly. Of course, any implementation of this API can choose whatever kind of license the API implementer wishes, but it would be fabulous if one or more such implementations had Creative Commons or BSD-ish licenses.

The API relies heavily on C macros and hopefully has no magic numbers.

10.2 API Implementation Considerations

All implementations of this API must act as recursive resolvers, and some might choose not to be able to act as stub resolvers. Note that all implementations of this API must be DNSSEC validators.

Because there are many C event libraries available, and they have different calling routines, it is the implementation of an API that determines which event library is used. This is certainly not optimal for C programmers, but they appear to have gotten used to is so far. All implementations of this API must support synchronous calls with getdns_general_sync().

Versions are differentiated by version strings instead of version numbers. The version string for this API is "getdns April 2013". Each implementation is free to set the implementation string as it feels fit.

The API's .h file contains a macro called GETDNS_COMPILATION_COMMENT. This can be useful to an application which will use the API because it can check the string without calling any functions. Each time the API implementation is compiled, this string should be updated with unique information about the implementation build.

The implementation of both the async and sync getdns functions will copy all the values of the parameters into local memory, in case the application changes or deallocates them.

Creative Commons License
This work is licensed under a Creative Commons Attribution 3.0 Unported License.

getdns-1.6.0/src/000077500000000000000000000000001362622307100135735ustar00rootroot00000000000000getdns-1.6.0/src/Doxyfile.in000066400000000000000000003177701362622307100157250ustar00rootroot00000000000000# Doxyfile 1.8.11 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. # # All text after a double hash (##) is considered a comment and is placed in # front of the TAG it is preceding. # # All text after a single hash (#) is considered a comment and will be ignored. # The format is: # TAG = value [value, ...] # For lists, items can also be appended using: # TAG += value [value, ...] # Values that contain spaces should be placed between quotes (\" \"). #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- # This tag specifies the encoding used for all characters in the config file # that follow. The default is UTF-8 which is also the encoding used for all text # before the first occurrence of this tag. Doxygen uses libiconv (or the iconv # built into libc) for the transcoding. See http://www.gnu.org/software/libiconv # for the list of possible encodings. # The default value is: UTF-8. DOXYFILE_ENCODING = UTF-8 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded by # double-quotes, unless you are using Doxywizard) that should identify the # project for which the documentation is generated. This name is used in the # title of most generated pages and in a few other places. # The default value is: My Project. PROJECT_NAME = "getdns" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version # control system is used. PROJECT_NUMBER = @PACKAGE_VERSION@ # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. PROJECT_BRIEF = "An implementation of the getdns API - a modern asynchronous API for fetching DNS data" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. PROJECT_LOGO = # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. OUTPUT_DIRECTORY = doc # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and # will distribute the generated files over these directories. Enabling this # option can be useful when feeding doxygen a huge amount of source files, where # putting all generated files in the same directory would otherwise causes # performance problems for the file system. # The default value is: NO. CREATE_SUBDIRS = NO # If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII # characters to appear in the names of generated files. If set to NO, non-ASCII # characters will be escaped, for example _xE3_x81_x84 will be used for Unicode # U+3044. # The default value is: NO. ALLOW_UNICODE_NAMES = NO # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. # Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, # Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), # Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, # Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), # Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, # Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, # Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, # Ukrainian and Vietnamese. # The default value is: English. OUTPUT_LANGUAGE = English # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. # The default value is: YES. BRIEF_MEMBER_DESC = YES # If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief # description of a member or function before the detailed description # # Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. # The default value is: YES. REPEAT_BRIEF = YES # This tag implements a quasi-intelligent brief description abbreviator that is # used to form the text in various listings. Each string in this list, if found # as the leading text of the brief description, will be stripped from the text # and the result, after processing the whole list, is used as the annotated # text. Otherwise, the brief description is used as-is. If left blank, the # following values are used ($name is automatically replaced with the name of # the entity):The $name class, The $name widget, The $name file, is, provides, # specifies, contains, represents, a, an and the. ABBREVIATE_BRIEF = # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then # doxygen will generate a detailed section even if there is only a brief # description. # The default value is: NO. ALWAYS_DETAILED_SEC = YES # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all # inherited members of a class in the documentation of that class as if those # members were ordinary class members. Constructors, destructors and assignment # operators of the base classes will not be shown. # The default value is: NO. INLINE_INHERITED_MEMB = NO # If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path # before files name in the file list and in the header files. If set to NO the # shortest path that makes the file name unique will be used # The default value is: YES. FULL_PATH_NAMES = NO # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. # Stripping is only done if one of the specified strings matches the left-hand # part of the path. The tag can be used to show relative paths in the file list. # If left blank the directory from which doxygen is run is used as the path to # strip. # # Note that you can specify absolute paths here, but also relative paths, which # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. STRIP_FROM_PATH = # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which # header file to include in order to use a class. If left blank only the name of # the header file containing the class definition is used. Otherwise one should # specify the list of include paths that are normally passed to the compiler # using the -I flag. STRIP_FROM_INC_PATH = # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but # less readable) file names. This can be useful is your file systems doesn't # support long names like on DOS, Mac, or CD-ROM. # The default value is: NO. SHORT_NAMES = NO # If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the # first line (until the first dot) of a Javadoc-style comment as the brief # description. If set to NO, the Javadoc-style will behave just like regular Qt- # style comments (thus requiring an explicit @brief command for a brief # description.) # The default value is: NO. JAVADOC_AUTOBRIEF = NO # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If # set to NO, the Qt-style will behave just like regular Qt-style comments (thus # requiring an explicit \brief command for a brief description.) # The default value is: NO. QT_AUTOBRIEF = NO # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a # multi-line C++ special comment block (i.e. a block of //! or /// comments) as # a brief description. This used to be the default behavior. The new default is # to treat a multi-line C++ comment block as a detailed description. Set this # tag to YES if you prefer the old behavior instead. # # Note that setting this tag to YES also means that rational rose comments are # not recognized any more. # The default value is: NO. MULTILINE_CPP_IS_BRIEF = NO # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the # documentation from any documented member that it re-implements. # The default value is: YES. INHERIT_DOCS = YES # If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new # page for each member. If set to NO, the documentation of a member will be part # of the file/class/namespace that contains it. # The default value is: NO. SEPARATE_MEMBER_PAGES = NO # The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen # uses this value to replace tabs by spaces in code fragments. # Minimum value: 1, maximum value: 16, default value: 4. TAB_SIZE = 4 # This tag can be used to specify a number of aliases that act as commands in # the documentation. An alias has the form: # name=value # For example adding # "sideeffect=@par Side Effects:\n" # will allow you to put the command \sideeffect (or @sideeffect) in the # documentation, which will result in a user-defined paragraph with heading # "Side Effects:". You can put \n's in the value part of an alias to insert # newlines. ALIASES = # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class" # will allow you to use the command class in the itcl::class meaning. TCL_SUBST = # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all # members will be omitted, etc. # The default value is: NO. OPTIMIZE_OUTPUT_FOR_C = YES # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or # Python sources only. Doxygen will then generate output that is more tailored # for that language. For instance, namespaces will be presented as packages, # qualified scopes will look different, etc. # The default value is: NO. OPTIMIZE_OUTPUT_JAVA = NO # Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran # sources. Doxygen will then generate output that is tailored for Fortran. # The default value is: NO. OPTIMIZE_FOR_FORTRAN = NO # Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL # sources. Doxygen will then generate output that is tailored for VHDL. # The default value is: NO. OPTIMIZE_OUTPUT_VHDL = NO # Doxygen selects the parser to use depending on the extension of the files it # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and # language is one of the parsers supported by doxygen: IDL, Java, Javascript, # C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: # FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: # Fortran. In the later case the parser tries to guess whether the code is fixed # or free formatted code, this is the default for Fortran type files), VHDL. For # instance to make doxygen treat .inc files as Fortran files (default is PHP), # and .f files as C (default is Fortran), use: inc=Fortran f=C. # # Note: For files without extension you can use no_extension as a placeholder. # # Note that for custom extensions you also need to set FILE_PATTERNS otherwise # the files are not read by doxygen. EXTENSION_MAPPING = # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable # documentation. See http://daringfireball.net/projects/markdown/ for details. # The output of markdown processing is further processed by doxygen, so you can # mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in # case of backward compatibilities issues. # The default value is: YES. MARKDOWN_SUPPORT = YES # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can # be prevented in individual cases by putting a % sign in front of the word or # globally by setting AUTOLINK_SUPPORT to NO. # The default value is: YES. AUTOLINK_SUPPORT = YES # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want # to include (a tag file for) the STL sources as input, then you should set this # tag to YES in order to let doxygen match functions declarations and # definitions whose arguments contain STL classes (e.g. func(std::string); # versus func(std::string) {}). This also make the inheritance and collaboration # diagrams that involve STL classes more complete and accurate. # The default value is: NO. BUILTIN_STL_SUPPORT = NO # If you use Microsoft's C++/CLI language, you should set this option to YES to # enable parsing support. # The default value is: NO. CPP_CLI_SUPPORT = NO # Set the SIP_SUPPORT tag to YES if your project consists of sip (see: # http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen # will parse them like normal C++ but will assume all classes use public instead # of private inheritance when no explicit protection keyword is present. # The default value is: NO. SIP_SUPPORT = NO # For Microsoft's IDL there are propget and propput attributes to indicate # getter and setter methods for a property. Setting this option to YES will make # doxygen to replace the get and set methods by a property in the documentation. # This will only work if the methods are indeed getting or setting a simple # type. If this is not the case, or you want to show the methods anyway, you # should set this option to NO. # The default value is: YES. IDL_PROPERTY_SUPPORT = YES # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC # tag is set to YES then doxygen will reuse the documentation of the first # member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. # The default value is: NO. DISTRIBUTE_GROUP_DOC = NO # If one adds a struct or class to a group and this option is enabled, then also # any nested class or struct is added to the same group. By default this option # is disabled and one has to add nested compounds explicitly via \ingroup. # The default value is: NO. GROUP_NESTED_COMPOUNDS = NO # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that # type (e.g. under the Public Functions section). Set it to NO to prevent # subgrouping. Alternatively, this can be done per class using the # \nosubgrouping command. # The default value is: YES. SUBGROUPING = YES # When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions # are shown inside the group in which they are included (e.g. using \ingroup) # instead of on a separate page (for HTML and Man pages) or section (for LaTeX # and RTF). # # Note that this feature does not work in combination with # SEPARATE_MEMBER_PAGES. # The default value is: NO. INLINE_GROUPED_CLASSES = NO # When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions # with only public data fields or simple typedef fields will be shown inline in # the documentation of the scope in which they are defined (i.e. file, # namespace, or group documentation), provided this scope is documented. If set # to NO, structs, classes, and unions are shown on a separate page (for HTML and # Man pages) or section (for LaTeX and RTF). # The default value is: NO. INLINE_SIMPLE_STRUCTS = NO # When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or # enum is documented as struct, union, or enum with the name of the typedef. So # typedef struct TypeS {} TypeT, will appear in the documentation as a struct # with name TypeT. When disabled the typedef will appear as a member of a file, # namespace, or class. And the struct will be named TypeS. This can typically be # useful for C code in case the coding convention dictates that all compound # types are typedef'ed and only the typedef is referenced, never the tag name. # The default value is: NO. TYPEDEF_HIDES_STRUCT = NO # The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This # cache is used to resolve symbols given their name and scope. Since this can be # an expensive process and often the same symbol appears multiple times in the # code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small # doxygen will become slower. If the cache is too large, memory is wasted. The # cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range # is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 # symbols. At the end of a run doxygen will report the cache usage and suggest # the optimal cache size from a speed point of view. # Minimum value: 0, maximum value: 9, default value: 0. LOOKUP_CACHE_SIZE = 0 #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- # If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in # documentation are documented, even if no documentation was available. Private # class members and static file members will be hidden unless the # EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. # Note: This will also disable the warnings about undocumented members that are # normally produced when WARNINGS is set to YES. # The default value is: NO. EXTRACT_ALL = YES # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. # The default value is: NO. EXTRACT_PRIVATE = NO # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. # The default value is: NO. EXTRACT_PACKAGE = NO # If the EXTRACT_STATIC tag is set to YES, all static members of a file will be # included in the documentation. # The default value is: NO. EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined # locally in source files will be included in the documentation. If set to NO, # only classes defined in header files are included. Does not have any effect # for Java sources. # The default value is: YES. EXTRACT_LOCAL_CLASSES = YES # This flag is only useful for Objective-C code. If set to YES, local methods, # which are defined in the implementation section but not in the interface are # included in the documentation. If set to NO, only methods in the interface are # included. # The default value is: NO. EXTRACT_LOCAL_METHODS = NO # If this flag is set to YES, the members of anonymous namespaces will be # extracted and appear in the documentation as a namespace called # 'anonymous_namespace{file}', where file will be replaced with the base name of # the file that contains the anonymous namespace. By default anonymous namespace # are hidden. # The default value is: NO. EXTRACT_ANON_NSPACES = NO # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all # undocumented members inside documented classes or files. If set to NO these # members will be included in the various overviews, but no documentation # section is generated. This option has no effect if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_MEMBERS = NO # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set # to NO, these classes will be included in the various overviews. This option # has no effect if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_CLASSES = NO # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend # (class|struct|union) declarations. If set to NO, these declarations will be # included in the documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any # documentation blocks found inside the body of a function. If set to NO, these # blocks will be appended to the function's detailed documentation block. # The default value is: NO. HIDE_IN_BODY_DOCS = NO # The INTERNAL_DOCS tag determines if documentation that is typed after a # \internal command is included. If the tag is set to NO then the documentation # will be excluded. Set it to YES to include the internal documentation. # The default value is: NO. INTERNAL_DOCS = NO # If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file # names in lower-case letters. If set to YES, upper-case letters are also # allowed. This is useful if you have classes or files whose names only differ # in case and if your file system supports case sensitive file names. Windows # and Mac users are advised to set this option to NO. # The default value is: system dependent. CASE_SENSE_NAMES = YES # If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with # their full class and namespace scopes in the documentation. If set to YES, the # scope will be hidden. # The default value is: NO. HIDE_SCOPE_NAMES = NO # If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will # append additional text to a page's title, such as Class Reference. If set to # YES the compound reference will be hidden. # The default value is: NO. HIDE_COMPOUND_REFERENCE= NO # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of # the files that are included by a file in the documentation of that file. # The default value is: YES. SHOW_INCLUDE_FILES = YES # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each # grouped member an include statement to the documentation, telling the reader # which file to include in order to use the member. # The default value is: NO. SHOW_GROUPED_MEMB_INC = NO # If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include # files with double quotes in the documentation rather than with sharp brackets. # The default value is: NO. FORCE_LOCAL_INCLUDES = NO # If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the # documentation for inline members. # The default value is: YES. INLINE_INFO = YES # If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the # (detailed) documentation of file and class members alphabetically by member # name. If set to NO, the members will appear in declaration order. # The default value is: YES. SORT_MEMBER_DOCS = NO # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member # name. If set to NO, the members will appear in declaration order. Note that # this will also influence the order of the classes in the class list. # The default value is: NO. SORT_BRIEF_DOCS = NO # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the # (brief and detailed) documentation of class members so that constructors and # destructors are listed first. If set to NO the constructors will appear in the # respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. # Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief # member documentation. # Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting # detailed member documentation. # The default value is: NO. SORT_MEMBERS_CTORS_1ST = NO # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy # of group names into alphabetical order. If set to NO the group names will # appear in their defined order. # The default value is: NO. SORT_GROUP_NAMES = NO # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by # fully-qualified names, including namespaces. If set to NO, the class list will # be sorted only by class name, not including the namespace part. # Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. # Note: This option applies only to the class list, not to the alphabetical # list. # The default value is: NO. SORT_BY_SCOPE_NAME = NO # If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper # type resolution of all parameters of a function it will reject a match between # the prototype and the implementation of a member function even if there is # only one candidate or it is obvious which candidate to choose by doing a # simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still # accept a match between prototype and implementation in such cases. # The default value is: NO. STRICT_PROTO_MATCHING = NO # The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo # list. This list is created by putting \todo commands in the documentation. # The default value is: YES. GENERATE_TODOLIST = YES # The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test # list. This list is created by putting \test commands in the documentation. # The default value is: YES. GENERATE_TESTLIST = YES # The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug # list. This list is created by putting \bug commands in the documentation. # The default value is: YES. GENERATE_BUGLIST = YES # The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) # the deprecated list. This list is created by putting \deprecated commands in # the documentation. # The default value is: YES. GENERATE_DEPRECATEDLIST= YES # The ENABLED_SECTIONS tag can be used to enable conditional documentation # sections, marked by \if ... \endif and \cond # ... \endcond blocks. ENABLED_SECTIONS = # The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the # initial value of a variable or macro / define can have for it to appear in the # documentation. If the initializer consists of more lines than specified here # it will be hidden. Use a value of 0 to hide initializers completely. The # appearance of the value of individual variables and macros / defines can be # controlled using \showinitializer or \hideinitializer command in the # documentation regardless of this setting. # Minimum value: 0, maximum value: 10000, default value: 30. MAX_INITIALIZER_LINES = 30 # Set the SHOW_USED_FILES tag to NO to disable the list of files generated at # the bottom of the documentation of classes and structs. If set to YES, the # list will mention the files that were used to generate the documentation. # The default value is: YES. SHOW_USED_FILES = YES # Set the SHOW_FILES tag to NO to disable the generation of the Files page. This # will remove the Files entry from the Quick Index and from the Folder Tree View # (if specified). # The default value is: YES. SHOW_FILES = YES # Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces # page. This will remove the Namespaces entry from the Quick Index and from the # Folder Tree View (if specified). # The default value is: YES. SHOW_NAMESPACES = YES # The FILE_VERSION_FILTER tag can be used to specify a program or script that # doxygen should invoke to get the current version for each file (typically from # the version control system). Doxygen will invoke the program by executing (via # popen()) the command command input-file, where command is the value of the # FILE_VERSION_FILTER tag, and input-file is the name of an input file provided # by doxygen. Whatever the program writes to standard output is used as the file # version. For an example see the documentation. FILE_VERSION_FILTER = # The LAYOUT_FILE tag can be used to specify a layout file which will be parsed # by doxygen. The layout file controls the global structure of the generated # output files in an output format independent way. To create the layout file # that represents doxygen's defaults, run doxygen with the -l option. You can # optionally specify a file name after the option, if omitted DoxygenLayout.xml # will be used as the name of the layout file. # # Note that if you run doxygen from a directory containing a file called # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib # extension is automatically appended if omitted. This requires the bibtex tool # to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. # For LaTeX the style of the bibliography can be controlled using # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the # search path. See also \cite for info how to create references. CITE_BIB_FILES = #--------------------------------------------------------------------------- # Configuration options related to warning and progress messages #--------------------------------------------------------------------------- # The QUIET tag can be used to turn on/off the messages that are generated to # standard output by doxygen. If QUIET is set to YES this implies that the # messages are off. # The default value is: NO. QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES # this implies that the warnings are on. # # Tip: Turn warnings on while writing the documentation. # The default value is: YES. WARNINGS = YES # If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: YES. WARN_IF_UNDOCUMENTED = YES # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some parameters # in a documented function, or documenting parameters that don't exist or using # markup commands wrongly. # The default value is: YES. WARN_IF_DOC_ERROR = YES # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return # value. If set to NO, doxygen will only warn about wrong or incomplete # parameter documentation, but not about the absence of documentation. # The default value is: NO. WARN_NO_PARAMDOC = NO # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when # a warning is encountered. # The default value is: NO. WARN_AS_ERROR = NO # The WARN_FORMAT tag determines the format of the warning messages that doxygen # can produce. The string should contain the $file, $line, and $text tags, which # will be replaced by the file and line number from which the warning originated # and the warning text. Optionally the format may contain $version, which will # be replaced by the version of the file (if it could be obtained via # FILE_VERSION_FILTER) # The default value is: $file:$line: $text. WARN_FORMAT = "$file:$line: $text" # The WARN_LOGFILE tag can be used to specify a file to which warning and error # messages should be written. If left blank the output is written to standard # error (stderr). WARN_LOGFILE = #--------------------------------------------------------------------------- # Configuration options related to the input files #--------------------------------------------------------------------------- # The INPUT tag is used to specify the files and/or directories that contain # documented source files. You may enter file names like myfile.cpp or # directories like /usr/src/myproject. Separate the files or directories with # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. INPUT = @srcdir@/getdns/ \ getdns/getdns.h \ getdns/getdns_extra.h \ @srcdir@/../README.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # libiconv (or the iconv built into libc) for the transcoding. See the libiconv # documentation (see: http://www.gnu.org/software/libiconv) for the list of # possible encodings. # The default value is: UTF-8. INPUT_ENCODING = UTF-8 # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and # *.h) to filter out the source-files in the directories. # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # read by doxygen. # # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, # *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, # *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, # *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f, *.for, *.tcl, # *.vhd, *.vhdl, *.ucf, *.qsf, *.as and *.js. FILE_PATTERNS = # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. # The default value is: NO. RECURSIVE = NO # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. # # Note that relative paths are relative to the directory from which doxygen is # run. EXCLUDE = config.h # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded # from the input. # The default value is: NO. EXCLUDE_SYMLINKS = NO # If the value of the INPUT tag contains directories, you can use the # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude # certain files from those directories. # # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* EXCLUDE_PATTERNS = # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the # output. The symbol name can be a fully qualified name, a word, or if the # wildcard * is used, a substring. Examples: ANamespace, AClass, # AClass::ANamespace, ANamespace::*Test # # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories use the pattern */test/* EXCLUDE_SYMBOLS = # The EXAMPLE_PATH tag can be used to specify one or more files or directories # that contain example code fragments that are included (see the \include # command). EXAMPLE_PATH = example/ # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and # *.h) to filter out the source-files in the directories. If left blank all # files are included. EXAMPLE_PATTERNS = # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be # searched for input files to be used with the \include or \dontinclude commands # irrespective of the value of the RECURSIVE tag. # The default value is: NO. EXAMPLE_RECURSIVE = NO # The IMAGE_PATH tag can be used to specify one or more files or directories # that contain images that are to be included in the documentation (see the # \image command). IMAGE_PATH = # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program # by executing (via popen()) the command: # # # # where is the value of the INPUT_FILTER tag, and is the # name of an input file. Doxygen will then use the output that the filter # program writes to standard output. If FILTER_PATTERNS is specified, this tag # will be ignored. # # Note that the filter must not add or remove lines; it is applied before the # code is scanned, but not when the output code is generated. If lines are added # or removed, the anchors will not be placed correctly. # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. INPUT_FILTER = # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern # basis. Doxygen will compare the file name with each pattern and apply the # filter if there is a match. The filters are a list of the form: pattern=filter # (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how # filters are used. If the FILTER_PATTERNS tag is empty or if none of the # patterns match the file name, INPUT_FILTER is applied. # # Note that for custom extensions or not directly supported extensions you also # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. FILTER_PATTERNS = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using # INPUT_FILTER) will also be used to filter the input files that are used for # producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). # The default value is: NO. FILTER_SOURCE_FILES = NO # The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file # pattern. A pattern will override the setting for FILTER_PATTERN (if any) and # it is also possible to disable source filtering for a specific pattern using # *.ext= (so without naming a filter). # This tag requires that the tag FILTER_SOURCE_FILES is set to YES. FILTER_SOURCE_PATTERNS = # If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that # is part of the input, its contents will be placed on the main page # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. USE_MDFILE_AS_MAINPAGE = @srcdir@/../README.md #--------------------------------------------------------------------------- # Configuration options related to source browsing #--------------------------------------------------------------------------- # If the SOURCE_BROWSER tag is set to YES then a list of source files will be # generated. Documented entities will be cross-referenced with these sources. # # Note: To get rid of all source code in the generated output, make sure that # also VERBATIM_HEADERS is set to NO. # The default value is: NO. SOURCE_BROWSER = YES # Setting the INLINE_SOURCES tag to YES will include the body of functions, # classes and enums directly into the documentation. # The default value is: NO. INLINE_SOURCES = NO # Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any # special comment blocks from generated source code fragments. Normal C, C++ and # Fortran comments will always remain visible. # The default value is: YES. STRIP_CODE_COMMENTS = YES # If the REFERENCED_BY_RELATION tag is set to YES then for each documented # function all documented functions referencing it will be listed. # The default value is: NO. REFERENCED_BY_RELATION = NO # If the REFERENCES_RELATION tag is set to YES then for each documented function # all documented entities called/used by that function will be listed. # The default value is: NO. REFERENCES_RELATION = NO # If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set # to YES then the hyperlinks from functions in REFERENCES_RELATION and # REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will # link to the documentation. # The default value is: YES. REFERENCES_LINK_SOURCE = YES # If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the # source code will show a tooltip with additional information such as prototype, # brief description and links to the definition and documentation. Since this # will make the HTML file larger and loading of large files a bit slower, you # can opt to disable this feature. # The default value is: YES. # This tag requires that the tag SOURCE_BROWSER is set to YES. SOURCE_TOOLTIPS = YES # If the USE_HTAGS tag is set to YES then the references to source code will # point to the HTML generated by the htags(1) tool instead of doxygen built-in # source browser. The htags tool is part of GNU's global source tagging system # (see http://www.gnu.org/software/global/global.html). You will need version # 4.8.6 or higher. # # To use it do the following: # - Install the latest version of global # - Enable SOURCE_BROWSER and USE_HTAGS in the config file # - Make sure the INPUT points to the root of the source tree # - Run doxygen as normal # # Doxygen will invoke htags (and that will in turn invoke gtags), so these # tools must be available from the command line (i.e. in the search path). # # The result: instead of the source browser generated by doxygen, the links to # source code will now point to the output of htags. # The default value is: NO. # This tag requires that the tag SOURCE_BROWSER is set to YES. USE_HTAGS = NO # If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a # verbatim copy of the header file for each class for which an include is # specified. Set to NO to disable this. # See also: Section \class. # The default value is: YES. VERBATIM_HEADERS = YES # If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the # clang parser (see: http://clang.llvm.org/) for more accurate parsing at the # cost of reduced performance. This can be particularly helpful with template # rich C++ code for which doxygen's built-in parser lacks the necessary type # information. # Note: The availability of this option depends on whether or not doxygen was # generated with the -Duse-libclang=ON option for CMake. # The default value is: NO. CLANG_ASSISTED_PARSING = NO # If clang assisted parsing is enabled you can provide the compiler with command # line options that you would normally use when invoking the compiler. Note that # the include paths will already be set by doxygen for the files and directories # specified with INPUT and INCLUDE_PATH. # This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. CLANG_OPTIONS = #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- # If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all # compounds will be generated. Enable this if the project contains a lot of # classes, structs, unions or interfaces. # The default value is: YES. ALPHABETICAL_INDEX = YES # The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in # which the alphabetical index list will be split. # Minimum value: 1, maximum value: 20, default value: 5. # This tag requires that the tag ALPHABETICAL_INDEX is set to YES. COLS_IN_ALPHA_INDEX = 5 # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored # while generating the index headers. # This tag requires that the tag ALPHABETICAL_INDEX is set to YES. IGNORE_PREFIX = #--------------------------------------------------------------------------- # Configuration options related to the HTML output #--------------------------------------------------------------------------- # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. GENERATE_HTML = YES # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of # it. # The default directory is: html. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_OUTPUT = html # The HTML_FILE_EXTENSION tag can be used to specify the file extension for each # generated HTML page (for example: .htm, .php, .asp). # The default value is: .html. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_FILE_EXTENSION = .html # The HTML_HEADER tag can be used to specify a user-defined HTML header file for # each generated HTML page. If the tag is left blank doxygen will generate a # standard header. # # To get valid HTML the header file that includes any scripts and style sheets # that doxygen needs, which is dependent on the configuration options used (e.g. # the setting GENERATE_TREEVIEW). It is highly recommended to start with a # default header using # doxygen -w html new_header.html new_footer.html new_stylesheet.css # YourConfigFile # and then modify the file new_header.html. See also section "Doxygen usage" # for information on how to generate the default header that doxygen normally # uses. # Note: The header is subject to change so you typically have to regenerate the # default header when upgrading to a newer version of doxygen. For a description # of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_HEADER = # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each # generated HTML page. If the tag is left blank doxygen will generate a standard # footer. See HTML_HEADER for more information on how to generate a default # footer and what special commands can be used inside the footer. See also # section "Doxygen usage" for information on how to generate the default footer # that doxygen normally uses. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_FOOTER = # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style # sheet that is used by each HTML page. It can be used to fine-tune the look of # the HTML output. If left blank doxygen will generate a default style sheet. # See also section "Doxygen usage" for information on how to generate the style # sheet that doxygen normally uses. # Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as # it is more robust and this tag (HTML_STYLESHEET) will in the future become # obsolete. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_STYLESHEET = # The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined # cascading style sheets that are included after the standard style sheets # created by doxygen. Using this option one can overrule certain style aspects. # This is preferred over using HTML_STYLESHEET since it does not replace the # standard style sheet and is therefore more robust against future updates. # Doxygen will copy the style sheet files to the output directory. # Note: The order of the extra style sheet files is of importance (e.g. the last # style sheet in the list overrules the setting of the previous ones in the # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_EXTRA_STYLESHEET = # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note # that these files will be copied to the base HTML output directory. Use the # $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these # files. In the HTML_STYLESHEET file, use the file name only. Also note that the # files will be copied as-is; there are no commands or markers available. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_EXTRA_FILES = # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to # this color. Hue is specified as an angle on a colorwheel, see # http://en.wikipedia.org/wiki/Hue for more information. For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 # purple, and 360 is red again. # Minimum value: 0, maximum value: 359, default value: 220. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_HUE = 220 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors # in the HTML output. For a value of 0 the output will use grayscales only. A # value of 255 will produce the most vivid colors. # Minimum value: 0, maximum value: 255, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_SAT = 100 # The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the # luminance component of the colors in the HTML output. Values below 100 # gradually make the output lighter, whereas values above 100 make the output # darker. The value divided by 100 is the actual gamma applied, so 80 represents # a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not # change the gamma. # Minimum value: 40, maximum value: 240, default value: 80. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_GAMMA = 80 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML # page will contain the date and time when the page was generated. Setting this # to YES can help to show when doxygen was last run and thus if the # documentation is up to date. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_TIMESTAMP = YES # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the # page has loaded. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_DYNAMIC_SECTIONS = NO # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries # shown in the various tree structured indices initially; the user can expand # and collapse entries dynamically later on. Doxygen will expand the tree to # such a level that at most the specified number of entries are visible (unless # a fully collapsed tree already exceeds this amount). So setting the number of # entries 1 will produce a full collapsed tree by default. 0 is a special value # representing an infinite number of entries and will result in a full expanded # tree by default. # Minimum value: 0, maximum value: 9999, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_INDEX_NUM_ENTRIES = 100 # If the GENERATE_DOCSET tag is set to YES, additional index files will be # generated that can be used as input for Apple's Xcode 3 integrated development # environment (see: http://developer.apple.com/tools/xcode/), introduced with # OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a # Makefile in the HTML output directory. Running make will produce the docset in # that directory and running make install will install the docset in # ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at # startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html # for more information. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_DOCSET = NO # This tag determines the name of the docset feed. A documentation feed provides # an umbrella under which multiple documentation sets from a single provider # (such as a company or product suite) can be grouped. # The default value is: Doxygen generated docs. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_FEEDNAME = "Doxygen generated docs" # This tag specifies a string that should uniquely identify the documentation # set bundle. This should be a reverse domain-name style string, e.g. # com.mycompany.MyDocSet. Doxygen will append .docset to the name. # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_BUNDLE_ID = org.doxygen.Project # The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify # the documentation publisher. This should be a reverse domain-name style # string, e.g. com.mycompany.MyDocSet.documentation. # The default value is: org.doxygen.Publisher. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_PUBLISHER_ID = org.doxygen.Publisher # The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. # The default value is: Publisher. # This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_PUBLISHER_NAME = Publisher # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop # (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on # Windows. # # The HTML Help Workshop contains a compiler that can convert all HTML output # generated by doxygen into a single compiled HTML file (.chm). Compiled HTML # files are now used as the Windows 98 help format, and will replace the old # Windows help format (.hlp) on all Windows platforms in the future. Compressed # HTML files also contain an index, a table of contents, and you can search for # words in the documentation. The HTML workshop also contains a viewer for # compressed HTML files. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_HTMLHELP = NO # The CHM_FILE tag can be used to specify the file name of the resulting .chm # file. You can add a path in front of the file if the result should not be # written to the html output directory. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_FILE = # The HHC_LOCATION tag can be used to specify the location (absolute path # including file name) of the HTML help compiler (hhc.exe). If non-empty, # doxygen will try to run the HTML help compiler on the generated index.hhp. # The file has to be specified with full path. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. HHC_LOCATION = # The GENERATE_CHI flag controls if a separate .chi index file is generated # (YES) or that it should be included in the master .chm file (NO). # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. GENERATE_CHI = NO # The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) # and project file content. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_INDEX_ENCODING = # The BINARY_TOC flag controls whether a binary table of contents is generated # (YES) or a normal table of contents (NO) in the .chm file. Furthermore it # enables the Previous and Next buttons. # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. BINARY_TOC = NO # The TOC_EXPAND flag can be set to YES to add extra items for group members to # the table of contents of the HTML help documentation and to the tree view. # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. TOC_EXPAND = NO # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and # QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that # can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help # (.qch) of the generated HTML documentation. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_QHP = NO # If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify # the file name of the resulting .qch file. The path specified is relative to # the HTML output folder. # This tag requires that the tag GENERATE_QHP is set to YES. QCH_FILE = # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help # Project output. For more information please see Qt Help Project / Namespace # (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_QHP is set to YES. QHP_NAMESPACE = org.doxygen.Project # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt # Help Project output. For more information please see Qt Help Project / Virtual # Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- # folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. QHP_VIRTUAL_FOLDER = doc # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom # filter to add. For more information please see Qt Help Project / Custom # Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- # filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_NAME = # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the # custom filter to add. For more information please see Qt Help Project / Custom # Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- # filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_ATTRS = # The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this # project's filter section matches. Qt Help Project / Filter Attributes (see: # http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_SECT_FILTER_ATTRS = # The QHG_LOCATION tag can be used to specify the location of Qt's # qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the # generated .qhp file. # This tag requires that the tag GENERATE_QHP is set to YES. QHG_LOCATION = # If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be # generated, together with the HTML files, they form an Eclipse help plugin. To # install this plugin and make it available under the help contents menu in # Eclipse, the contents of the directory containing the HTML and XML files needs # to be copied into the plugins directory of eclipse. The name of the directory # within the plugins directory should be the same as the ECLIPSE_DOC_ID value. # After copying Eclipse needs to be restarted before the help appears. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_ECLIPSEHELP = NO # A unique identifier for the Eclipse help plugin. When installing the plugin # the directory name containing the HTML and XML files should also have this # name. Each documentation set should have its own identifier. # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. ECLIPSE_DOC_ID = org.doxygen.Project # If you want full control over the layout of the generated HTML pages it might # be necessary to disable the index and replace it with your own. The # DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top # of each HTML page. A value of NO enables the index and the value YES disables # it. Since the tabs in the index contain the same information as the navigation # tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. DISABLE_INDEX = NO # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index # structure should be generated to display hierarchical information. If the tag # value is set to YES, a side panel will be generated containing a tree-like # index structure (just like the one that is generated for HTML Help). For this # to work a browser that supports JavaScript, DHTML, CSS and frames is required # (i.e. any modern browser). Windows users are probably better off using the # HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can # further fine-tune the look of the index. As an example, the default style # sheet generated by doxygen has an example that shows how to put an image at # the root of the tree instead of the PROJECT_NAME. Since the tree basically has # the same information as the tab index, you could consider setting # DISABLE_INDEX to YES when enabling this option. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_TREEVIEW = NO # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that # doxygen will group on one line in the generated HTML documentation. # # Note that a value of 0 will completely suppress the enum values from appearing # in the overview section. # Minimum value: 0, maximum value: 20, default value: 4. # This tag requires that the tag GENERATE_HTML is set to YES. ENUM_VALUES_PER_LINE = 4 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used # to set the initial width (in pixels) of the frame in which the tree is shown. # Minimum value: 0, maximum value: 1500, default value: 250. # This tag requires that the tag GENERATE_HTML is set to YES. TREEVIEW_WIDTH = 250 # If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to # external symbols imported via tag files in a separate window. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. EXT_LINKS_IN_WINDOW = NO # Use this tag to change the font size of LaTeX formulas included as images in # the HTML documentation. When you change the font size after a successful # doxygen run you need to manually remove any form_*.png images from the HTML # output directory to force them to be regenerated. # Minimum value: 8, maximum value: 50, default value: 10. # This tag requires that the tag GENERATE_HTML is set to YES. FORMULA_FONTSIZE = 10 # Use the FORMULA_TRANPARENT tag to determine whether or not the images # generated for formulas are transparent PNGs. Transparent PNGs are not # supported properly for IE 6.0, but are supported on all modern browsers. # # Note that when changing this option you need to delete any form_*.png files in # the HTML output directory before the changes have effect. # The default value is: YES. # This tag requires that the tag GENERATE_HTML is set to YES. FORMULA_TRANSPARENT = YES # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see # http://www.mathjax.org) which uses client side Javascript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path # to it using the MATHJAX_RELPATH option. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. USE_MATHJAX = NO # When MathJax is enabled you can set the default output format to be used for # the MathJax output. See the MathJax site (see: # http://docs.mathjax.org/en/latest/output.html) for more details. # Possible values are: HTML-CSS (which is slower, but has the best # compatibility), NativeMML (i.e. MathML) and SVG. # The default value is: HTML-CSS. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_FORMAT = HTML-CSS # When MathJax is enabled you need to specify the location relative to the HTML # output directory using the MATHJAX_RELPATH option. The destination directory # should contain the MathJax.js script. For instance, if the mathjax directory # is located at the same level as the HTML output directory, then # MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax # Content Delivery Network so you can quickly see the result without installing # MathJax. However, it is strongly recommended to install a local copy of # MathJax from http://www.mathjax.org before deployment. # The default value is: http://cdn.mathjax.org/mathjax/latest. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_EXTENSIONS = # The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces # of code that will be used on startup of the MathJax code. See the MathJax site # (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an # example see the documentation. # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_CODEFILE = # When the SEARCHENGINE tag is enabled doxygen will generate a search box for # the HTML output. The underlying search engine uses javascript and DHTML and # should work on any modern browser. Note that when using HTML help # (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) # there is already a search function so this one should typically be disabled. # For large projects the javascript based search engine can be slow, then # enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to # search using the keyboard; to jump to the search box use + S # (what the is depends on the OS and browser, but it is typically # , /