<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type"
content="text/html;charset=iso-8859-1">
<title>ldns documentation</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
</head><body>
<div class="logo">
<img src="LogoInGradientBar2-y100.png"/>
</div>
<!-- Generated by Doxygen 1.7.4 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="dirs.html"><span>Directories</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<div class="title">Tutorial 1: Querying for MX records </div> </div>
</div>
<div class="contents">
<div class="textblock"><p>The full source code can be found in <a class="el" href="ldns-mx_8c.html">examples/ldns-mx.c</a></p>
<p>ldns-mx is a simple tool that queries your default caching forwarder for the MX (Mail exchange) record of the given domain.</p>
<pre>
% ldns-mx nlnetlabs.nl
nlnetlabs.nl. 86400 IN MX 100 omval.tednet.nl.
nlnetlabs.nl. 86400 IN MX 50 open.nlnetlabs.nl.
</pre><p>First of all, we need to include the correct header files, so that all functions are available to us:</p>
<p><div class="fragment"><pre class="fragment"><span class="preprocessor">#include "config.h"</span>
<span class="preprocessor">#include <<a class="code" href="ldns_8h.html" title="Including this file will include all ldns files, and define some lookup tables.">ldns/ldns.h</a>></span>
</pre></div></p>
<p>In this case we have used a configure script to generate a config.h file that does all our inclusions for us, so that it can be compiled on multiple platforms. If your platform supports the include files <code>stdint.h</code> and <code>stdlib.h</code>, you can include these instead of using a configure script.</p>
<p>The first included files are prerequisites that ldns needs to function. The last one, of course, includes the functions of ldns itself.</p>
<p>In our main function, we declare some variables that we are going to use:</p>
<p><div class="fragment"><pre class="fragment"> <a class="code" href="structldns__struct__resolver.html" title="DNS stub resolver structure.">ldns_resolver</a> *res;
<a class="code" href="structldns__struct__rdf.html" title="Resource record data field.">ldns_rdf</a> *domain;
<a class="code" href="structldns__struct__pkt.html" title="DNS packet.">ldns_pkt</a> *p;
<a class="code" href="structldns__struct__rr__list.html" title="List or Set of Resource Records.">ldns_rr_list</a> *mx;
<a class="code" href="error_8h.html#aaa6d98f86f535cf87b83b89e91f488f9">ldns_status</a> s;
</pre></div></p>
<ul>
<li>The <code>ldns_resolver</code> structure keeps a list of nameservers, and can perform queries for us</li>
<li>An <code>ldns_rdf</code> is a basic data type of dns, the RDATA. See <a class="el" href="design.html">Design</a> for a description about the building blocks of DNS. In this case, <code>domain</code> will be used to store the name the user specifies when calling the program</li>
<li>An <code>ldns_pkt</code> is a DNS packet, for instance a complete query, or an answer</li>
<li>The <code>ldns_rr_list</code> structure contains a list of DNS Resource Records (RRs). In this case, we will store the MX records we find in the list.</li>
<li><code>ldns_status</code> is the basic type for status messages in ldns. Most functions will return a value of this type.</li>
</ul>
<p>First, we parse the command line argument (checks omitted on this page, see full source code), and store it in our <code>domain</code> variable: <div class="fragment"><pre class="fragment"> domain = <a class="code" href="dname_8c.html#af4963d4ae086b1d77a58c6f757a00462" title="creates a new dname rdf from a string.">ldns_dname_new_frm_str</a>(argv[1]);
</pre></div></p>
<p>This function takes a string containing a domain name (like "nlnetlabs.nl") and returns an <code>ldns_rdf</code> representing that name. If somehow the given string can not be parsed it returns NULL.</p>
<p>Then, we create the resolver structure: <div class="fragment"><pre class="fragment"> s = <a class="code" href="resolver_8c.html#a783fdb0e6523eb6c1f4a1563b32ac135" title="Configure a resolver by means of a resolv.conf file The file may be NULL in which case there will be ...">ldns_resolver_new_frm_file</a>(&res, NULL);
</pre></div></p>
<p>Most of the functions work like this, the first argument is a pointer to the structure where ldns should store its results (which is also a pointer). The function returns a status code indicating success (<a class="el" href="error_8h.html#a11f34802bb1624af46054952e3b853afac58492ee3fc8d23f33c79824ed08c465">LDNS_STATUS_OK</a>) or an error number. Remember that these types of functions allocate memory that you should free later (using the ldns_free_<type> functions).</p>
<p>The second argument is the filename that contains information about the resolver structure that is to be created. If this argument is NULL, /etc/resolv.conf is used. The syntax of the file is like that of /etc/resolv.conf.</p>
<p>We tell the resolver to query for our domain, type MX, of class IN: <div class="fragment"><pre class="fragment"> p = <a class="code" href="resolver_8c.html#a11ed37ad2349dbdc0ce6fbb618091d10" title="Send a query to a nameserver.">ldns_resolver_query</a>(res,
domain,
<a class="code" href="rr_8h.html#a640100112b0009efe3d61bbf799b33daaf13c7ee3899f0484210333da33db2a6c" title="mail exchange">LDNS_RR_TYPE_MX</a>,
<a class="code" href="rr_8h.html#adc72070b39f210fae670577de8136600a2ad89c0befc939420e3b1157c07a8b46" title="the Internet">LDNS_RR_CLASS_IN</a>,
<a class="code" href="packet_8h.html#adbf4098a01ab543ebbcbd329103cc8d9">LDNS_RD</a>);
</pre></div></p>
<p>The last argument contains flags to influence the type of query the resolver structure sends. In this case, we want the nameserver to use recursion, so that we'll get the final answer. Therefore, we specify the <a class="el" href="packet_8h.html#adbf4098a01ab543ebbcbd329103cc8d9">LDNS_RD</a> (Recursion Desired) flag.</p>
<p>This should return a packet if everything goes well.</p>
<p>We get all RRs of type MX from the answer packet and store them in our list: <div class="fragment"><pre class="fragment"> mx = <a class="code" href="packet_8c.html#aff953969fdd5f6bbbae10569f3455505" title="return all the rr with a specific type from a packet.">ldns_pkt_rr_list_by_type</a>(p,
<a class="code" href="rr_8h.html#a640100112b0009efe3d61bbf799b33daaf13c7ee3899f0484210333da33db2a6c" title="mail exchange">LDNS_RR_TYPE_MX</a>,
<a class="code" href="packet_8h.html#adad42096a5200b78a988227bd8c59b71a80effb31e9d19e57c89b79424a0b08ec">LDNS_SECTION_ANSWER</a>);
</pre></div></p>
<p>If this list is not empty, we sort and print it: <div class="fragment"><pre class="fragment"> <a class="code" href="rr_8c.html#a59fd6b0801f57bd952d1c69386677095" title="sorts an rr_list (canonical wire format).">ldns_rr_list_sort</a>(mx);
<a class="code" href="host2str_8c.html#ac2840486d0b166f4af59360deb18600b" title="print a rr_list to output">ldns_rr_list_print</a>(stdout, mx);
</pre></div></p>
<p>And finally, just to be proper, we free our allocated data: <div class="fragment"><pre class="fragment"> <a class="code" href="rr_8c.html#a25181bd133a53f132abce4eefd8e33af" title="frees an rr_list structure and all rrs contained therein.">ldns_rr_list_deep_free</a>(mx);
}
}
<a class="code" href="packet_8c.html#a05bd6d99b1f608238c67b84449724c16" title="frees the packet structure and all data that it contains.">ldns_pkt_free</a>(p);
<a class="code" href="resolver_8c.html#afddfa77c8dccef423178c340b9817401" title="Frees the allocated space for this resolver and all it's data.">ldns_resolver_deep_free</a>(res);
</pre></div></p>
<p>For structures that can contain other ldns structures, there are two types of free() function available</p>
<ul>
<li><code>ldns_free_<type></code> frees only the allocated data for the structure itself.</li>
<li><code>ldns_deep_free_<type></code> frees the structure, and ALL structures that are nested in it. For example, of you <code>deep_free</code> an ldns_rr_list, all <code>ldns_rr</code> structures that were present in the list are also freed. </li>
</ul>
</div></div>
<hr class="footer"/><address class="footer"><small>Generated on Wed Jan 11 2012 for ldns by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.4 </small></address>
</body>
</html>
