ldns base 1.6.9 from tarball

libs/ldns/doc/tutorial2_zone.dox

@@ -0,0 +1,111 @@
+/**
+   \page tutorial2_zone Tutorial 2: Reading a zone file
+   \dontinclude ldns-read-zone.c 
+   
+   The full source code can be found in \link examples/ldns-read-zone.c \endlink
+   
+   ldns-read-zone reads a zone file, and prints it to stdout, with 1 resource record per line.
+
+   <pre>
+% cat example.zone
+$ORIGIN example.
+$TTL 600
+
+example.        IN SOA  example. op.example. (
+                                2004022501 ; serial
+                                28800      ; refresh (8 hours)
+                                7200       ; retry (2 hours)
+                                604800     ; expire (1 week)
+                                18000      ; minimum (5 hours)
+                                )
+
+@       IN      MX      10 mail.example.
+@       IN      NS      ns1
+@       IN      NS      ns2
+@       IN      A       123.123.123.123
+
+% ldns-read-zone example.zone
+example.        600     IN      SOA     example. op.example. 2004022501 28800 7200 604800 18000
+example.        600     IN      MX      10 mail.example.
+example.        600     IN      NS      ns1.example.
+example.        600     IN      NS      ns2.example.
+example.        600     IN      A       123.123.123.123
+   </pre>
+
+
+
+Again, let's start with including some necessary header files:
+
+\skipline include
+\until errno
+
+In this example, we are going to open a file, if that fails, we'll need errno.h to display an error message.
+
+Okay, let's declare the variables we are going to need today:
+
+\skipline filename
+\until ldns_status
+
+The only two ldns-specific types here are \c ldns_zone and \c ldns_status.
+  - \c ldns_zone is the structure that can contain a complete zone
+  - \c ldns_status again is used to check return values of ldns functions
+
+
+If we get no filename, we'll read standard input, otherwise, we'll try to
+open the given filename:
+\skipline if (argc == 0)
+\until exit(EXIT_FAILURE)
+\until }
+\until }
+
+
+With the \c FILE pointer in our hands, we visit ldns to pour it into a zone
+structure:
+\skipline ldns_zone_new_frm_fp_l
+
+There is also a \c ldns_zone_new_frm_fp, but this one also remembers the
+line number it was on, so we can use that if we encounter a parse error.
+
+Just like in \ref tutorial1_mx, the first argument is a pointer
+to the place ldns should store its creation in, and again, the return value
+is the status code.
+
+The second argument is the file pointer where our zone data should reside.
+
+The third argument, if not NULL, is a \c dname that contains the zones
+origin. It will place this dname after every name in the file that is not a
+fully qualified domain name.
+
+The fourth argument, if not 0, is the default TTL to use.
+
+Both these values can be specified in the zone file by setting \c $ORIGIN and \c $TTL.
+
+The fifth argument specifies the default class, which defaults to IN (\ref LDNS_RR_CLASS_IN).
+
+And finally, every time \c ldns_zone_new_frm_fp_l reads a line from the
+input file pointer, it will increment the value pointed to by the last
+argument with 1.
+
+
+Okay, with that, we should have a nice zone structure. Of course we need to
+check whether it has succeeded.
+
+\skipline LDNS_STATUS_OK
+\until deep_free
+
+If everything went well, we sort the zone if necessary, print it, and free it.
+
+Since \c ldns_zone contains other ldns structures, we use \c ldns_deep_free
+so that every \c ldns_rr_list, \c ldns_rr et cetera are freed too.
+
+\until line_nr);
+\until }
+
+If something went wrong, we use \c ldns_get_errorstr_by_id() to get a nice
+error string instead of just a status integer.
+
+And of course, we should play nice and close the file:
+\skipline fclose
+\until exit
+
+*/