--- name: "libsres" section: "3" platform: "linux" package: "dnssec-tools" version: "2.2.3-16" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libsres" --- # libsres(3) send queries and receive responses from a DNS name server. clone\_ns(), clone\_ns\_list(), free\_name\_server(), free\_name\_servers() - manage name server lists print\_response() - display answers returned from the name server ## NAME query\_send(), response\_rcv(), get() - send queries and receive responses from a DNS name server. clone\_ns(), clone\_ns\_list(), free\_name\_server(), free\_name\_servers() - manage name server lists print\_response() - display answers returned from the name server ## SYNOPSIS ``` #include int query_send(const char *name, const unsigned short type, const unsigned short class, struct name_server *nslist, int edns0_size, int *trans_id); int response_recv(int *trans_id, fd_set *pending_desc, struct timeval *closest_event, struct name_server **respondent, unsigned char **response, size_t *response_length); int get(const char *name_n, const unsigned short type_h, const unsigned short class_h, struct name_server *nslist, struct name_server **respondent, unsigned char **response, size_t *response_length); int clone_ns(struct name_server **cloned_ns, struct name_server *ns); int clone_ns_list(struct name_server **ns_list, struct name_server *orig_ns_list); void free_name_server(struct name_server **ns); void free_name_servers(struct name_server **ns); void print_response(unsigned char *response, size_t response_length); ``` ## DESCRIPTION The *query\_send()* function sends a query to the name servers specified in *nslist*. The query is comprised of the \<*name, class, type*\> tuple and *trans\_id* provides a handle to this transaction within the *libsres* library. The buffer size advertised in the EDNS0 option can be set using the *ends0\_size* argument. The *response\_recv()* function returns the answers, if available, from the name server that responds for the query identified by *trans\_id*. The response is available in *response* and the responding name server is returned in *respondent*. The length of the response in bytes is returned in *response\_length*. The *get()* function provides a wrapper around the *query\_send()* and *response\_recv()* functions. After sending a request, it blocks until a response is received from some name server or until the request times out. The *libsres* library does not automatically follow referrals; responses containing referrals are treated as valid responses. The memory pointed to by *\*respondent* is internally allocated by the *libsres* library and must be freed by the invoker using *free\_name\_server()*. An entire list of name servers can be freed using *free\_name\_servers()*. A copy of the name server can be created using *clone\_ns()* and a copy of a name server list can be made using *clone\_ns\_list()*. *print\_response()* provides a convenient way to display answers returned in *response* by the name server. The *name\_server* structure is defined in **resolver.h** as follows: ``` #define NS_MAXCDNAME 255 struct name_server { unsigned char ns_name_n[NS_MAXCDNAME]; void *ns_tsig; unsigned int ns_security_options; unsigned int ns_status; unsigned long ns_options; int ns_retry; int ns_retrans; struct name_server *ns_next; int ns_number_of_addresses; struct sockaddr_storage **ns_address; }; ``` - *ns\_name\_n* The name of the zone for which this name server is authoritative. - *ns\_tsig* The *tsig* key that should be used to protect messages sent to this name server. This field is currently unused and must be set to NULL. - *ns\_security\_options* The security options for the zone. This field is currently unused and must be set to **ZONE\_USE\_NOTHING**. - *ns\_status* The status of the zone. This field indicates how the zone information was obtained. The invoker must set this value to **SR\_ZI\_STATUS\_UNSET**. Zone information obtained through referrals have a value of **SR\_ZI\_STATUS\_LEARNED** for this field. - *ns\_options* Specifies additional resolver flags. Currently defined flags are **SR\_QUERY\_RECURSE**, which sets the "Recursion Desired" flag; **SR\_QUERY\_SET\_DO**, which sets the "DNSSEC OK" bit in the EDNS0 header; **SR\_QUERY\_SET\_CD**, which sets the "DNSSEC CD" bit in the EDNS0 header; and **SR\_QUERY\_DEBUG**, which enables debugging. **SR\_QUERY\_VALIDATING\_STUB\_FLAGS** sets both **SR\_QUERY\_SET\_DO** and **SR\_QUERY\_SET\_CD**. - *ns\_retry* Specifies the maximum number of attempts that must be made to obtain a name from an unresponsive name server before giving up. - *ns\_retrans* Specifies the retransmission interval in seconds for queries sent to unresponsive name servers. - *ns\_next* The address of the next name server in the list. - *ns\_number\_of\_addresses* The number of elements in the array *ns\_addresses*. This field is currently unused. - *ns\_addresses* The IP address of the name server. ## OTHER SYMBOLS EXPORTED The *libsres* library also exports the following BIND functions, documentation for which can be found in the BIND sources and documentation manuals: ``` res_nametoclass res_nametotype ns_name_ntop ns_name_pton ns_name_unpack ns_parse_ttl p_class p_section p_type ``` The *p\_type()* function exported from *libsres* has been augmented such that it recognizes the various DNSSEC type codes such DNSKEY, RRSIG, NSEC, NSEC3 and DLV. ## RETURN VALUES - **SR\_UNSET** No error. - **SR\_CALL\_ERROR** An invalid parameter was passed to *get()*, *query\_send()*, or *response\_recv()*. - **SR\_INTERNAL\_ERROR** The resolver encountered some internal error. - **SR\_TSIG\_ERROR** The resolver encountered some TSIG-related error. This is currently not implemented. - **SR\_NO\_ANSWER** No answers were received from any name server. - **SR\_NO\_ANSWER\_YET** No answer currently available; the query is still active. - **SR\_HEADER\_ERROR** The length and count of records in the header were incorrect. - **SR\_NXDOMAIN** The queried name did not exist. - **SR\_FORMERR** The name server was not able to parse the query message. - **SR\_SERVFAIL** The name server was not reachable. - **SR\_NOTIMPL** A particular functionality is not yet implemented. - **SR\_REFUSED** The name server refused to answer this query. - **SR\_DNS\_GENERIC\_FAILURE** Other failure returned by the name server and reflected in the returned message **RCODE**. - **SR\_EDNS\_VERSION\_ERROR** The EDNS version was not recognized - **SR\_NAME\_EXPANSION\_FAILURE** A failure was encountered while trying to expand a compressed domain name. ## CURRENT STATUS There is currently no support for IPv6. There is limited support for specifying resolver policy; members of the *struct name\_server* are still subject to change. ## COPYRIGHT Copyright 2004-2013 SPARTA, Inc. All rights reserved. See the COPYING file included with the dnssec-tools package for details. ## SEE ALSO *[libval(3)](/libval/3.md)* http://www.dnssec-tools.org