mkefs

Updated: October 28, 2024

Build an embedded filesystem (QNX)

Syntax:

mkefs [option...]* [buildfile] [directory] [outputfile]

mkxfs -t ffs3 [option...]* [buildfile] [directory] [outputfile]

Runs on:

Linux, Mac, Microsoft Windows

Options:

-?
(QNX Neutrino 7.0 or later) Display some help information.
-c cache_dir
Cache compressed files in cache_dir.
-D
Treat undeclared intermediate directories as errors. If there's a target filesystem entry of /x/y, and /x has never occurred explicitly in the buildfile, the input directory, or as a child of a recursively included directory, then /x is considered an undeclared intermediate directory.
-d
Display warnings for undeclared intermediate directories.
-l inputline
(“el”) Process inputline before interpretation of the buildfile begins. Input lines given to mkefs should be quoted to prevent interpretation by the shell (as mkefs input lines often contain spaces). Multiple -l options are processed in the order specified. No default.
-n[n...]
Don't use timestamps in the files. Using the -n option permits identical images in binary format. Specifying additional -n options strips all time information from files.
-o directory
(“oh”) Specify a directory to be used for all permanent build artifacts, other than the output image itself.
-p patchfile
Apply patching instructions from this file (see Patch files,” below).
-r rootdir

This option doesn't immediately affect where mkefs searches for host files; it only adds standard search paths under rootdir to the MKIFS_PATH environment variable. Because this variable isn't used as the default value for the search attribute (unlike with mkifs), you must do the following to make mkefs behave like mkifs when searching for files:

  1. Add the line [search=${MKIFS_PATH}] near the beginning of your buildfile. For more information, see the search attribute and the MKIFS_PATH description.
  2. Set the PROCESSOR and PROCESSOR_BASE environment variables based on the target platform.

Then, when searching for files, mkefs will search the default paths used for storing binaries within the rootdir directory before searching the default paths within ${QNX_TARGET}.

You can define multiple -r options; each adds a set of paths to search for files. For an explanation of how multiple -r options are handled, see the mkifs -r option.

-t ffs3
Set the type of output filesystem. Currently, the only supported type is a version 3 flash filesystem image.
-v[v..]
Operate verbosely. Specifying additional -v options increases verbosity. Default is quiet operation.

Description:

The mkefs utility reads a text buildfile describing an embedded filesystem and produces a binary image file containing the embedded filesystem. You can copy this file to flash at a later stage, or use mkimage to combine it with an OS image before downloading.

Note: Don't confuse this command with mkifs, which builds an OS image filesystem, or mketfs, which builds an embedded transaction filesystem (ETFS).

You specify the input and output on the command line:

buildfile
The filename of the buildfile that describes the contents of the embedded filesystem; use - to specify standard input (the default).
directory
The root of a directory hierarchy to be appended to the file list specified in buildfile (if any). The default is no directory.
outputfile
The filename of the image file containing the embedded filesystem; use - to specify standard output (the default). Note that you can specify the outputfile only if you specified a buildfile.

If you don't specify either a buildfile or a directory, a buildfile is expected as input from standard input. The output is always an image file; if you don't specify outputfile, image-file data will be produced on standard output.

Note: QNX Neutrino flash filesystem version 3 no longer provides built-in decompression. The flash filesystem's decompression functionality has moved into the inflator resource manager. You should now use the deflate utility to compress files.

License checking

The mkefs utility checks for a valid QNX license key before performing any operation. If the license check fails, the utility stops running and displays a diagnostic message. A license check may fail if the license key is expired, missing, or not currently activated, or if the key doesn’t contain the permissions needed to run the utility.

Buildfiles

The buildfile uses the same grammar as the mkifs command, but supports different attributes.

The buildfile is basically just a list of files that you want to be included in the embedded filesystem image file when it's built by mkefs. As well as the files to be included, you can specify various attributes that are used to set parameters of the filesystem and the files in it. For example, you can specify the maximum size of the filesystem, or the user and group IDs of the individual files.

Note:

You can't use a backslash (\) to break long lines into smaller pieces.

