chiark - git - mdw - dpkg/blob - man/deb822.man

   1 .\" dpkg manual page - deb822(5)
   2 .\"
   3 .\" Copyright © 1995-1996 Ian Jackson <ijackson@chiark.greenend.org.uk>
   4 .\" Copyright © 2015 Guillem Jover <guillem@debian.org>
   5 .\"
   6 .\" This is free software; you can redistribute it and/or modify
   7 .\" it under the terms of the GNU General Public License as published by
   8 .\" the Free Software Foundation; either version 2 of the License, or
   9 .\" (at your option) any later version.
  10 .\"
  11 .\" This is distributed in the hope that it will be useful,
  12 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 .\" GNU General Public License for more details.
  15 .\"
  16 .\" You should have received a copy of the GNU General Public License
  17 .\" along with this program.  If not, see <https://www.gnu.org/licenses/>.
  18 .
  19 .TH deb822 5 "%RELEASE_DATE%" "%VERSION%" "dpkg suite"
  20 .nh
  21 .SH NAME
  22 deb822 \- Debian RFC822 control data format
  23 .
  24 .SH DESCRIPTION
  25 The package management system manipulates data represented in a common
  26 format, known as \fIcontrol data\fP, stored in \fIcontrol files\fP.
  27 Control files are used for source packages, binary packages and the
  28 \fB.changes\fP files which control the installation of uploaded
  29 files (\fBdpkg\fP's internal databases are in a similar format).
  30 .
  31 .SH SYNTAX
  32 A control file consists of one or more paragraphs of fields (the paragraphs
  33 are also sometimes referred to as stanzas).
  34 The paragraphs are separated by empty lines.
  35 Parsers may accept lines consisting solely of U+0020 \fBSPACE\fP and
  36 U+0009 \fBTAB\fP as paragraph separators, but control files should use
  37 empty lines.
  38 Some control files allow only one paragraph; others allow several, in which
  39 case each paragraph usually refers to a different package.
  40 (For example, in source packages, the first paragraph refers to the source
  41 package, and later paragraphs refer to binary packages generated from the
  42 source.)
  43 The ordering of the paragraphs in control files is significant.
  44
  45 Each paragraph consists of a series of data fields.
  46 Each field consists of the field name followed by a colon
  47 (U+003A ‘\fB:\fP’), and then the data/value associated with that field.
  48 The field name is composed of US-ASCII characters excluding control
  49 characters, space, and colon (i.e., characters in the ranges
  50 U+0021 ‘\fB!\fP’ through U+0039 ‘\fB9\fP’, and
  51 U+003B ‘\fB;\fP’ through U+007E ‘\fB~\fP’, inclusive).
  52 Field names must not begin with the comment character
  53 (U+0023 ‘\fB#\fP’), nor with the hyphen character
  54 (U+002D ‘\fB\-\fP’).
  55
  56 The field ends at the end of the line or at the end of the last continuation
  57 line (see below).
  58 Horizontal whitespace (U+0020 \fBSPACE\fP and U+0009 \fBTAB\fP) may occur
  59 immediately before or after the value and is ignored there; it is conventional
  60 to put a single space after the colon.
  61 For example, a field might be:
  62 .RS
  63 .nf
  64 Package: dpkg
  65 .fi
  66 .RE
  67 the field name is \fBPackage\fP and the field value \fBdpkg\fP.
  68
  69 Empty field values are only permitted in source package control files
  70 (\fIdebian/control\fP).
  71 Such fields are ignored.
  72
  73 A paragraph must not contain more than one instance of a particular field name.
  74
  75 There are three types of fields:
  76
  77 .RS 0
  78 .TP
  79 .B simple
  80 The field, including its value, must be a single line.
  81 Folding of the field is not permitted.
  82 This is the default field type if the definition of the field does not
  83 specify a different type.
  84 .TP
  85 .B folded
  86 The value of a folded field is a logical line that may span several lines.
  87 The lines after the first are called continuation lines and must start with
  88 a U+0020 \fBSPACE\fP or a U+0009 \fBTAB\fP.
  89 Whitespace, including any newlines, is not significant in the field values
  90 of folded fields.
  91
  92 This folding method is similar to RFC5322, allowing control files that
  93 contain only one paragraph and no multiline fields to be read by parsers
  94 written for RFC5322.
  95 .TP
  96 .B multiline
  97 The value of a multiline field may comprise multiple continuation lines.
  98 The first line of the value, the part on the same line as the field name,
  99 often has special significance or may have to be empty.
 100 Other lines are added following the same syntax as the continuation lines
 101 of the folded fields.
 102 Whitespace, including newlines, is significant in the values of multiline
 103 fields.
 104 .RE
 105
 106 Whitespace must not appear inside names (of packages, architectures, files
 107 or anything else) or version numbers, or between the characters of
 108 multi-character version relationships.
 109
 110 The presence and purpose of a field, and the syntax of its value may differ
 111 between types of control files.
 112
 113 Field names are not case-sensitive, but it is usual to capitalize the field
 114 names using mixed case as shown below.
 115 Field values are case-sensitive unless the description of the field says
 116 otherwise.
 117
 118 Paragraph separators (empty lines) and lines consisting only of
 119 U+0020 \fBSPACE\fP and U+0009 \fBTAB\fP, are not allowed within field
 120 values or between fields.
 121 Empty lines in field values are usually escaped by representing them by a
 122 U+0020 \fBSPACE\fP followed by a dot (U+002E ‘\fB.\fP’).
 123
 124 Lines starting with U+0023 ‘\fB#\fP’, without any preceding whitespace
 125 are comments lines that are only permitted in source package control files
 126 (\fIdebian/control\fP) and in \fBdeb\-origin\fP(5) files.
 127 These comment lines are ignored, even between two continuation lines.
 128 They do not end logical lines.
 129
 130 All control files must be encoded in UTF-8.
 131 .
 132 .\" .SH EXAMPLE
 133 .\" .RS
 134 .\" .nf
 135 .\" .fi
 136 .\" .RE
 137 .
 138 .SH SEE ALSO
 139 .BR RFC822 ,
 140 .BR RFC5322 .