Commit | Line | Data |
---|---|---|
1479465f GJ |
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 . |