git.gag.com Git - debian/amanda/blob - man/amanda-archive-format.5

   1 .\"     Title: amanda-archive-format
   2 .\"    Author: Dustin J. Mitchell <dustin@zmanda.com>
   3 .\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
   4 .\"      Date: 01/22/2009
   5 .\"    Manual: File formats and conventions
   6 .\"    Source: Amanda 2.6.1
   7 .\"  Language: English
   8 .\"
   9 .TH "AMANDA\-ARCHIVE\-FOR" "5" "01/22/2009" "Amanda 2\&.6\&.1" "File formats and conventions"
  10 .\" -----------------------------------------------------------------
  11 .\" * (re)Define some macros
  12 .\" -----------------------------------------------------------------
  13 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  14 .\" toupper - uppercase a string (locale-aware)
  15 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  16 .de toupper
  17 .tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
  18 \\$*
  19 .tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
  20 ..
  21 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  22 .\" SH-xref - format a cross-reference to an SH section
  23 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  24 .de SH-xref
  25 .ie n \{\
  26 .\}
  27 .toupper \\$*
  28 .el \{\
  29 \\$*
  30 .\}
  31 ..
  32 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  33 .\" SH - level-one heading that works better for non-TTY output
  34 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  35 .de1 SH
  36 .\" put an extra blank line of space above the head in non-TTY output
  37 .if t \{\
  38 .sp 1
  39 .\}
  40 .sp \\n[PD]u
  41 .nr an-level 1
  42 .set-an-margin
  43 .nr an-prevailing-indent \\n[IN]
  44 .fi
  45 .in \\n[an-margin]u
  46 .ti 0
  47 .HTML-TAG ".NH \\n[an-level]"
  48 .it 1 an-trap
  49 .nr an-no-space-flag 1
  50 .nr an-break-flag 1
  51 \." make the size of the head bigger
  52 .ps +3
  53 .ft B
  54 .ne (2v + 1u)
  55 .ie n \{\
  56 .\" if n (TTY output), use uppercase
  57 .toupper \\$*
  58 .\}
  59 .el \{\
  60 .nr an-break-flag 0
  61 .\" if not n (not TTY), use normal case (not uppercase)
  62 \\$1
  63 .in \\n[an-margin]u
  64 .ti 0
  65 .\" if not n (not TTY), put a border/line under subheading
  66 .sp -.6
  67 \l'\n(.lu'
  68 .\}
  69 ..
  70 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  71 .\" SS - level-two heading that works better for non-TTY output
  72 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  73 .de1 SS
  74 .sp \\n[PD]u
  75 .nr an-level 1
  76 .set-an-margin
  77 .nr an-prevailing-indent \\n[IN]
  78 .fi
  79 .in \\n[IN]u
  80 .ti \\n[SN]u
  81 .it 1 an-trap
  82 .nr an-no-space-flag 1
  83 .nr an-break-flag 1
  84 .ps \\n[PS-SS]u
  85 \." make the size of the head bigger
  86 .ps +2
  87 .ft B
  88 .ne (2v + 1u)
  89 .if \\n[.$] \&\\$*
  90 ..
  91 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  92 .\" BB/BE - put background/screen (filled box) around block of text
  93 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  94 .de BB
  95 .if t \{\
  96 .sp -.5
  97 .br
  98 .in +2n
  99 .ll -2n
 100 .gcolor red
 101 .di BX
 102 .\}
 103 ..
 104 .de EB
 105 .if t \{\
 106 .if "\\$2"adjust-for-leading-newline" \{\
 107 .sp -1
 108 .\}
 109 .br
 110 .di
 111 .in
 112 .ll
 113 .gcolor
 114 .nr BW \\n(.lu-\\n(.i
 115 .nr BH \\n(dn+.5v
 116 .ne \\n(BHu+.5v
 117 .ie "\\$2"adjust-for-leading-newline" \{\
 118 \M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
 119 .\}
 120 .el \{\
 121 \M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
 122 .\}
 123 .in 0
 124 .sp -.5v
 125 .nf
 126 .BX
 127 .in
 128 .sp .5v
 129 .fi
 130 .\}
 131 ..
 132 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 133 .\" BM/EM - put colored marker in margin next to block of text
 134 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 135 .de BM
 136 .if t \{\
 137 .br
 138 .ll -2n
 139 .gcolor red
 140 .di BX
 141 .\}
 142 ..
 143 .de EM
 144 .if t \{\
 145 .br
 146 .di
 147 .ll
 148 .gcolor
 149 .nr BH \\n(dn
 150 .ne \\n(BHu
 151 \M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
 152 .in 0
 153 .nf
 154 .BX
 155 .in
 156 .fi
 157 .\}
 158 ..
 159 .\" -----------------------------------------------------------------
 160 .\" * set default formatting
 161 .\" -----------------------------------------------------------------
 162 .\" disable hyphenation
 163 .nh
 164 .\" disable justification (adjust text to left margin only)
 165 .ad l
 166 .\" -----------------------------------------------------------------
 167 .\" * MAIN CONTENT STARTS HERE *
 168 .\" -----------------------------------------------------------------
 169 .SH "Name"
 170 amanda-archive-format \- Format of amanda archive streams
 171 .SH "DESCRIPTION"
 172 .PP
 173 The
 174 \fIAmanda\fR
 175 archive format is designed to be a simple, efficient means of interleaving multiple simultaneous files, allowing an arbitrary number of data streams for a file\&. It is a streaming format in the sense that the writer need not know the size of files until they are completely written to the archive, and the reader can process the archive in constant space\&.
 176 .SH "DATA MODEL"
 177 .PP
 178 The data stored in an archive consists of an unlimited number of files\&. Each file consists of a number of "attributes", each identified by a 16\-bit ID\&. Each attribute can contain an unlimited amount of data\&.
 179 .PP
 180 Attribute IDs less than 16 (AMAR_ATTR_APP_START) are reserved for special purposes, but the remaining IDs are available for application\-specific uses\&.
 181 .SH "STRUCTURE"
 182 .SS "RECORDS"
 183 .PP
 184 A record can be either a header record or a data record\&. A header record serves as a "checkpoint" in the file, with a magic value that can be used to recognize archive files\&.
 185 .PP
 186 A header record has a fixed size of 28 bytes, as follows:
 187 .sp
 188 .nf
 189   28 bytes:    magic string
 190 .fi
 191 The magic string is the ASCII text "AMANDA ARCHIVE FORMAT " followed by a decimal representation of the format version number (currently \'1\'), padded to 28 bytes with NUL bytes\&.
 192 .PP
 193 A data record has a variable size, as follows:
 194 .sp
 195 .nf
 196   2 bytes:     file number
 197   2 bytes:     attribute ID
 198   4 bytes:     data size (N)
 199   N bytes:     data
 200 .fi
 201 The file number and attribute ID serve to identify the data stream to which this data belongs\&. The low 31 bits of the data size give the number of data bytes following, while the high bit (the EOA bit) indicates the end of the attribute, as described below\&. Because records are generally read into memory in their entirety, the data size must not exceed 4MB (4194304 bytes)\&. All integers are in network byte order\&.
 202 .PP
 203 A header record is distinguished from a data record by the magic string\&. The file number 0x414d, corresponding to the characters "AM", is forbidden and must be skipped on writing\&.
 204 .PP
 205 Attribute ID 0 (AMAR_ATTR_FILENAME) gives the filename of a file\&. This attribute is mandatory for each file, must be nonempty, must fit in a single record, and must precede any other attributes for the same file in the archive\&. The filename should be a printable string (ASCII or UTF\-8), to facilitate use of generic archive\-display utilities, but the format permits any nonempty bytestring\&. The filename cannot span multiple records\&.
 206 .PP
 207 Attribute ID 1 (AMAR_ATTR_EOF) signals the end of a file\&. This attribute must contain no data, but should have the EOA bit set\&.
 208 .SS "CONNECTION TO DATA MODEL"
 209 .PP
 210 Each file in an archive is assigned a file number distinct from any other active file in the archive\&. The first record for a file must have attribute ID 0 (AMAR_ATTR_FILENAME), indicating a filename\&. A file ends with an empty record with ID 1 (AMAR_ATTR_EOF)\&. For every file at which a reader might want to begin reading, the filename record should be preceded by a header record\&. How often to write header records is left to the discretion of the application\&.
 211 .PP
 212 All data records with the same file number and attribute ID are considered a part of the same attribute\&. The boundaries between such records are not significant to the contents of the attribute, and both readers and writers are free to alter such boundaries as necessary\&.
 213 .PP
 214 The final data record for each attribute has the high bit (the EOA bit) of its data size field set\&. A writer must not reuse an attribute ID within a file\&. An attribute may be terminated by a record containing both data and an EOA bit, or by a zero\-length record with its EOA bit set\&.
 215 .SH "SEE ALSO"
 216 .PP
 217
 218 \fBamanda\fR(8),
 219 .SH "Author"
 220 .PP
 221 \fBDustin J\&. Mitchell\fR <\&dustin@zmanda\&.com\&>
 222 .RS 4
 223 Zmanda, Inc\&. (\FChttp://www\&.zmanda\&.com\F[])
 224 .RE