You can use forward slashes (/) as directory delimiters in mkefs buildfiles, even on Windows. It is strongly recommended to do so, because backslashes may adversely affect the functionality of your buildfile.

In a buildfile, a pound sign (#) indicates a comment; anything between it and the end of the line is ignored. There must be a space between a buildfile command and the pound sign.

Each line is in the form:

[attributes] file_specification

where the attributes (with the enclosing square brackets) and the file specification are both optional.

You can use an attribute:

Attributes provide information about the file following the attribute. They're enclosed in square brackets; when combining attributes (e.g., to specify both the user ID and the group ID), enclose both attribute tokens in the same pair of square brackets. For example:

# correct way
[uid=5 gid=5] filename

# incorrect way
[uid=5] [gid=5] filename

There are two types of attributes:

boolean attributes
Those prefixed with a plus (“+”) or minus (“-”) sign.
value attributes
Those ending with an equals sign (“=”) followed by a value. Don't put any spaces around the equals sign.

A question mark (?) before an attribute makes the setting conditional. The attribute is set only if it hasn't already been set. For example, ?+bigendian sets the +bigendian attribute only if +bigendian or -bigendian hasn't been specified.

The file_specification that follows the attributes takes one of these forms:

path

The file is copied from the host to the location in the image defined by the prefix attribute. If path starts with a slash (“/”) on a Linux or Mac development host, or a disk volume label (i.e., drive letter and a colon) followed by a backslash (“\”) on a Windows host, the path is absolute and mkefs looks for the file at that exact host location. (On Windows, any path starting with a backslash but no disk label is absolute within the disk volume of the current directory (e.g., the C: drive) but not across all volumes. To make the path completely absolute, the disk label must be given.)

If path contains a slash or backslash character that's not at the start, the path is relative and mkefs tries to resolve it relative to the current working directory (CWD). If path does not contain a directory separator or the file could not be found relative to the CWD, mkefs tries to resolve it relative to all directories given in the search attribute, in succession.

target_path=host_path
The specified file or contents of the specified directory are fetched from the host filesystem and placed into the image at the specified target location. The search for the host_path file or directory contents proceeds in the same way as it does with the first file specification form, meaning it depends on whether the path is absolute or relative (see the previous paragraph for details).
target_path={contents}
An inline definition. The contents of the file are listed within the buildfile itself, enclosed in braces ({ }); the file doesn't exist on the host system anywhere. The contents of the inline file can't be on the same line as the opening or closing brace.
Note: The mkefs utility doesn't parse the contents of an inline file for anything but the closing brace. For example, mkefs doesn't interpret a pound sign (#) in an inline file as the beginning of a comment. The syntax of the inline file depends on what it's used for on the target system.

Closing braces (}) and backslashes (\) in an inline file must be escaped with a backslash.

You can enclose a filename in double quotes ("") if it includes spaces or unusual characters.

Attributes

The mkefs command supports the following attributes:

Note: An OR-bar indicates that either the first element or the second element must be present, but not both (e.g., +|- bigendian means either +bigendian or -bigendian, but not +-bigendian).

bigendian attribute (boolean)

+|-bigendian

Set the byte order for the embedded filesystem to either big (via +bigendian) or little (via -bigendian) endian. The default is little endian.

block_size attribute

block_size=bsize

Set the block size for the embedded filesystem. The block size depends on what memory devices you have in your target hardware and how they're arranged. For example, two interleaved 64 KB × 8-bit devices configured for a 16-bit interface have a block size of 128 KB. The default block size is 64 KB.

cd attribute

cd=pathname

Set the current working directory to the specified pathname before attempting to open the host file. Default is the directory from which mkefs was invoked.

You can specify variables in the attribute's value. For information on how they're expanded (i.e., evaluated to a value used in their place), see the mkxfs section on processing variables.

In the pathname, you can use forward slashes (/) as directory delimiters, even on Windows. It is strongly recommended to do so, because backslashes may adversely affect the functionality of your buildfile.

cksum attribute

cksum=number

Specify the expected checksum (as calculated by the cksum utility) of the file that the attribute applies to. If you specify this attribute, mkefs calculates the checksum of the host file imported into the image and compares it to the expected value; if a mismatch is detected, the program terminates with an error.

dperms attribute

dperms=dperms_spec
Set the access permissions of the directory. The dperms_spec can be one of the following:
  • a number (just as with the chmod command)
  • an asterisk (*) to use the host directory's permissions; for an inline directory, the permissions are 0755 (rwxr-xr-x)
  • a symbolic mode string to delete, add, or set permissions. This string is similar (but not identical) to chmod's and is as follows (with spaces added for clarity):

    [who] operator permissions[, ...]

    The components are as follows:
    who
    A combination of zero or more of the following:
    Character Meaning
    u User
    g Group
    o Others
    a All (the default if you don't specify who)
    operator
    One of the following:
    Character Meaning
    - Delete the specified permissions
    = Explicitly set the permissions
    + Add the specified permissions
    permissions
    A combination of one or more of the following:
    Character Meaning
    r Read permission
    w Write permission
    x Execute permission, or search permission for directories
    s When executed, set the user ID
    g When executed, set the group ID
    t Sticky bit

    You can include multiple symbolic mode strings, separating them with commas (,).

The default dperms_spec is *.

Note: When running on a Windows host, mkefs might guess at the permissions, so you should use the dperms attribute to specify them explicitly. You might also have to use the uid and gid attributes to set the ownership correctly.

drop attribute

drop=[pattern[|pattern]...]

(QNX Neutrino 7.1 or later) Specify patterns of file names that you want to ignore when recursively importing host directories. Each pattern is a simple filename wildcard pattern that can include the following meta-characters:

?
Match exactly one arbitrary character.
*
Match zero or more arbitrary characters.
\
Treat the next character literally.

For example:

[drop=*.sym] bin
[drop=*.a|*.dll] lib

Note the following:

Specifying the drop attribute without a pattern turns off exclusion in subsequent directories (unless you specify another drop attribute).

ecc_on attribute

ecc_on=value

Control error-correcting code (ECC) support:

Specify value as: To:
0 Disable ECC (the default)
1 Enable 64-byte alignment ECC
2 Enable 32-byte alignment ECC
Note: Don't mix ECC-enabled partitions and ECC-disabled partitions; the devf-* drivers don't support this.

The mkefs utility automatically handles the formatting alignment, but you have to use the -b option for flashctl to specify the appropriate alignment.

filter attribute

filter=filter_spec

Run the host file through the filter program specified, presenting the host file data as standard input to the program and using the standard output from the program as the data to be placed into the embedded filesystem. Default is no filter.

The most common filter you're likely to use with the embedded filesystem is deflate. This compresses the file before copying it to the embedded filesystem. For example:

[filter="deflate"]

You can specify a filter_spec of none. This is useful if you need to override a global filter specification.

[+|-followlink]

Whether to resolve any symbolic links and include the target files or directories instead of the links.

If you specify +followlink (enable the attribute), whenever an item taken from the host filesystem is a symbolic link, mkefs follows the link and includes its target. If you omit the attribute, this is the default behavior.

If you specify -followlink (disable it):

gid attribute

gid=id_spec

Set the group ID number for the file. The value of this attribute may be either a number or an asterisk (*). If it's an asterisk, the group ID is taken from the host file; for an inline file, the group ID is the group of the user running mkefs. The default value for this attribute is *.

include attribute (boolean)

+|-include

(QNX Neutrino 7.1 or later) Include files as part of the buildfile being processed. You can apply this attribute to a single file:

[+include] buildfile_path

or as a global attribute:

[+include]
buildfile_path_1
buildfile_path_2
...
buildfile_path_n
[-include]

You can specify variables in the attribute's value. For information on how they're expanded (i.e., evaluated to a value used in their place), see the mkxfs section on processing variables.

Each buildfile_path can be an absolute or a relative path. If buildfile_path starts with a slash (“/”) on a Linux or Mac development host, or a disk volume label followed by a backslash (“\”) on a Windows host, it's absolute and mkefs searches for the file in that exact host location. For more details on specifying absolute paths, see the buildfile path description above. If the path starts with another character sequence, it's a relative path, and mkefs searches the following directories (in this order):

Note that you can't use the target=host notation for the paths.

If an include file can't be found, the result depends on the optional attribute. If +optional is set, the missing file is skipped; otherwise, mkefs terminates with an error.

Buildfiles are processed top-down, and buildfile inclusion happens in place: when an include attribute is found, the included buildfile is loaded and processed; when processing is completed, mkefs returns to the including buildfile.

You can nest buildfile inclusions, but any circular inclusion is treated as an error. For example, the inclusion hierarchy A(B(D),C(E,F)) is valid, but A(A) and A(B(C(B))) aren't. If you include a buildfile more than once (which could easily happen with nested include files), the repeated inclusion is ignored, and mkefs issues a diagnostic message.

Note: The top buildfile together with its included buildfiles effectively form one large “buildfile stream” that's processed as a single buildfile would be. This means that all attribute settings in effect before an inclusion remain in effect inside the included files, and everything set in an included file is carried over into the parent buildfile.

The default is -include, which causes files (if found) to be added to the filesystem, not to the buildfile.

max_size attribute

max_size=size

Set the maximum size of the embedded filesystem. You can set this attribute if you don't want the filesystem to exceed a maximum size. If this occurs while mkefs is building the filesystem, you'll see a warning message. The default is 4 GB.

min_size attribute

min_size=size

Set the minimum size of the embedded filesystem. If the size of the filesystem is less than this size after all the specified files have been added, then the filesystem is padded to the required size. If you don't specify this attribute, no padding occurs.

mount attribute

mount=mountpoint

Specify the mountpoint for the embedded filesystem. You can override the mountpoint with the -n option to the flashctl command.

You can specify variables in the attribute's value. For information on how they're expanded (i.e., evaluated to a value used in their place), see the mkxfs section on processing variables.

In the mountpoint, you can use forward slashes (/) as directory delimiters, even on Windows. It is strongly recommended to do so, because backslashes may adversely affect the functionality of your buildfile.

The default mountpoint is "", which makes the flash filesystem drivers (devf-*) use the appropriate default, usually /fs1p1.

mountperms attribute

mountperms=perms_spec

Set the access permissions for mountpoints. The perms_spec can be one of the following:

The default perms_spec is “0777”.

mtime attribute

mtime=time_spec

Set the timestamps of the files or directories to the specified time. The time_spec must be either:

Timestamps specified with the mtime attribute aren't affected by the -n option.

optional attribute (boolean)

+|-optional

If this attribute is enabled and the host file can't be found, output a warning and continue building the embedded filesystem. If it's disabled and the host file can't be found, output an error message and exit. The default setting is enabled.

This attribute applies only to those items explicitly included in the buildfile.

Note: If you specify [+optional] and [+followlink] (or don't specify one or both of them and use their default setting) and a broken symbolic link is implicitly included from a directory, mkefs returns an error and exits. This is because when followlink is enabled, symbolic links should never be imported into the image.

perms attribute

perms=perms_spec

Set the access permissions of the file. The perms_spec can be one of the following:

The default perms_spec is *.

Note: When running on a Windows host, mkefs can't get the setuid (“set user ID”) or setgid (“set group ID”) permissions from the file, and it might guess at the read, write, and execute permissions, so you should use the perms attribute to specify the permissions explicitly. You might also have to use the uid and gid attributes to set the ownership correctly. To determine whether or not a utility needs to have the setuid or setgid permission set, see its entry in the Utilities Reference.

prefix attribute

prefix=prefix_spec

Set the prefix on the target file names. The default is the empty string.

You can specify variables in the attribute's value. For information on how they're expanded (i.e., evaluated to a value used in their place), see the mkxfs section on processing variables.

In the prefix path, you can use forward slashes (/) as directory delimiters, even on Windows. It is strongly recommended to do so, because backslashes may adversely affect the functionality of your buildfile.

search=path:path:…

This attribute specifies that mkefs should search for the file in the named path locations on the host system. The search directory portion of the host file name isn't included in the name that's stored in the image filesystem. The default setting is empty, meaning only the current working directory will be searched for the host files. To make mkefs include the directories named in the MKIFS_PATH variable in the host locations that it searches, see the -r rootdir explanation above.

You can specify variables in the attribute's value. For information on how they're expanded (i.e., evaluated to a value used in their place), see the mkxfs section on processing variables.

Note:

To ensure that your search paths work without modification on all supported host OSs, you can use:

  • forward slashes (“/”), which are now recognized by Windows as well as Linux and macOS; it is strongly recommended to use forward slashes as directory delimiters, because backslashes may adversely affect the functionality of your buildfile
  • the PFS environment variable instead of “;” or “:” to separate multiple paths in path lists (see PFS under “Environment variables:” below)

sha256 attribute

sha256=hex_string

Specify the expected SHA256 hash of the file that the attribute applies to. If you specify this attribute, mkefs calculates the SHA256 hash of the host file imported into the image and compares it to the expected value; if a mismatch is detected, the program terminates with an error. You must specify the expected hash as a string of 64 hexadecimal digits, without a prefix or any delimiters. For example, instead of specifying 0xaa,0xbb,0xcc,..., specify aabbcc....

spare_blocks attribute

spare_blocks=sblocks

Set the number of spare blocks to be used by the embedded filesystem. If you want the embedded filesystem to be able to reclaim the space taken up by deleted files, set the number of spare blocks to 1 or more. The default is 1.

type attribute

type=file_type

Sets the type of the files being created in the embedded filesystem. Allowable types are:

Note: Specifying [type=dir] tells mkefs to make the named file a directory; you don't need to specify the type when you're copying the contents of a directory. For example, this command:
[type=dir]/usr/bin=/usr/nto/x86_64/bin

creates an empty directory named /usr/bin, with the same owner and permissions as for the host directory. To recursively copy /usr/nto/x86_64/bin to /usr/bin, you just need to specify:

/usr/bin=/usr/nto/x86_64/bin

uid attribute

uid=id_spec

Set the user ID number for the file. The value of this attribute may be either a number or an asterisk (*). If it's an asterisk, the user ID is taken from the host file; for an inline file, the user ID is the user running mkefs. The default value for this attribute is *.

Patch files

Patch files let you override the user ID, group ID, and permissions of certain files, depending on their location and filename pattern. Patches are applied after all files have been collected (from the buildfile and/or the specified directory). Consequently, patch files can override settings specified in the buildfile.

Patch files must contain only lines of the form:

#comment

or:

type:path:pattern:uid:gid:perms

In comment lines, # must be the very first character. The entire line is regarded as a comment and is ignored.

The type is either d or f, optionally followed by r. Type d patches are applied only to directories, and type f patches are applied only to files. An r indicates that the patch should be applied recursively within path; without r, the patch is applied to path only.

The pattern is a filename pattern that specifies which files to apply the patch to. The uid and gid must be decimal numbers, while perms must be an octal number (see chmod). Note that it isn't possible to set only the user ID, group ID, or permissions; for each match, all three are affected.

Examples:

Here's a sample buildfile, my_efs.bld:

# A sample buildfile for mkefs

[block_size=128k spare_blocks=1]
/home/jwall/nto_flash

In this example, we've specified a block size of 128 KB and one spare block. The files and subdirectories from the /home/jwall/nto_flash directory on the host system are to be recursively copied into the root directory of the embedded filesystem.

To create an embedded filesystem image file using the above buildfile, invoke mkefs as follows:

mkefs my_efs.bld my_image.efs

This creates the my_image.efs file containing the embedded filesystem, which can then be copied to the target system.

Environment variables:

PFS
Specifies the Path Field Separator (PFS). The mkefs utility automatically sets this variable to the character used to separate paths in path lists. That is, mkefs sets the variable to “;” on a Windows host and to “:” on a Linux or macOS host.

To keep buildfiles host OS-independent, use this environment variable instead of the OS-specific characters; for example, instead of writing:

[search=/a/b:/x/y/z]

write:

[search=/a/b${PFS}/x/y/z]

The mkefs utility will set the environment variable to the path separator appropriate for the host platform.

Exit status:

0
Successful completion.
1
An error occurred.