Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
getdns_general(3)		    getdns		     getdns_general(3)

NAME
       getdns_general, getdns_general_sync -- do a getdns DNS lookup

LIBRARY
       DNS Resolver library (libgetdns,	-lgetdns)

SYNOPSIS
       #include	<getdns.h>

       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)

       getdns_return_t
       getdns_general_sync (getdns_context *context,
	  const	char *name,
	  uint16_t request_type
	  getdns_dict *extensions,
	  getdns_dict **response)

DESCRIPTION
       The  getdns_general(3) and getdns_general_sync functions	provide	public
       entry points into the getdns API	library	 to  retrieve  any  valid  re-
       sponses to a query from the DNS (note that other	namespaces in the con-
       text are	not used).   Most typical use cases for	applications are prob-
       ably  satisifed	via  calls  to	getdns_address(3)  which would replace
       getaddrinfo(3).

       context A pointer to the	previsouly created DNS context that is	to  be
	  used with this DNS request. see getdns_context (3)

       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 in-
	  stead	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.

       request_type Specifies the RRtype for the query;	the RRtype numbers are
	  listed in the	IANA registry. For example, to get the NS records, re-
	  quest_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.

       extensions extensions for this request,	NULL  if  no  extensions,  see
	  libgetnds (3)	for a detailed description of extensions

       userarg returned	to the callback	function untouched, can	be NULL

       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

       callbackfn  non-NULL  pointer to	a callback function defined by the ap-
	  plication, typically used to process the response.  Only  the	 asyn-
	  chronous signature accepts a callback	function, the synchronous sig-
	  nature does not include a callback.  See libgetdns (3)  for  a  more
	  detailed discussion of callback functions.

       response	A getdns_dict type is returned in response and always contains
	  at least three names:	replies_full (a	list containing	 the  DNS  re-
	  sponse  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).

RETURN VALUES
       Upon  successful	 completion  the functions return GETDNS_RETURN_GOOD ,
       otherwise the following error values are	returned:

       GETDNS_RETURN_BAD_CONTEXT if the	context	pointer	is invalid or the con-
       text has	internal deficiencies

       GETDNS_RETURN_BAD_DOMAIN_NAME if	the domain name	passed to the function
       is invalid

       GETDNS_RETURN_EXTENSION_MISFORMAT if the	data type specified in one  or
       more of the extensions does not match the specifications

       GETDNS_RETURN_GENERIC_ERROR  if	some  problem  was  encountered	in the
       function	not addressed by one of	the more specific return codes

       GETDNS_RETURN_INVALID PARAMETER if one or more parameters  has  an  in-
       valid value

       GETDNS_RETURN_MEMORY_ERROR if unable to allocate	the memory required

       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:

       GETDNS_RESPSTATUS_GOOD if at least one response was returned

       GETDNS_RESPSTATUS_NO_NAME if queries for	the name yielded all  negative
       responses

       GETDNS_RESPSTATUS_ALL_TIMEOUT if	all queries for	the name timed out

       GETDNS_RESPSTATUS_NO_SECURE_ANSWERS  if	only  secure  replies accepted
       (per context) and at least one response was received  but  no  DNS  re-
       sponses were secure through DNSSEC

       For  a  more  detailed explanation of the response object see libgetdns
       (3)

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/assign-
       ments/dns-parameters/dns-parameters.xml

	  A	     Host address

	  AAAA	     IPv6 address

	  CAA	     Certificate Authority Authorization

	  CNAME	     Canonical name for	an alias

	  DLV	     DNSSEC lookaside validation

	  DNAME	     DNAME

	  DS	     Delegation	signer

	  HINFO	     Host information

	  KEY	     Security key

	  MINFO	     Mailbox or	mail list information

	  MX	     Mail exchange

	  NS	     Authoritative name	server

	  NSEC	     Next secure record

	  NSEC3	     Next secure record	(hashed)

	  NSEC3PARAM NSEC3PARAM

	  PTR	     Domain name pointer

	  RRSIG	     Signature for a record set

	  SIG	     Security signature

	  SOA	     Marks the start of	a zone of authority

	  SRV	     Server selection

	  TA	     DNSSEC trust authorities

	  TKEY	     Transaction key

	  TLSA	     TLSA

	  TSIG	     Transaction signature

	  TXT	     Text strings

EXAMPLES
       TBD

FILES
       /etc/hosts
       /etc/resolv.conf

SEE ALSO
       libgetdns(3),	       getdns_address(3),	    getdns_context(3),
       getdns_free_sync_request_memory(3),   getdns_hostname(3),   getdns_ser-
       vice(3),

getdns 1.5.2			 December 2015		     getdns_general(3)

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | REQUEST TYPES | EXAMPLES | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getdns_general&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help