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