                                 NAME

   csv2_txt - Description of txt and raw resource records in the
   csv2 zone file

                             DESCRIPTION

   Due to the complexity of TXT and RAW records, this man page
   is dedicated to describing the csv2 format of this RR.

   TXT and RAW rrs in MaraDNS' 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).

ASCII AND UTF-8 DATA

   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:
a.example.com. TXT 'This is some text' ~

   It is also possible, to place almost any printable ASCII
   characters between quotes. The '~' (tilde) character is not
   allowed unless csv2_tilde_handling has a value of 0; the '|'
   (pipe), '#' (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. For example:
b.example.com. TXT 'This is an example UTF-8 character: I ♥ MaraDNS'

   (If your font does not have this Unicode symbol, it is a
   heart)

   The printable ASCII characters not allowed in quotes are the
   ' character, the '|' character, the '~' (tilde) character,
   and the '#' character. See BACKSLASH ESCAPE SEQUENCES below
   for information on adding these characters to TXT or RAW
   fields.

UNQUOTED DATA

   Note that the record does not have to be quoted. As long as
   the record only contains ASCII alphanumeric data, and/or the
   characters '-', '_', '+', '%', '!', '^', and '=', the data
   can be unquoted as follows:
c.example.com. TXT This_is_100%_unquoted_text_+symbols!

   It is also possible to mix quoted and unquoted text, such as
   this:
d.example.com. TXT This' is a mix 'of_unquoted' and quoted 'text!

   Which will have its data look like this:
This is a mix of_unquoted and quoted text!

   When mixing quoted and unquoted data, it is important to have
   all whitespace inside quotes.

BACKSLASH ESCAPE SEQUENCES

   In order to accommodate storing non-UTF-8 high bit
   characters, the single quote character, non-printable ASCII
   control codes, the '|', '~', and '#' 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 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.

   The following characters can be backslashed:

   '
          When backslashed, the adds a literal quote to the
          resource record.

   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.

   0123
          When a number between 0 and 3 is backslashed, this
          indicates the beginning of a three-digit octal number.

   x
          When an x is backslashed, this indicates the beginning
          of a two-digit hexadecimal number.

   Note that, with the exception of the single quote, the
   backslash character is 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 ' ' in quotes, \x20, or
   as \040.

   Here are some examples of backslashed data. In this example,
   we see backslash sequences being used to store non-UTF-8
   hi-bit data:
e.example.com. TXT \x80\x81\x82\x83 ~

   This same data can also be created as follows:
f.example.com. TXT \200\201\202\203 ~

   Octal and hex information can be mixed:
g.example.com. TXT \200\x81\202\x83 ~

   Literal single quotes can be placed in resource records:
h.example.com. TXT 'perl -e '\''print "A Perl of a TXT record!\n"'\' ~

   The above example produces this record:
perl -e 'print "A Perl of a TXT record!\n"' ~

   To render the '~' character, use the escape sequence \x7e
   (outside of quotes). For example:
h1.example.com. TXT 'http://ocf.berkeley.edu/'\x7e'set' ~

   Produces this record:
http://ocf.berkeley.edu/~set

   To render the '|' character, use the escape sequence \x7c:
h2.example.com. TXT 'ls '\x7c' more' ~

   Produces this record:
ls | more

   To render the '#' character, use the escape sequence \x23:
h3.example.com. TXT 'Press '\x23' for customer service' ~

   Produces this record:
Press # for customer service

MULTI-LINE AND COMMENTED RECORDS

   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:
i.example.com. TXT 'Not only did the quick brown fox jump over the laz
y dog, but the lazy dog jumped over the cat.' ~

   Without affecting this resource record, the same data can be
   split over multiple lines:
j.example.com. TXT 'Not only did the quick brown fox jump '\
                   'over the lazy dog, but the lazy dog'\
                   ' jumped over the cat.' ~

   Some points:
     * The backslash must be outsize of the quotes (or a literal
       backslash will be added to the record)
     * The backslash must be present before any unquoted white
       space. Usually, the backslash is placed immediately after
       the quote character.
     * Unlike other environments, it does not matter whether or
       not there is invisible whitespace after the backslash.

   It is also possible to add comments after such a backslash as
   follows:
k.example.com. TXT 'Not only did the quick brown fox jump '\ # The fox
                   'over the lazy dog, but the lazy dog'\    # The dog
                   ' jumped over the cat.' ~                 # The cat

   Note that, since the third comment is not preceded by a
   backslash, this indicates the end of the resource record.

   There can also be multiple lines dedicated to comments (and,
   optionally, even blank lines) in the middle of TXT and RAW
   record data:
k2.example.com. TXT 'This is some data '\
# Here we have some comments followed by a blank line

# Now we have some more comments,
# followed by the rest of the data
    'and this is the rest of the data' ~

MULTIPLE TXT CHUNKS

   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:
o.example.com. TXT 'TXT record with only one chunk' ~

   It is also possible to have a record with multiple chunks.
   Chunks are delimited by an unquoted ';' character:
p.example.com. TXT 'This is chunk one';'This is chunk two' ~

   Or:
q.example.com. TXT 'This is chunk one';\   # Our first chunk
                    This_is_chunk_two;\    # Our second chunk
                   'This is chunk three' ~ # Our final chunk

   Quoted ; characters simply add a ; to the record data.

   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

   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.

   It is possible to have zero length chunks:
r.example.com. TXT 'chunk one';;'chunk three' ~ # Chunk two zero-lengt
h

   In particular, is is possible to have zero length chunks at
   the beginning and end of a TXT record:
s.example.com. TXT ;'chunk two'; ~ # Chunks one and three zero-length

   Do not place semicolons at the beginning nor end of TXT
   records unless you wish to have these zero-length chunks.

   Chunk support only exists for TXT records. An unquoted ;
   character will cause a syntax error in a RAW record.

RAW RECORDS

   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:
t1.example.com. RAW 40 \x10\x01\x02'Kitchen sink'\x2b' data' ~

t.example.com. RAW 40 \020\001\002Kitchen' sink+ data' ~

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

v.example.com. RAW 40 \x10\001\x02\
                      'Kitchen sink+ data' ~

w.example.com. RAW 40 \x10\ # Meaning: 16
                      \x01\ # Coding: 1
                      \x02\ # Sub-coding: 2
                      'Kitchen sink+ data' ~ # Data: 'Kitchen sink+ da
ta'

                           LEGAL DISCLAIMER

   THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''AS IS'' 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.

                                AUTHOR

   Sam Trenholme http://www.samiam.org/
