+++ /dev/null
-<section title="Examples">
-<t>
-A small example, which queries a nameserver on localhost
-to diplay the MX records for miek.nl.
-</t>
-
-<t>
-<figure>
-<artwork>
-/**
- * An example ldns program
- * In semi-C code
- *
- * Setup a resolver
- * Query a nameserver
- * Print the result
- */
-
-#include <ldns.h>
-
-int
-main(void)
-{
- ldns_resolver *res;
- ldns_rdf *default_dom;
- ldns_rdf *nameserver;
- ldns_rdf *qname;
- ldns_pkt *pkt;
-
- /* init */
- res = ldns_resolver_new();
- if (!res)
- return 1;
-
- /* create a default domain and add it */
- default_dom = ldns_rdf_new_frm_str("miek.nl.", LDNS_RDF_TYPE_DNAME);
- nameserver = ldns_rdf_new_frm_str("127.0.0.1", LDNS_RDF_TYPE_A);
-
- if (ldns_resolver_domain(res, default_dom) != LDNS_STATUS_OK)
- return 1;
- if (ldns_resolver_nameserver_push(res, nameserver) != LDNS_STATUS_OK)
- return 1;
-
- /* setup the question */
- qname = ldns_rdf_new_frm_str("www", LDNS_RDF_TYPE_DNAME);
-
- /* fire it off. "miek.nl." will be added */
- pkt = ldns_resolver_query(res, qname, LDNS_RR_TYPE_MX, NULL);
-
- /* print the resulting pkt to stdout */
- ldns_pkt_print(stdout, pkt);
-
- return 0;
-}
-</artwork>
-</figure>
-</t>
-</section> <!-- title="Short Example" -->
-
-</middle>
-<back>
-</back>
-</rfc>
+++ /dev/null
-.TH "ldns \- a general DNS(SEC) library" "25 Apr 2005"
-.SH NAME
-Insert the names of the functions here
-.SH SYNOPSIS
-#include <your include here>
-
-a listing of all the functions
-
-.SH DESCRIPTION
-Each paragraph describes a specific function
-.PP
-A new paragraph
-
-
-
-.SH RETURN VALUES
-
-
-.SH SEE ALSO
-
-
-
-
-
-.SH AUTHOR
-The ldns team at NLnet Labs. Which consists out of: Jelte Jansen, Erik Rozendaal and Miek Gieben.
-
-.SH REPORTING BUGS
-Please report bugs to ldns-team@nlnetlabs.nl
-
-.SH BUGS
-None sofar. This software just works great.
-
-.SH COPYRIGHT
-Copyright (c) 2004, 2005 NLnet Labs.
-Licensed under the GPL 2. There is NO warranty; not even for MERCHANTABILITY or
-FITNESS FOR A PARTICULAR PURPOSE.
-
-.SH SEE ALSO
-\fBperldoc Net::DNS\FR, \fBRFC1043\fR,
-\fBRFC1035\fR, \fBRFC4033\fR, \fBRFC4034\fR, \fBRFC4035\fR.
-
-
-
+++ /dev/null
-#!/usr/bin/perl
-
-# this perl program takes the html output from
-# doxygen and creates and RFC like document
-# with the lDNS API. This document also has
-# some highlevel language in how to use
-# lDNS.
-
-use strict;
-
-# get it from cmd line
-my $title = "BOGUS TITLE";
-
-# what to put in front and after
-my $func_head = "<t>
-<artwork>
-";
-my $func_foot = "</artwork>
-</t>
-";
-my $list_head = "<t>
-<list style=\"symbols\">
-";
-my $list_foot = "</list>
-</t>
-";
-
-my $sec_head="<section title=\"$title\">
-";
-my $sec_foot="</section> <!-- \"$title\">
-";
-
-print $sec_head;
-print $list_head;
-my $indoc = 0;
-my @current_func = ();
-while (<>) {
- if (/^Function Documentation/) {
- $indoc = 1;
- next;
- }
- if ($indoc == 0) {
- next;
- }
-
- if (/Definition at line/) {
- # we are at the end of the current function
- print $func_head;
- print @current_func;
- print $func_foot;
- @current_func = ();
- next;
- }
- push @current_func, $_;
-}
-print $list_foot;
-print $sec_foot;
+++ /dev/null
-ldns tutorial
-
-
-In this tutorial we will explain how to make a simple application with
-ldns.
-
-* Introduction
-
-The following paragraphs will introduce some concepts used in ldns. It is
-assumed that the reader is familiar with DNS (knowledge of DNSSEC is not
-a problem).
-
-Take for instance the following RR:
-open.nlnetlabs.nl 8600 IN A 213.154.224.1
-
-This RR consists out of 4 elements:
-1. 'open.nlnetlabs.nl' - the ownername of the RR
-2. '8600' - the TTL of the RR
-3. 'IN' - the class of the RR
-4. 'A' - the type of the RR
-5. '213.154.224.1' - 1 rdata field
-
-'213.154.224.1'
-To begin with the last element, ldns calls that a RDATA FIELD, or rdf. This
-is the smallest type in ldns. An RR's rdata consists of 1 or several rdf's.
-All these rdf's have a type, in the case of an A record, this type is
-LDNS_RDF_TYPE_A.
-
-The data in a rdf is stored in network byte order.
-
-'A'
-This is the type of the whole RR, this type is called LDNS_RR_TYPE_A in
-ldns.
-
-'IN'
-the class
-
-'8600'
-The TTL of a RR, stored in host order
-
-'open.nlnetlabs.nl'
-The ownername of the RR, this owner name is stored in wire data, this this
-particaliar name is stored as 04open09nlnetlabs02nl00.
-
-RDF TYPES
-The following rdf types exist in ldns:
-LDNS_RDF_TYPE_A - for ip4 addresses
-LDNS_RDF_TYPE_AAAA - for ip6 addresses
-LDNS_RDF_TYPE_TXT - for txt
-LDNS_RDF_TYPE_INT8 - for 8 bit numbers
-LDNS_RDF_TYPE_INT16 - for 16 bit numbers
-LDNS_RDF_TYPE_INT32 - for 32 bit numbers
-...
-etc.
-
-
-RR TYPES
-ldns knows about the following RR types:
-LDNS_RR_TYPE_A
-LDNS_RR_TYPE_AAAA
-LDNS_RR_TYPE_TXT
-LDNS_RR_TYPE_DNSKEY
-...
-etc.
-
-
-RR CLASSES
-LDNS_RR_CLASS_IN
-LDNS_RR_CLASS_HS
-LDNS_RR_CLASS_CH
-...
-etc.
-
-* Making a small application with ldns
-
-In this tutorial we will make a small application which takes a domain name
-and looks up the MX records for this domain. We will call this program:
-'mx'.
-
-The general flow of the program is as follows:
-1. make a resolver structure
-2. use the resolver to generate an mx query
-3. print the result.
-
-First we begin with some boiler plating:
-<code>
- 1 /*
- 2 * mx is a small programs that prints out the mx records
- 3 * for a particulary domain
- 4 */
- 5
- 6 #include <stdio.h>
- 7 #include <config.h>
- 8 #include <ldns/dns.h>
- 9
- 10 int
- 11 usage(FILE *fp, char *prog) {
- 12 fprintf(fp, "%s zone\n", prog);
- 13 fprintf(fp, " print out the mx for the domain\n");
- 14 return 0;
- 15 }
- 16
-</code>
-
-Line 9 is the important one here, this includes all the stuff we need
-from ldns.
-
-<code>
- 17 int
- 18 main(int argc, char *argv[])
- 19 {
- 20 ldns_resolver *res;
- 21 ldns_rdf *domain;
- 22 ldns_pkt *p;
- 23 ldns_rr_list *mx;
- 24 char *domstr;
- 25
- 26 if (argc != 2) {
- 27 usage(stdout, argv[0]);
- 28 exit(1);
- 29 } else {
- 30 /* create a rdf from the command line arg */
- 31 domain = ldns_dname_new_frm_str(argv[1]);
- 32 if (!domain) {
- 33 usage(stdout, argv[0]);
- 34 exit(1);
- 35 }
- 36 /* transform it in a string for the error msg (if needed) */
- 37 domstr = ldns_rdf2str(domain);
- 38 }
- 39
- 40 /* create a new resolver from /etc/resolv.conf */
- 41 res = ldns_resolver_new_frm_file(NULL);
- 42 if (!res) {
- 43 free(domstr);
- 44 exit(1);
- 45 }
- 46
- 47 /* use the resolver to send it a query for the mx
- 48 * records of the domain given on the command line
- 49 */
- 50 p = ldns_resolver_query(res, domain, LDNS_RR_TYPE_MX, LDNS_RR_CLASS_IN, LDNS_RD);
- 51 if (!p) {
- 52 free(domstr);
- 53 exit(1);
- 54 } else {
- 55 /* retrieve the MX records from the answer section of that
- 56 * packet
- 57 */
- 58 mx = ldns_pkt_rr_list_by_type(p, LDNS_RR_TYPE_MX, LDNS_SECTION_ANSWER);
- 59 if (!mx) {
- 60 fprintf(stderr,
- 61 " *** invalid answer name %s after MX query for %s\n ",
- 62 domstr, domstr);
- 63 free(domstr);
- 64 exit(1);
- 65 } else {
- 66 /* sort the list nicely */
- 67 ldns_rr_list_sort(mx);
- 68 /* print the rrlist to stdout */
- 69 ldns_rr_list_print(stdout, mx);
- 70 }
- 71 }
- 72 return 0;
- 73 }
-</code>
-
-</code>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<article>
-<book>
- <bookinfo>
- <title>A tutorial for ldns</title>
-
+<!-- Article information. -->
+<articleinfo>
+ <!-- Article title and abstract. -->
+ <title>ldns tutorial</title>
+ <abstract>
+ <para>
+ In this tutorial we will explain how to make a simple application
+ with ldns. Also some insights in the setup/construction of ldns
+ is given.
+ </para>
+ </abstract>
+ <!-- Author name and bio. -->
<author>
- <firstname>Miek</firstname>
- <surname>Gieben</surname>
- <affiliation>
- <address><email>miekg@nlnetlabs.nl</email></address>
- </affiliation>
+ <firstname>Miek</firstname> <surname>Gieben</surname>
+ <authorblurb>
+ <para>miek@nlnetlabs.nl</para>
+ </authorblurb>
</author>
+</articleinfo>
+<!-- Body of article. -->
- <copyright>
- <year>2005</year>
- <holder>Copyright string here</holder>
- </copyright>
+<sect1>
+<title>
+Introduction ldns
+</title>
+<para>
+The following paragraphs will introduce some concepts used in ldns. It is
+assumed that the reader is familiar with DNS (knowledge of DNSSEC is not
+a problem).
+</para>
- <abstract>
- <para>This tutorial will help you make your first ldns application.
- </para>
- </abstract>
- </bookinfo>
+<para>
+Take for instance the following RR:
+<programlisting>
+open.nlnetlabs.nl 8600 IN A 213.154.224.1
+</programlisting>
+This RR consists out of five elements:
+<variablelist>
+ <varlistentry>
+ <term>open.nlnetlabs.nl</term>
+ <listitem>
+ <para>the ownername of the RR</para>
+ </listitem>
+ </varlistentry>
- <preface>
- <title>Preface</title>
+ <varlistentry>
+ <term>8600</term>
+ <listitem>
+ <para>the TTL of the RR</para>
+ </listitem>
+ </varlistentry>
- <para>Your book may have a preface, in which case it should be placed
- here.</para>
- </preface>
-
- <chapter>
- <title>Introduction</title>
+ <varlistentry>
+ <term>IN</term>
+ <listitem>
+ <para>the class of the RR</para>
+ </listitem>
+ </varlistentry>
- <para>This is the first chapter in my book.</para>
+ <varlistentry>
+ <term>A</term>
+ <listitem>
+ <para>the type of the RR</para>
+ </listitem>
+ </varlistentry>
- <sect1>
- <title>My first section</title>
+ <varlistentry>
+ <term>213.154.224.1</term>
+ <listitem>
+ <para>1 rdata field, in this case with the address</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
- <para>This is the first section in my book.</para>
- </sect1>
- </chapter>
- <chapter>
- <title>Getting Started</title>
- <para>
- </para>
+<sect2>
+<title>213.154.224.1</title>
+<para>
+To begin with the last element, ldns calls that a RDATA FIELD, or rdf. This
+is the smallest type in ldns. An RR's rdata consists of 1 or several rdf's.
+All these rdf's have a type, in the case of an A record, this type is
+LDNS_RDF_TYPE_A.
+The data in a rdf is stored in network byte order.
+</para>
+</sect2>
+
+<sect2>
+<title>A</title>
+<para>
+This is the type of the whole RR, this type is called LDNS_RR_TYPE_A in
+ldns
+
+</para>
+</sect2>
+
+<sect2>
+<title>IN</title>
+<para>
+The class. Other possible values are CH, and HS. But only the IN class is
+used on the Internet.
+</para>
+</sect2>
+
+<sect2>
+<title>3600</title>
+<para>
+The TTL of a RR, stored in host order.
+</para>
+</sect2>
+
+<sect2>
+<title>open.nlnetlabs.nl</title>
+<para>
+The ownername of the RR, this owner name is stored in wire data, this this
+particaliar name is stored as 04open09nlnetlabs02nl00.
+</para>
+</sect2>
+
+</sect1>
<sect1>
-<title>What are we going to make</title>
+ <title>Making a small application with ldns</title>
+ <para>
+In this tutorial we will make a small application which takes a domain name
+and looks up the MX records for this domain. We will call this program:
+'mx'.
+ </para>
+
+ <para>
+ The general flow of the program is as follows:
+ <orderedlist>
+ <listitem>
+ <para>make a resolver structure,</para>
+ </listitem>
+ <listitem>
+ <para>use the resolver to generate an mx query,</para>
+ </listitem>
+ <listitem>
+ <para>print the result.</para>
+ </listitem>
+ </orderedlist>
+ </para>
+
<para>
+First we begin with some boiler plating:
+<programlisting>
+ 1 /*
+ 2 * mx is a small programs that prints out the mx records
+ 3 * for a particulary domain
+ 4 */
+ 5
+ 6 #include <stdio.h>
+ 7
+ 8 #include <ldns/dns.h>
+ 9
+ 10 int
+ 11 usage(FILE *fp, char *prog) {
+ 12 fprintf(fp, "%s zone\n", prog);
+ 13 fprintf(fp, " print out the mx for the domain\n");
+ 14 return 0;
+ 15 }
+ 16
+</programlisting>
+Line 9 is the important one here, this includes all the stuff we need
+from ldns.
<programlisting>
-int
-main(int argc, char **argv)
-{
- return 0;
-}
+ 17 int
+ 18 main(int argc, char *argv[])
+ 19 {
+ 20 ldns_resolver *res;
+ 21 ldns_rdf *domain;
+ 22 ldns_pkt *p;
+ 23 ldns_rr_list *mx;
+ 24
+ 25
+ 26 if (argc != 2) {
+ 27 usage(stdout, argv[0]);
+ 28 exit(1);
+ 29 } else {
+ 30 /* create a rdf from the command line arg */
+ 31 domain = ldns_dname_new_frm_str(argv[1]);
+ 32 if (!domain) {
+ 33 usage(stdout, argv[0]);
+ 34 exit(1);
+ 35 }
+ 36 /* transform it in a string for the error msg (if needed) */
+ 38 }
</programlisting>
+Here we parse the arguments. We create a new rdf structure which contain the domain
+name that we got from the commandline.
+<programlisting>
+ 39
+ 40 /* create a new resolver from /etc/resolv.conf */
+ 41 res = ldns_resolver_new_frm_file(NULL);
+ 42 if (!res) {
+ 43 exit(1);
+ 44 }
+</programlisting>
+At line 41 we create a new resolver structure. When it's argument is NULL it uses
+<filename>/etc/resolv.conf</filename> to setup the resolver structure.
+
+<programlisting>
+ 45
+ 46
+ 47 /* use the resolver to send it a query for the mx
+ 48 * records of the domain given on the command line
+ 49 */
+ 50 p = ldns_resolver_query(res, domain, LDNS_RR_TYPE_MX, LDNS_RR_CLASS_IN, LDNS_RD);
+</programlisting>
+At line 50 we do the actual query. The ldns_resolver_query command returns ldns_pkt* structure,
+with the reply from the nameserver. As we look at the function call, we see that we do a
+query for a RR type 'MX' in the class 'IN' and we set the RD (recursion desired) flag on the
+qeury.
+
+<programlisting>
+ 51 if (!p) {
+ 52
+ 53 exit(1);
+ 54 } else {
+ 55 /* retrieve the MX records from the answer section of that
+ 56 * packet
+ 57 */
+ 58 mx = ldns_pkt_rr_list_by_type(p, LDNS_RR_TYPE_MX, LDNS_SECTION_ANSWER);
+</programlisting>
+On line 58 we look inside the packet to see if we got any MX records back for our query. We look
+only inside the answer section of the packet.
+
+<programlisting>
+ 59 if (!mx) {
+ 60 fprintf(stderr,
+ 61 " *** invalid answer name %s after MX query for %s\n ",
+ 62 argv[1],
+ 63 argv[1]);
+ 64 exit(1);
+ 65 } else {
+ 66 /* sort the list nicely */
+ 67 ldns_rr_list_sort(mx);
+ 68 /* print the rrlist to stdout */
+ 69 ldns_rr_list_print(stdout, mx);
+ 70 }
+</programlisting>
+Here we sort the list and print it to stdout.
+
+<programlisting>
+ 71 }
+ 72 return 0;
+ 73 }
+</programlisting>
+</para>
+
+<para>
+This example shows that with a fairly short C program you can already do
+complex tasks.
</para>
+
</sect1>
- </chapter>
-</book>
+</article>
projects / thirdparty / ldns.git / commitdiff
