Man Linux: Main Page and Category List


     update-binfmts - maintain registry of executable binary formats


     update-binfmts [options] --install name path spec
     update-binfmts [options] --remove name path
     update-binfmts [options] --import [name]
     update-binfmts [options] --display [name]
     update-binfmts [options] --enable [name]
     update-binfmts [options] --disable [name]


     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.


     Exactly one action must be specified; this may be accompanied by any one
     of the 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

           When installing new formats, the --import action should be used

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

     --cachedir directory
           Specifies the directory in which binary format registration
           instructions are cached, when this is to be different from the
           default of /var/cache/binfmts.

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

           Display some usage information.

           Display version information.

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

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

     --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 \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 and --mask.

     --offset offset
           This is the offset of the magic/mask in the file, counted in bytes.
           The default is 0.  Only valid with --magic.

     --mask byte-sequence
           This mask will be logically-ANDed with the string to be checked
           against the magic number given with --magic.  The default is all
           0xff, i.e. no effect.  Only valid with --magic.

     --extension extension
           This matches all files whose names end in ".extension".
           Hexadecimal escapes are not recognized here.  Extension matching is

     --detector path
           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.

     --credentials yes, --credentials no
           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.

     A format file is a sequence of options, one per line, corresponding
     roughly to the options given to an --install command.  Each option
     consists of a key, followed by whitespace, followed by a value.

     The package 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 magic, offset, mask, extension, detector, and
     credentials options correspond to the command-line options of the same


     0     The requested action was successfully performed.

     2     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 files:

         package javawrapper
         interpreter /usr/bin/javawrapper
         magic \xca\xfe\xba\xbe

     This corresponds roughly to the following command:

         update-binfmts --package javawrapper \
             --install javawrapper /usr/bin/javawrapper \
             --magic '\xca\xfe\xba\xbe'


     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.


     update-binfmts is copyright (c) 2000-2002 Colin Watson
     〈〉.  See the GNU General Public License version 2 or
     later for copying conditions.

     You can find the GNU GPL in /usr/share/common-licenses/GPL on any modern
     Debian system.

     Richard Guenther wrote the binfmt_misc kernel module.


     Ian Jackson wrote update-alternatives and dpkg-divert, from which this
     program borrows heavily.