update-binfmts (8) Linux Manual Page

update-binfmts – maintain registry of executable binary formats

Synopsis

update\-binfmts [options ] –-install name path spec

update\-binfmts [options ] –-remove name path

update\-binfmts [options ] –-import [name ]

update\-binfmts [options ] –-unimport [name ]

update\-binfmts [options ] –-display [name ]

update\-binfmts [options ] –-enable [name ]

update\-binfmts [options ] –-disable [name ]

update\-binfmts [options ] –-find [path ]

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). update\-binfmts manages a persistent database of these interpreters.

When each package providing a registered interpreter is installed, changed, or removed, update\-binfmts is called to update information about that interpreter. update\-binfmts is usually called from the postinst or prerm scripts in Debian packages.

Options

Exactly one action must be specified; this may be accompanied by any one of the common options.

Common Options

–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.

When installing new formats, the –-import action should be used instead. Similarly, when removing old formats, the –-unimport action should be used instead.

–admindir directory

Specifies the administrative directory, when this is to be different from the default of /var/lib/binfmts

–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

–test

Don’t do anything, just demonstrate what would be done.

–help

Display some usage information.

–version

Display version information.

Actions

–install 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 Sx BINARY FORMAT SPECIFICATIONS below).

–-install will attempt to enable this binary format in the kernel as well as adding it to its own database; see –-enable below.

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 name path

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 –-disable below.

–import [name ]

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 Sx FORMAT FILES below for the required contents of these files.

For packages, this is preferable to using the –-install option, as a format file can be installed without update\-binfmts needing to be available.

–unimport [name ]

Unimport a packaged format file called name or unimport 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 Sx FORMAT FILES below for the required contents of these files.

For packages, this is preferable to using the –-remove option, for symmetry with –-import

–display [name ]

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 disabled.

–enable [name ]

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 [name ]

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.

–find [path ]

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.

Binary Format Specifications

–magic byte-sequence

This matches all files with the magic number byte-sequence Hexadecimal escapes may be included in the byte-sequence by preceding them with