maintain registry of executable binary
name path spec
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). update-binfmts
persistent database of these interpreters.
When each package providing a registered interpreter is installed, changed, or
is called to update
information about that interpreter.
is usually called from the
scripts in Debian packages.
Exactly one action must be specified; this may be accompanied by any one of the
- 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
When installing new formats, the
should be used instead.
- Specifies the administrative directory, when this is to be
different from the default of
- Specifies the directory from which packaged binary formats
are imported, when this is to be different from the default of
- Don't do anything, just demonstrate what would be
- Display some usage information.
- Display version information.
name path spec
- Install a binary format identified by
name with interpreter
path into the database. After
registration, this format will be used when the kernel tries to execute a
file matching spec (see
FORMAT SPECIFICATIONS below).
attempt to enable this binary format in the kernel as well as adding it to
its own database; see
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.
- Remove the binary format identified by
name with interpreter
path from the database. This will also
attempt to disable the binary format in the kernel; see
- Import a packaged format file called
name, or import all format files
currently on the system if no name is
given. If name is not a full path, it is
assumed to be a file in the import directory
(/usr/share/binfmts by default). See
FORMAT FILES below for
the required contents of these files.
For packages, this is preferable to using the
option, as a format file can be installed without
update-binfmts needing to be available.
- Display any information held in the database about the
binary format identifier name, or about
all known binary formats if no name is
given. Also show whether displayed binary formats are enabled or
- Enable binary format name,
or all known binary formats if no 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.
- Disable binary format
name, or all known binary formats if no
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.
- Print the list of interpreters that will be tried in
sequence when attempting to execute path,
one per line. The first one for which
execvp(3) succeeds will be used.
Note that if multiple formats match an executable, then the order is in
general not defined, and may not be preserved between
update-binfmts operations, so you should
generally try to ensure that this option prints at most one line for any
given path. The exception to this is that
any format with a userspace detector will be run before any format without
a userspace detector.
- This matches all files with the magic number
byte-sequence. Hexadecimal escapes may be
included in the byte-sequence by
preceding them with \x, for example ‘\x0a’ for a linefeed.
Remember to protect such escapes with quotes or an additional backslash to
prevent their interpretation by the shell.
Also see --offset
- This is the offset of the magic/mask in the file, counted
in bytes. The default is 0. Only valid with
- This mask will be logically-ANDed with the string to be
checked against the magic number given with
default is all 0xff, i.e. no effect. Only valid with
- This matches all files whose names end in
escapes are not recognized here. Extension matching is
- If this option is used, a userspace detector program will
be used to check whether the file is suitable for this interpreter. This
may be used when the binary format is more complex than can be handled by
the kernel's format specifications alone. The program should return an
exit code of zero if the file is appropriate and non-zero otherwise.
- Whether to keep the credentials of the original binary to
run the interpreter; this is typically useful to run setuid binaries, but
has security implications.
- Whether to preserve the original
argv when running the interpreter, rather than
overwriting it with the full path to the binary.
- Whether to open the interpreter binary immediately and
always use the opened image. This allows the interpreter from the host to
be used regardless of usage in chroots or different mount namespaces. The
default behaviour is no, meaning that the
kernel should open the interpreter binary lazily when needed. This option
requires Linux 4.8 or newer.
A format file is a sequence of options, one per line, corresponding roughly to
the options given to an
Each option consists of a key, followed by whitespace, followed by a value.
option should be set to the current
package. The interpreter
option should be set
to the path to the interpreter that will handle this binary format. The
options correspond to the
command-line options of the same names.
- The requested action was successfully performed.
- Problems were encountered whilst parsing the command line
or performing the action.
This format file can be used with an interpreter capable of handling Java .class
This corresponds roughly to the following command:
update-binfmts --package javawrapper \
--install javawrapper /usr/bin/javawrapper \
If you're not careful, you can break your system with
. 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
to fix it. In the future
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.
is copyright (C) 2000, 2001, 2002,
2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
⟨firstname.lastname@example.org⟩. See the GNU General Public License
version 3 or later for copying conditions.
You can find the GNU GPL v3 in
on any modern
Richard Guenther wrote the binfmt_misc kernel module.
Ian Jackson wrote update-alternatives
, from which this program borrows