From: Miek Gieben Date: Tue, 26 Apr 2005 11:31:20 +0000 (+0000) Subject: documentation updates; tutorial.docbook 50% complete X-Git-Tag: release-0.50~85 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b2bc1e5986bda309bfe230b8839da772717fa209;p=thirdparty%2Fldns.git documentation updates; tutorial.docbook 50% complete --- diff --git a/doc/API-footer.xml b/doc/API-footer.xml deleted file mode 100644 index fce0c803..00000000 --- a/doc/API-footer.xml +++ /dev/null @@ -1,63 +0,0 @@ -
- -A small example, which queries a nameserver on localhost -to diplay the MX records for miek.nl. - - - -
- -/** - * 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; -} - -
- -
- - - - - diff --git a/doc/ldns-man.tmpl b/doc/ldns-man.tmpl deleted file mode 100644 index d1a7009e..00000000 --- a/doc/ldns-man.tmpl +++ /dev/null @@ -1,44 +0,0 @@ -.TH "ldns \- a general DNS(SEC) library" "25 Apr 2005" -.SH NAME -Insert the names of the functions here -.SH SYNOPSIS -#include - -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. - - - diff --git a/doc/make-xml-from-dox.pl b/doc/make-xml-from-dox.pl deleted file mode 100755 index 9fa74d0f..00000000 --- a/doc/make-xml-from-dox.pl +++ /dev/null @@ -1,57 +0,0 @@ -#!/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 = " - -"; -my $func_foot = " - -"; -my $list_head = " - -"; -my $list_foot = " - -"; - -my $sec_head="
-"; -my $sec_foot="
+ + + ldns tutorial + + + 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. + + + - Miek - Gieben - -
miekg@nlnetlabs.nl
- + Miek Gieben + + miek@nlnetlabs.nl + + + - - 2005 - Copyright string here - + + +Introduction ldns + + +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). + - - This tutorial will help you make your first ldns application. - - - + +Take for instance the following RR: + +open.nlnetlabs.nl 8600 IN A 213.154.224.1 + +This RR consists out of five elements: + + + open.nlnetlabs.nl + + the ownername of the RR + + - - Preface + + 8600 + + the TTL of the RR + + - Your book may have a preface, in which case it should be placed - here. - - - - Introduction + + IN + + the class of the RR + + - This is the first chapter in my book. + + A + + the type of the RR + + - - My first section + + 213.154.224.1 + + 1 rdata field, in this case with the address + + + + - This is the first section in my book. - - - - Getting Started - - + +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. Other possible values are CH, and HS. But only the IN class is +used on the Internet. + + + + +3600 + +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. + + + + -What are we going to make + 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: + + + make a resolver structure, + + + use the resolver to generate an mx query, + + + print the result. + + + + +First we begin with some boiler plating: + + 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 + +Line 9 is the important one here, this includes all the stuff we need +from ldns. -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 } +Here we parse the arguments. We create a new rdf structure which contain the domain +name that we got from the commandline. + + 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 } + +At line 41 we create a new resolver structure. When it's argument is NULL it uses +/etc/resolv.conf to setup the resolver structure. + + + 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); + +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. + + + 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); + +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. + + + 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 } + +Here we sort the list and print it to stdout. + + + 71 } + 72 return 0; + 73 } + + + + +This example shows that with a fairly short C program you can already do +complex tasks. + - - +