lwres_getrrsetbyname.docbook revision 83a28ca274521e15086fc39febde507bcc4e145e
25cc5fbba63f84b47e389af749f55abbbde71c8cChristian Maeder - Copyright (C) 2000, 2001, 2004, 2005, 2007, 2014-2016 Internet Systems Consortium, Inc. ("ISC")
25cc5fbba63f84b47e389af749f55abbbde71c8cChristian Maeder - This Source Code Form is subject to the terms of the Mozilla Public
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder - License, v. 2.0. If a copy of the MPL was not distributed with this
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder - file, You can obtain one at http://mozilla.org/MPL/2.0/.
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder<!-- Converted by db4-upgrade version 1.0 -->
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <refentryinfo>
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
1aee4aaddde105264c1faf394d88e302c05094ffChristian Maeder </refentryinfo>
a53841f6d6e86ac751c12a33dc8aadf53f59d977Klaus Luettich <refentrytitle>lwres_getrrsetbyname</refentrytitle>
ac0bbbcb2774629bb87986e69cf53d3402c5f575Christian Maeder <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
8410667510a76409aca9bb24ff0eda0420088274Christian Maeder <refpurpose>retrieve DNS records</refpurpose>
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder </refnamediv>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <refsynopsisdiv>
8410667510a76409aca9bb24ff0eda0420088274Christian Maeder <funcsynopsis>
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettich<funcsynopsisinfo>#include <lwres/netdb.h></funcsynopsisinfo>
b1f59a4ea7c96f4c03a4d7cfcb9c5e66871cfbbbChristian Maeder<funcprototype>
4d56f2fa72e4aec20eb827c11ed49c8cbb7014bdChristian Maeder<function>lwres_getrrsetbyname</function></funcdef>
4cb215739e9ab13447fa21162482ebe485b47455Christian Maeder <paramdef>const char *<parameter>hostname</parameter></paramdef>
8ef75f1cc0437656bf622cec5ac9e8ea221da8f2Christian Maeder <paramdef>unsigned int <parameter>rdclass</parameter></paramdef>
404166b9366552e9ec5abb87a37c76ec8a815fb7Klaus Luettich <paramdef>unsigned int <parameter>rdtype</parameter></paramdef>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <paramdef>unsigned int <parameter>flags</parameter></paramdef>
356fa49fe3e6a8398f92d13e9f920d0f093697ecChristian Maeder <paramdef>struct rrsetinfo **<parameter>res</parameter></paramdef>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder </funcprototype>
55adfe57a4de1f36adc3e3bfc16f342e44a7d444Christian Maeder<funcprototype>
8d97ef4f234681b11bb5924bd4d03adef858d2d2Christian Maeder<function>lwres_freerrset</function></funcdef>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <paramdef>struct rrsetinfo *<parameter>rrset</parameter></paramdef>
e593b89bfd4952698dc37feced21cefe869d87a2Christian Maeder </funcprototype>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder</funcsynopsis>
1aee4aaddde105264c1faf394d88e302c05094ffChristian Maeder The following structures are used:
7cc09dd93962a2155c34d209d1d4cd7d7b838264Christian Maederstruct rdatainfo {
1aee4aaddde105264c1faf394d88e302c05094ffChristian Maeder unsigned int rdi_length; /* length of data */
1aee4aaddde105264c1faf394d88e302c05094ffChristian Maeder unsigned char *rdi_data; /* record data */
dcbd32289a7bdf1e6edd06c6ab0698c6a9dbf37aChristian Maeder</programlisting>
dcbd32289a7bdf1e6edd06c6ab0698c6a9dbf37aChristian Maederstruct rrsetinfo {
c2fcc35abb03cf0b4ca4b050efeb10827f38c322Christian Maeder unsigned int rri_flags; /* RRSET_VALIDATED... */
1aee4aaddde105264c1faf394d88e302c05094ffChristian Maeder unsigned int rri_rdclass; /* class number */
356fa49fe3e6a8398f92d13e9f920d0f093697ecChristian Maeder unsigned int rri_rdtype; /* RR type number */
356fa49fe3e6a8398f92d13e9f920d0f093697ecChristian Maeder unsigned int rri_ttl; /* time to live */
356fa49fe3e6a8398f92d13e9f920d0f093697ecChristian Maeder unsigned int rri_nrdatas; /* size of rdatas array */
356fa49fe3e6a8398f92d13e9f920d0f093697ecChristian Maeder unsigned int rri_nsigs; /* size of sigs array */
356fa49fe3e6a8398f92d13e9f920d0f093697ecChristian Maeder char *rri_name; /* canonical name */
0206ab93ef846e4e0885996d052b9b73b9dc66b0Christian Maeder struct rdatainfo *rri_rdatas; /* individual records */
f13d1e86e58da53680e78043e8df182eed867efbChristian Maeder struct rdatainfo *rri_sigs; /* individual signatures */
757e6c79ec40491d45dc72c82b5eb59a386634b0Jian Chun Wang</programlisting>
757e6c79ec40491d45dc72c82b5eb59a386634b0Jian Chun Wang </refsynopsisdiv>
c6fcd42c6d6d9dae8c7835c24fcb7ce8531a9050Christian Maeder <refsection><info><title>DESCRIPTION</title></info>
c55a0f77be7e88d3620b419ec8961f4379a586e3Klaus Luettich <para><function>lwres_getrrsetbyname()</function>
36f63902db2b3463faa9f59912ad106e2d5aaa24Klaus Luettich gets a set of resource records associated with a
36f63902db2b3463faa9f59912ad106e2d5aaa24Klaus Luettich <parameter>hostname</parameter>, <parameter>class</parameter>,
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder <parameter>hostname</parameter> is a pointer a to
8cacad2a09782249243b80985f28e9387019fe40Christian Maeder null-terminated string. The <parameter>flags</parameter> field
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder is currently unused and must be zero.
8a28707e9155465c6f2236a06eac6580a65c7025Christian Maeder After a successful call to
df35538fec1d9135602308d577255c0d466b6365Christian Maeder <function>lwres_getrrsetbyname()</function>,
df35538fec1d9135602308d577255c0d466b6365Christian Maeder <parameter>*res</parameter> is a pointer to an
431d34c7007a787331c4e5ec997badb0f8190fc7Christian Maeder <type>rrsetinfo</type> structure, containing a list of one or
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder more <type>rdatainfo</type> structures containing resource
d3ae0072823e2ef0d41d4431fcc768e66489c20eChristian Maeder records and potentially another list of <type>rdatainfo</type>
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder structures containing SIG resource records associated with those
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder records. The members <constant>rri_rdclass</constant> and
5191fa24c532d1f67e7a642e9aece65efb8a0975Christian Maeder <constant>rri_rdtype</constant> are copied from the parameters.
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder <constant>rri_ttl</constant> and <constant>rri_name</constant>
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder are properties of the obtained rrset. The resource records
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder contained in <constant>rri_rdatas</constant> and
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder <constant>rri_sigs</constant> are in uncompressed DNS wire
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder format. Properties of the rdataset are represented in the
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder <constant>rri_flags</constant> bitfield. If the RRSET_VALIDATED
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder bit is set, the data has been DNSSEC validated and the
a7c27282e71cf4505026645f96d4f5cb8a284e32Christian Maeder signatures verified.
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder All of the information returned by
776a1a086df734581431e6edb4343ed4c8d34d55Christian Maeder <function>lwres_getrrsetbyname()</function> is dynamically
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder allocated: the <constant>rrsetinfo</constant> and
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder <constant>rdatainfo</constant> structures, and the canonical
6dc9bc98d0854fe2e3dd3bfc4275096a0c28ee1cChristian Maeder host name strings pointed to by the
61fa0ac06ede811c7aad54ec4c4202346727368eChristian Maeder Memory allocated for the dynamically allocated structures
c0c2380bced8159ff0297ece14eba948bd236471Christian Maeder created by a successful call to
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <function>lwres_getrrsetbyname()</function> is released by
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <parameter>rrset</parameter> is a pointer to a <type>struct
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder rrset</type> created by a call to
9e748851c150e1022fb952bab3315e869aaf0214Christian Maeder <function>lwres_getrrsetbyname()</function>.
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder </refsection>
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder <refsection><info><title>RETURN VALUES</title></info>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder <para><function>lwres_getrrsetbyname()</function>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder returns zero on success, and one of the following error codes if
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder an error occurred:
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder <variablelist>
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder <varlistentry>
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder <term><constant>ERRSET_NONAME</constant></term>
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder the name does not exist
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder </varlistentry>
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder <varlistentry>
2d130d212db7208777ca896a7ecad619a8944971Christian Maeder <term><constant>ERRSET_NODATA</constant></term>
6ff7a91875597d6e4dfaa68c79187d01473e8341Christian Maeder the name exists, but does not have data of the desired type
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder </varlistentry>
a9b59eb2ce961014974276cdae0e9df4419bd212Christian Maeder <varlistentry>
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder <term><constant>ERRSET_NOMEMORY</constant></term>
6a79849bed67264c396dddb3e9c184bdfc1a1bc9Christian Maeder memory could not be allocated
a3c6d8e0670bf2aa71bc8e2a3b1f45d56dd65e4cChristian Maeder </varlistentry>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <varlistentry>
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder <term><constant>ERRSET_INVAL</constant></term>
363939beade943a02b31004cea09dec34fa8a6d9Christian Maeder a parameter is invalid
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder </varlistentry>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder <varlistentry>
4017ebc0f692820736d796af3110c3b3018c108aChristian Maeder <term><constant>ERRSET_FAIL</constant></term>
0be0db405c49906bd7057255069bf6df53395ac9Klaus Luettich other failure
63f0e65a37b95621334db9ee4ba0cd9d826f5c0fChristian Maeder </varlistentry>
f2f9df2e17e70674f0bf426ed1763c973ee4cde0Christian Maeder <varlistentry>
d946c1bfdd7d58aa7c023efe864d5999eb44a61bChristian Maeder </varlistentry>
d23b0cc79c0d204e6ec758dff8d0ba71c9f693f7Christian Maeder </variablelist>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder </refsection>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder <refsection><info><title>SEE ALSO</title></info>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
ca074a78b8dcccbb8c419586787882f98d0c6163Christian Maeder </citerefentry>.
f1541d4a151dbd08002dbd14e7eb1d5dde253689Christian Maeder </refsection>