.\" Do *not* edit this file; it was automatically generated by ej2man
.\" Look for a name.ej file with the same name as this filename
.\"
.\" Process this file with the following
.\" nroff -man -Tutf8 maradns.8 | tr '\020' ' '
.\"
.\" Last updated Mon Mar 24 09:52:32 2008
.\"
.TH CSV2_TXT 5 "January 2007" MARADNS "MaraDNS reference"
.\" We don't want hyphenation (it's too ugly)
.\" We also disable justification when using nroff
.\" Due to the way the -mandoc macro works, this needs to be placed
.\" after the .TH heading
.hy 0
.if n .na
.\"
.\" We need the following stuff so that we can have single quotes
.\" In both groff and other UNIX *roff processors
.if \n(.g .mso www.tmac
.ds aq \(aq
.if !\n(.g .if '\(aq'' .ds aq \'

.SH "NAME"
.PP
csv2_txt - Description of txt and raw resource records in the csv2 zone
file
.SH "DESCRIPTION"
.PP
Due to the complexity of TXT and RAW records, this man page is
dedicated to describing the csv2 format of this RR.
.PP
TXT and RAW rrs in MaraDNS\(aq csv2 zone files can store any arbitrary
binary data. Additionally, it is possible to arbitrarily divide up
TXT records in to chunks (chunks, which RFC1035 call
"character-string"s,
are described below).
.PP
.in -3
\fBASCII AND UTF-8 DATA\fR
.PP
If a given TXT field or RAW record contains only ASCII data, creating a
record is easy: Place the full data between single quotes, like
this:

.nf
a.example.com. TXT \(aqThis is some text\(aq ~
.fi

It is also possible, to place almost any printable ASCII characters
between quotes. The \(aq~\(aq (tilde) character is not allowed unless
csv2_tilde_handling has a value of 0; the \(aq|\(aq (pipe), \(aq#\(aq
(hash) and
non-printable ASCII control characters are not allowed in TXT data
if the ~ is used to separate records. If there are any bytes
with a value of 0x80 or more, the data must be UTF-8 encoded Unicode.
.PP
The printable ASCII characters not allowed in quotes are the \(aq
character,
the \(aq|\(aq character, the \(aq~\(aq (tilde) character, and the
\(aq#\(aq character.
See BACKSLASH ESCAPE SEQUENCES below for information on adding these
characters to TXT or RAW fields.
.PP
.in -3
\fBUNQUOTED DATA\fR
.PP
Note that the record does not have to be quoted. As long as the
record only contains ASCII alphanumeric data, and/or the characters
\(aq-\(aq, \(aq_\(aq, \(aq+\(aq, \(aq%\(aq, \(aq!\(aq, \(aq^\(aq, and
\(aq=\(aq, the data can be unquoted
as follows:

.nf
c.example.com. TXT This_is_100%_unquoted_text_+symbols!
.fi

It is also possible to mix quoted and unquoted text, such as this:

.nf
d.example.com. TXT This\(aq is a mix \(aqof_unquoted\(aq and quoted \(aqtext!
.fi

Which will have its data look like this:

.nf
This is a mix of_unquoted and quoted text!
.fi

When mixing quoted and unquoted data, it is important to have all
whitespace
.I "inside"
quotes.
.PP
.in -3
\fBBACKSLASH ESCAPE SEQUENCES\fR
.PP
In order to accommodate storing non-UTF-8 high bit characters, the
single quote character, non-printable ASCII control codes, the
\(aq|\(aq,
\(aq~\(aq, and \(aq#\(aq characters, and to permit multi-line TXT/RAW
records
(with comments allowed mid-record), the TXT/RAW RR allows backslashes.
These backslashes only have significance
.I "outside"
of quoted text;
if they are placed inside single quotes, they are not interpreted and
result in a literal backslash being added to the resource record data.
.PP
The following characters can be backslashed:
.TP 3
\(aq
When backslashed, the adds a literal quote to the resource record.
.TP 3
whitespace
When any whitespace is backslashed (space, newline, cr, and tab), this
indicates that the record has not ended, and that more data for this
resource will follow. This also allows comments to be placed in
TXT and RAW resource records. What happens is that the backslash
indicates that any whitespace characters (space, tab, carriage return,
and line feed) are to be ignored until
the next non-whitespace character that is not a # (hash). If a
# is seen, this indicates that we ignore any and all characters until
the
next carriage return or line feed, and continue to ignore everything
until the next non-whitespace character.
See the section on multi-line and
commented records for examples.
.TP 3
0123
When a number between 0 and 3 is backslashed, this indicates the
beginning of a three-digit octal number.
.TP 3
x
When an x is backslashed, this indicates the beginning of a two-digit
hexadecimal number.
.PP
Note that, with the exception of the single quote, the backslash
character
is
.I "not"
used to remove the meta-significance of a given character.
In particular, unlike other environments, it is not possible to
backslash
spaces. Spaces can be represented either as \(aq \(aq in quotes, \\x20,
or
as \\040.
.PP
Here are some examples of backslashed data.
In this example, we see backslash sequences being used to store
non-UTF-8
hi-bit data:

.nf
e.example.com. TXT \\x80\\x81\\x82\\x83 ~
.fi

This same data can also be created as follows:

.nf
f.example.com. TXT \\200\\201\\202\\203 ~
.fi

Octal and hex information can be mixed:

.nf
g.example.com. TXT \\200\\x81\\202\\x83 ~
.fi

Literal single quotes can be placed in resource records:

.nf
h.example.com. TXT \(aqperl -e \(aq\\\(aq\(aqprint "A Perl of a TXT record!\\n"\(aq\\\(aq ~
.fi

The above example produces this record:

.nf
perl -e \(aqprint "A Perl of a TXT record!\\n"\(aq ~
.fi

To render the \(aq~\(aq character, use the escape sequence \\x7e
(outside of
quotes). For example:

.nf
h1.example.com. TXT \(aqhttp://ocf.berkeley.edu/\(aq\\x7e\(aqset\(aq ~
.fi

Produces this record:

.nf
http://ocf.berkeley.edu/~set
.fi

To render the \(aq|\(aq character, use the escape sequence \\x7c:

.nf
h2.example.com. TXT \(aqls \(aq\\x7c\(aq more\(aq ~
.fi

Produces this record:

.nf
ls | more
.fi

To render the \(aq#\(aq character, use the escape sequence \\x23:

.nf
h3.example.com. TXT \(aqPress \(aq\\x23\(aq for customer service\(aq ~
.fi

Produces this record:

.nf
Press # for customer service
.fi
.PP

.in -3
\fBMULTI-LINE AND COMMENTED RECORDS\fR
.PP
By utilizing backslashes followed by comments, it is possible to have
multi-line and commented TXT and RAW records. The following resource
record will span more than one line on an 80-column display:

.nf
i.example.com. TXT \(aqNot only did the quick brown fox jump over the lazy dog, but the lazy dog jumped over the cat.\(aq ~
.fi

Without affecting this resource record, the same data can be split over
multiple lines:

.nf
j.example.com. TXT \(aqNot only did the quick brown fox jump \(aq\\
                   \(aqover the lazy dog, but the lazy dog\(aq\\
                   \(aq jumped over the cat.\(aq ~
.fi

Some points:
.TP 2
*
The backslash must be outsize of the quotes (or a literal backslash
will
be added to the record)
.TP 2
*
The backslash must be present
.I "before"
any unquoted white space.
Usually, the backslash is placed immediately after the
quote character.
.TP 2
*
Unlike other environments, it does not matter whether or not there
is invisible whitespace after the backslash.
.PP
It is also possible to add comments after such a backslash as follows:

.nf
k.example.com. TXT \(aqNot only did the quick brown fox jump \(aq\\ # The fox
                   \(aqover the lazy dog, but the lazy dog\(aq\\    # The dog
                   \(aq jumped over the cat.\(aq ~                 # The cat
.fi

Note that, since the third comment is not preceded by a backslash, this
indicates the end of the resource record.
.PP
There can also be multiple lines dedicated to
comments (and, optionally, even blank lines) in the middle
of TXT and RAW record data:

.nf
k2.example.com. TXT \(aqThis is some data \(aq\\
# Here we have some comments followed by a blank line

# Now we have some more comments, 
# followed by the rest of the data
    \(aqand this is the rest of the data\(aq ~
.fi
.PP
.PP
.in -3
\fBMULTIPLE TXT CHUNKS\fR
.PP
TXT RRs may be divided up in to multiple "chunks" (RFC1035 calls these
"character-string"s). A single chunk can be anywhere from zero to 255
bytes long. The default is to have one chunk, as follows:

.nf
o.example.com. TXT \(aqTXT record with only one chunk\(aq ~
.fi

It is also possible to have a record with multiple chunks. Chunks
are delimited by an unquoted \(aq;\(aq character:

.nf
p.example.com. TXT \(aqThis is chunk one\(aq;\(aqThis is chunk two\(aq ~
.fi

Or:

.nf
q.example.com. TXT \(aqThis is chunk one\(aq;\\   # Our first chunk
                    This_is_chunk_two;\\    # Our second chunk
                   \(aqThis is chunk three\(aq ~ # Our final chunk
.fi

Quoted ; characters simply add a ; to the record data.
.PP
If a single TXT chunk is longer than 255 bytes long, the csv2 parser
will
report an error in the zone file: Single TXT chunk too long
.PP
In order to resolve this, place unquoted ; characters in the record
data
so that each chunk is under 255 octets (bytes or characters) in length.
.PP
It is possible to have zero length chunks:

.nf
r.example.com. TXT \(aqchunk one\(aq;;\(aqchunk three\(aq ~ # Chunk two zero-length
.fi

In particular, is is possible to have zero length chunks at the
beginning and end of a TXT record:

.nf
s.example.com. TXT ;\(aqchunk two\(aq; ~ # Chunks one and three zero-length
.fi

Do not place semicolons at the beginning nor end of TXT records unless
you wish to have these zero-length chunks.
.PP
Chunk support only exists for TXT records. An unquoted ; character will
cause a syntax error in a RAW record.
.PP
.in -3
\fBRAW RECORDS\fR
.PP
With the exception of no support for chunk delimiters, and the addition
of a
numeric record type before the record data, the format for RAW records
is
identical to text records. For example, if we wish to have a "Kitchen
Sink"
RR record, which has the 8-bit binary numbers "16", "1", and "2",
followed
by the ASCII string "Kitchen sink+ data", we can specify this in any of
the
following manners:

.nf
t1.example.com. RAW 40 \\x10\\x01\\x02\(aqKitchen sink\(aq\\x2b\(aq data\(aq ~
.fi


.nf
t.example.com. RAW 40 \\020\\001\\002Kitchen\(aq sink+ data\(aq ~
.fi


.nf
u.example.com. RAW 40 \\x10\\x01\\x02Kitchen\\x20sink+\\x20data ~
.fi


.nf
v.example.com. RAW 40 \\x10\\001\\x02\\
                      \(aqKitchen sink+ data\(aq ~
.fi


.nf
w.example.com. RAW 40 \\x10\\ # Meaning: 16
                      \\x01\\ # Coding: 1
                      \\x02\\ # Sub-coding: 2
                      \(aqKitchen sink+ data\(aq ~ # Data: \(aqKitchen sink+ data\(aq
.fi

.SH "LEGAL DISCLAIMER"
.PP
THIS SOFTWARE IS PROVIDED BY THE AUTHORS \(aq\(aqAS IS\(aq\(aq AND ANY
EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.SH "AUTHOR"
.PP
Sam Trenholme
http://www.samiam.org/