File: update-binfmts.8

package info (click to toggle)
binfmt-support 1.1.5
  • links: PTS
  • area: main
  • in suites: woody
  • size: 92 kB
  • ctags: 25
  • sloc: perl: 622; makefile: 36; sh: 32
file content (265 lines) | stat: -rw-r--r-- 7,520 bytes parent folder | download
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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
.\" update-binfmts.8
.TH UPDATE-BINFMTS 8 "6 January 2002" DEBIAN "Debian"
.SH NAME
update-binfmts \- maintain registry of executable binary formats
.SH SYNOPSIS
.B update-binfmts
.RI [ options ]
.B \-\-install
.I name path spec
.br
.B update-binfmts
.RI [ options ]
.B \-\-remove
.I name path
.br
.B update-binfmts
.RI [ options ]
.B \-\-import
.RI [ name ]
.br
.B update-binfmts
.RI [ options ]
.B \-\-display
.RI [ name ]
.br
.B update-binfmts
.RI [ options ]
.B \-\-enable
.RI [ name ]
.br
.B update-binfmts
.RI [ options ]
.B \-\-disable
.RI [ name ]
.SH DESCRIPTION
Versions 2.1.43 and later of the Linux kernel have contained the binfmt_misc
module.
This enables a system administrator to register interpreters for various
binary formats based on a magic number or their file extension, and cause
the appropriate interpreter to be invoked whenever a matching file is
executed.
Think of it as a more flexible version of the #! executable interpreter
mechanism, or as something which can behave a little like "associations" in
certain other operating systems (though in GNU/Linux the tendency is to keep
this sort of thing somewhere else, like your file manager).
.B update-binfmts
manages a persistent database of these interpreters.
.PP
When each package providing a registered interpreter is installed, changed,
or removed,
.B update-binfmts
is called to update information about that interpreter.
.B update-binfmts
is usually called from the
.I postinst
or
.I prerm
scripts in Debian packages.
.SH OPTIONS
Exactly one action must be specified; this may be accompanied by any one of
the common options.
.SS "COMMON OPTIONS"
.TP
.BI \-\-package " package-name"
Specifies the name of the current package, to be used by package
post-installation and pre-removal scripts.
System administrators installing binary formats for local use should
probably ignore this option.
.IP
When installing new formats, the
.B \-\-import
action should be used instead.
.TP
.BI \-\-admindir " directory"
Specifies the administrative directory, when this is to be different from
the default of /var/lib/binfmts.
.TP
.BI \-\-importdir " directory"
Specifies the directory from which packaged binary formats are imported,
when this is to be different from the default of /usr/share/binfmts.
.TP
.B \-\-test
Don't do anything, just demonstrate what would be done.
.TP
.B \-\-help
Display some usage information.
.TP
.B \-\-version
Display version information.
.SS ACTIONS
.TP
.BI \-\-install " name path spec"
Install a binary format identified by
.I name
with interpreter
.I path
into the database.
After registration, this format will be used when the kernel tries to
execute a file matching
.I spec
(see
.B BINARY FORMAT SPECIFICATIONS
below).
.IP
.B \-\-install
will attempt to enable this binary format in the kernel as well as adding it
to its own database; see
.B \-\-enable
below.
.IP
You cannot install a format with any of the names ".", "..", "register", or
"status", as these are used by the filesystem or the binfmt_misc module.
.TP
.BI \-\-remove " name path"
Remove the binary format identified by
.I name
with interpreter
.I path
from the database.
This will also attempt to disable the binary format in the kernel; see
.B \-\-disable
below.
.TP
\fB\-\-import\fP [\fIname\fP]
Import a packaged format file called
.IR name ,
or import all format files currently on the system if no
.I name
is given.
If
.I name
is not a full path, it is assumed to be a file in the import directory
(/usr/share/binfmts by default).
See
.B FORMAT FILES
below for the required contents of these files.
.IP
For packages, this is preferable to using the
.B \-\-install
option, as a format file can be installed without
.B update-binfmts
needing to be available.
.TP
\fB\-\-display\fP [\fIname\fP]
Display any information held in the database about the binary format
identifier
.IR name ,
or about all known binary formats if no
.I name
is given.
Also show whether displayed binary formats are enabled or disabled.
.TP
\fB\-\-enable\fP [\fIname\fP]
Enable binary format
.IR name ,
or all known binary formats if no
.I name
is given, in the kernel, thus enabling direct execution of matching files.
You must have binfmt_misc compiled into the kernel or loaded as a module for
this to work.
.TP
\fB\-\-disable\fP [\fIname\fP]
Disable binary format
.IR name ,
or all known binary formats if no
.I name
is given, in the kernel, thus disabling direct execution of matching files.
You must have binfmt_misc compiled into the kernel or loaded as a module for
this to work.
.SS "BINARY FORMAT SPECIFICATIONS"
.TP
.BI \-\-magic " byte-sequence"
This matches all files with the magic number
.IR byte-sequence .
Hexadecimal escapes may be included in the
.I byte-sequence
by preceding them with \ex, for example '\ex0a' for a linefeed.
Remember to protect such escapes with quotes or an additional backslash to
prevent their interpretation by the shell.
.IP
Also see
.BR \-\-offset " and " \-\-mask .
.TP
.BI \-\-offset " offset"
This is the offset of the magic/mask in the file, counted in bytes. The default
is 0. Only valid with
.BR \-\-magic .
.TP
.BI \-\-mask " byte-sequence"
This mask will be logically-ANDed with the string to be checked against the
magic number given with
.BR \-\-magic .
The default is all 0xff, i.e. no effect.
Only valid with
.BR \-\-magic.
.TP
.BI \-\-extension " extension"
This matches all files whose names end in
.RI \(lq. extension \(rq.
Hexadecimal escapes are not recognized here.
Extension matching is case-sensitive.
.SS "FORMAT FILES"
A format file is a sequence of options, one per line, corresponding roughly
to the options given to an
.B \-\-install
command.
Each option consists of a key, followed by whitespace, followed by a value.
.PP
The
.I package
option should be set to the current package.
The
.I interpreter
option should be set to the path to the interpreter that will handle this
binary format.
The
.IR magic ", " offset ", " mask ", and " extension
options correspond to the command-line options of the same names.
.SH EXIT STATUS
.IP 0
The requested action was successfully performed.
.IP 2
Problems were encountered whilst parsing the command line or performing the
action.
.SH EXAMPLES
This format file can be used with an interpreter capable of handling Java
\&.class files:
.PP
.nf
    package javawrapper
    interpreter /usr/bin/javawrapper
    magic \exca\exfe\exba\exbe
.fi
.PP
This corresponds roughly to the following command:
.PP
.nf
    update-binfmts --package javawrapper \e
        --install javawrapper /usr/bin/javawrapper \e
        --magic '\exca\exfe\exba\exbe'
.fi
.SH NOTES
If you're not careful, you can break your system with update-binfmts.
An easy way to do this is to register an ELF binary as a handler for ELF,
which will almost certainly cause your system to hang immediately; even if
it doesn't, you won't be able to run update-binfmts to fix it.
In the future update-binfmts may have some checks to prevent this sort of
thing happening accidentally, though of course you can still manipulate the
binfmt_misc kernel module directly.
.SH AUTHOR
.B update-binfmts
is copyright (c) 2000-2002 Colin Watson <cjwatson@debian.org>.
See the GNU General Public License version 2 or later for copying
conditions.
.PP
You can find the GNU GPL in /usr/share/common-licenses/GPL on any modern
Debian system.
.PP
Richard Guenther wrote the binfmt_misc kernel module.
.SH THANKS
Ian Jackson wrote
.B update-alternatives
and
.BR dpkg-divert ,
from which this program borrows heavily.