Bug #46011 for bind9-public: [PATCH] A begginer's guide to rdatasets

I thought it might be helpful to write a quick overview/summary of some of the stuff I learned while writing dnssec-cds. --- doc/dev/rdatasets-for-beginners | 60 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 doc/dev/rdatasets-for-beginners diff --git a/doc/dev/rdatasets-for-beginners b/doc/dev/rdatasets-for-beginners new file mode 100644 index 0000000..30ea488 --- /dev/null +++ b/doc/dev/rdatasets-for-beginners @@ -0,0 +1,60 @@ +Copyright (C) 1999-2001, 2004, 2016 Internet Systems Consortium, Inc. ("ISC") + +This Source Code Form is subject to the terms of the Mozilla Public +License, v. 2.0. If a copy of the MPL was not distributed with this +file, You can obtain one at http://mozilla.org/MPL/2.0/. + +Written by Tony Finch <dot@dotat.at> <fanf2@cam.ac.uk> +at Cambridge University Information Services + + +A beginner's guide to rdatasets +=============================== + +These notes aim to help you get started with the BIND9 libdns API, in +particular rdatasets and their multi-layer stack of abstractions. +We're going to work down from upper to lower abstraction layers. + + +rdataset +-------- + +An rdataset is BIND9's representation of a DNS RRset, excluding its +owner name. It does not actually hold the data itself: it is a view +that refers to data held elsewhere, for instance in a message, or in +an rbtdb (for cached or authoritative data). + +It is a vaguely OO-style polymorphic data structure, with different +implementations depending on the backing data structure that actually +holds the records. The rdataset is explicitly associated/disassociated +with the backing data structure so that it can maintain refcounts. + + +rdatalist +--------- + +One of the possible implementations of an rdataset is an rdatalist. +(The other important one is inside rbtdb, but we won't go into that +here.) An rdatalist is a linked list of rdata structures, using the +link field inside `sttuct dns_rdata`. It is used to record the +locations of records in a DNS message. An rdatalist doesn't maintain +refcounts. + + +rdata +----- + +BIND9's representation of the right hand side of a DNS record. Again, +it doesn't hold any data itself, but refers to data in wire format +stored elsewhere. It doesn't maintain refcounts - it is usually used +in the context of an rdataset which retains any necessary refcount. + + +type-specific structures +------------------------ + +The file doc/dev/rdata.html explains how the type-specific rdata +conversions work. In some cases the unpacked struct still refers to +the wire-format storage, e.g. when the rdata has variable-sized fields +such as DNSSEC crypto blobs. -- 2.10.1.445.g3cdd5d1

---

Thanks Tony. I took your text and, with minor revisions, put it into dev.md. Also took the opportunity to convert rdata.html to markdown format. Resolving without a CHANGES note.

---