.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "libsres 3" .TH libsres 3 "2013-01-02" "perl v5.18.1" "Programmer's Manual" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" query_send(), response_rcv(), get() \- send queries and receive responses from a DNS name server. .PP clone_ns(), clone_ns_list(), free_name_server(), free_name_servers() \- manage name server lists .PP print_response() \- display answers returned from the name server .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #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); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \fI\fIquery_send()\fI\fR function sends a query to the name servers specified in \&\fInslist\fR. The query is comprised of the <\fIname, class, type\fR> tuple and \&\fItrans_id\fR provides a handle to this transaction within the \fIlibsres\fR library. The buffer size advertised in the \s-1EDNS0\s0 option can be set using the \fIends0_size\fR argument. .PP The \fI\fIresponse_recv()\fI\fR function returns the answers, if available, from the name server that responds for the query identified by \fItrans_id\fR. The response is available in \fIresponse\fR and the responding name server is returned in \fIrespondent\fR. The length of the response in bytes is returned in \fIresponse_length\fR. .PP The \fI\fIget()\fI\fR function provides a wrapper around the \fI\fIquery_send()\fI\fR and \&\fI\fIresponse_recv()\fI\fR functions. After sending a request, it blocks until a response is received from some name server or until the request times out. The \fIlibsres\fR library does not automatically follow referrals; responses containing referrals are treated as valid responses. .PP The memory pointed to by \fI*respondent\fR is internally allocated by the \&\fIlibsres\fR library and must be freed by the invoker using \&\fI\fIfree_name_server()\fI\fR. An entire list of name servers can be freed using \&\fI\fIfree_name_servers()\fI\fR. A copy of the name server can be created using \&\fI\fIclone_ns()\fI\fR and a copy of a name server list can be made using \&\fI\fIclone_ns_list()\fI\fR. .PP \&\fI\fIprint_response()\fI\fR provides a convenient way to display answers returned in \fIresponse\fR by the name server. .PP The \fIname_server\fR structure is defined in \fBresolver.h\fR as follows: .PP .Vb 10 \& #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; \& }; .Ve .IP "\fIns_name_n\fR" 4 .IX Item "ns_name_n" The name of the zone for which this name server is authoritative. .IP "\fIns_tsig\fR" 4 .IX Item "ns_tsig" The \fItsig\fR key that should be used to protect messages sent to this name server. This field is currently unused and must be set to \s-1NULL.\s0 .IP "\fIns_security_options\fR" 4 .IX Item "ns_security_options" The security options for the zone. This field is currently unused and must be set to \fB\s-1ZONE_USE_NOTHING\s0\fR. .IP "\fIns_status\fR" 4 .IX Item "ns_status" The status of the zone. This field indicates how the zone information was obtained. The invoker must set this value to \fB\s-1SR_ZI_STATUS_UNSET\s0\fR. Zone information obtained through referrals have a value of \&\fB\s-1SR_ZI_STATUS_LEARNED\s0\fR for this field. .IP "\fIns_options\fR" 4 .IX Item "ns_options" Specifies additional resolver flags. Currently defined flags are \&\fB\s-1SR_QUERY_RECURSE\s0\fR, which sets the \*(L"Recursion Desired\*(R" flag; \fB\s-1SR_QUERY_SET_DO\s0\fR, which sets the \*(L"\s-1DNSSEC OK\*(R"\s0 bit in the \s-1EDNS0\s0 header; \&\fB\s-1SR_QUERY_SET_CD\s0\fR, which sets the \*(L"\s-1DNSSEC CD\*(R"\s0 bit in the \s-1EDNS0\s0 header; and \fB\s-1SR_QUERY_DEBUG\s0\fR, which enables debugging. \fB\s-1SR_QUERY_VALIDATING_STUB_FLAGS\s0\fR sets both \fB\s-1SR_QUERY_SET_DO\s0\fR and \fB\s-1SR_QUERY_SET_CD\s0\fR. .IP "\fIns_retry\fR" 4 .IX Item "ns_retry" Specifies the maximum number of attempts that must be made to obtain a name from an unresponsive name server before giving up. .IP "\fIns_retrans\fR" 4 .IX Item "ns_retrans" Specifies the retransmission interval in seconds for queries sent to unresponsive name servers. .IP "\fIns_next\fR" 4 .IX Item "ns_next" The address of the next name server in the list. .IP "\fIns_number_of_addresses\fR" 4 .IX Item "ns_number_of_addresses" The number of elements in the array \fIns_addresses\fR. This field is currently unused. .IP "\fIns_addresses\fR" 4 .IX Item "ns_addresses" The \s-1IP\s0 address of the name server. .SH "OTHER SYMBOLS EXPORTED" .IX Header "OTHER SYMBOLS EXPORTED" The \fIlibsres\fR library also exports the following \s-1BIND\s0 functions, documentation for which can be found in the \s-1BIND\s0 sources and documentation manuals: .PP .Vb 9 \& res_nametoclass \& res_nametotype \& ns_name_ntop \& ns_name_pton \& ns_name_unpack \& ns_parse_ttl \& p_class \& p_section \& p_type .Ve .PP The \fI\fIp_type()\fI\fR function exported from \fIlibsres\fR has been augmented such that it recognizes the various \s-1DNSSEC\s0 type codes such \s-1DNSKEY, RRSIG, NSEC, NSEC3\s0 and \s-1DLV.\s0 .SH "RETURN VALUES" .IX Header "RETURN VALUES" .IP "\fB\s-1SR_UNSET\s0\fR" 4 .IX Item "SR_UNSET" No error. .IP "\fB\s-1SR_CALL_ERROR\s0\fR" 4 .IX Item "SR_CALL_ERROR" An invalid parameter was passed to \fI\fIget()\fI\fR, \fI\fIquery_send()\fI\fR, or \&\fI\fIresponse_recv()\fI\fR. .IP "\fB\s-1SR_INTERNAL_ERROR\s0\fR" 4 .IX Item "SR_INTERNAL_ERROR" The resolver encountered some internal error. .IP "\fB\s-1SR_TSIG_ERROR\s0\fR" 4 .IX Item "SR_TSIG_ERROR" The resolver encountered some TSIG-related error. This is currently not implemented. .IP "\fB\s-1SR_NO_ANSWER\s0\fR" 4 .IX Item "SR_NO_ANSWER" No answers were received from any name server. .IP "\fB\s-1SR_NO_ANSWER_YET\s0\fR" 4 .IX Item "SR_NO_ANSWER_YET" No answer currently available; the query is still active. .IP "\fB\s-1SR_HEADER_ERROR\s0\fR" 4 .IX Item "SR_HEADER_ERROR" The length and count of records in the header were incorrect. .IP "\fB\s-1SR_NXDOMAIN\s0\fR" 4 .IX Item "SR_NXDOMAIN" The queried name did not exist. .IP "\fB\s-1SR_FORMERR\s0\fR" 4 .IX Item "SR_FORMERR" The name server was not able to parse the query message. .IP "\fB\s-1SR_SERVFAIL\s0\fR" 4 .IX Item "SR_SERVFAIL" The name server was not reachable. .IP "\fB\s-1SR_NOTIMPL\s0\fR" 4 .IX Item "SR_NOTIMPL" A particular functionality is not yet implemented. .IP "\fB\s-1SR_REFUSED\s0\fR" 4 .IX Item "SR_REFUSED" The name server refused to answer this query. .IP "\fB\s-1SR_DNS_GENERIC_FAILURE\s0\fR" 4 .IX Item "SR_DNS_GENERIC_FAILURE" Other failure returned by the name server and reflected in the returned message \fB\s-1RCODE\s0\fR. .IP "\fB\s-1SR_EDNS_VERSION_ERROR\s0\fR" 4 .IX Item "SR_EDNS_VERSION_ERROR" The \s-1EDNS\s0 version was not recognized .IP "\fB\s-1SR_NAME_EXPANSION_FAILURE\s0\fR" 4 .IX Item "SR_NAME_EXPANSION_FAILURE" A failure was encountered while trying to expand a compressed domain name. .SH "CURRENT STATUS" .IX Header "CURRENT STATUS" There is currently no support for IPv6. .PP There is limited support for specifying resolver policy; members of the \&\fIstruct name_server\fR are still subject to change. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2004\-2013 \s-1SPARTA,\s0 Inc. All rights reserved. See the \s-1COPYING\s0 file included with the dnssec-tools package for details. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fI\fIlibval\fI\|(3)\fR .PP http://www.dnssec\-tools.org