`mkefs`

Build an embedded filesystem (QNX)

Syntax:

mkefs -t ffs2 | ffs3 [-l inputline] [-nv] [buildfile [outputfile]]

Options:

-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: 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.
-t ffs2 | -t ffs3: Set the type of output file system. Use -t ffs2 to make a version 2 flash filesystem image. Use -t ffs3 to make a version 3 flash filesystem image. The default is ffs3.
-v: Operate verbosely. Specifying additional -v options increases verbosity. Default is quiet operation.

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.

Don't confuse this command with mkifs, which builds an OS image filesystem.

The input and output files are specified 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).
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.

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.

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.

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

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.

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 already been set.

The file_specification takes one of the following forms:

path

The path is the same on the host as in the image.

target_path=host_path

The specified file or contents of the specified directory are fetched from the host filesystem and placed into the image.

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.

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:

+|-bigendian
block_size=bsize
cd=filename
dperms=dperm_spec
filter=filter_spec
+|-followlink
gid=id_spec
max_size=msize
min_size=tsize
mount=filename
+|-optional
perms=perm_spec
prefix=prefix_spec
search=path:path...
spare_blocks=sblocks
type=file_type
uid=id_spec

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 64K * 8-bit devices configured for a 16-bit interface have a block size of 128K bytes. The default block size is 64K bytes.

`cd` attribute

cd=filename

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.

`dperms` attribute

dperms=dperms_spec

Set the access permissions of the directory. If specified as a number, the permissions are set to that number (just like the chmod command). If specified as an asterisk ("*"), the host directory's permissions are used; for an inline directory, the permissions are obtained from the umask of the user running mkefs. Otherwise, a symbolic mode string (which is a subset of chmod's) is used to delete, add, or set permissions.

The symbolic mode string consists of:

a combination of u, g, o, and a
one of -, =, or +
a combination of r, w, x, s, g, and t.

You can include more than one symbolic mode string, separating them with a comma (,).

The default dperms_spec is "*".

`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"]

`followlink` attribute (boolean)

[+|-followlink]target_path=host_path

If you specify +followlink or omit it, mkefs follows any links and makes target_path a copy of host_path.

If you specify -followlink, mkefs creates a link called target_path that points to whatever host_path points at. It's up to you to make sure that the file pointed to is placed in the image.

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

`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 4G bytes.

`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. The default is unspecified, meaning that no padding occurs.

`mount` attribute

mount=filename

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

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

`optional` attribute (boolean)

+|-optional

If true, and the host file can't be found, output a warning and continue building the embedded filesystem. If false, and the host file can't be found, output an error message and exit mkefs. The default is false.

`perms` attribute

perms=perms_spec

Set the access permissions of the file. If specified as a number, the permissions are set to that number (just like the chmod command). If specified as an asterisk ("*"), the host file's permissions are used; for an inline file, the permissions are obtained from the umask of the user running mkefs. Otherwise, a symbolic mode string (which is a subset of chmod's) is used to delete, add, or set permissions.

The symbolic mode string consists of:

a combination of u, g, o, and a
one of -, =, or +
a combination of r, w, x, s, g, and t.

You can include more than one symbolic mode string, separating them with a comma (,).

The default perms_spec is "*".

`prefix` attribute

prefix=prefix_spec

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

`search` attribute

search=path:path:...

This attribute specifies that mkefs should search for the file in the named 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 file system.

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

link -- a symbolic link
file -- a regular, everyday file (the default)
dir -- a directory.

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

marks all the contents of /usr/bin as directories. To copy /usr/nto/x86/bin to /usr/bin, you just need to specify:

/usr/bin=/usr/nto/x86/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 "*".

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

Exit status:

0: Successful completion.
1: An error occurred.