Build an embedded filesystem (QNX)
mkefs [-?Ddhnv] [-c cache_dir] [-l inputline] [-o directory]
[-p patch_file] [-t ffs3] [buildfile] [directory] [outputfile]
Linux, Mac, Microsoft Windows
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.
You specify the input and output on the command line:
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.
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.
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.
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:
[attribute] A B C
[attribute] A B C
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:
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 takes one of the following forms:
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.
The mkefs command supports the following attributes:
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=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.
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.
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
[who] operator permissions[, ...]
| Character | Meaning |
|---|---|
| u | User |
| g | Group |
| o | Others |
| a | All (the default if you don't specify who) |
| Character | Meaning |
|---|---|
| - | Delete the specified permissions |
| = | Explicitly set the permissions |
| + | Add the specified permissions |
| 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 *.
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 |
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 attribute (boolean)
[+|-followlink]target_path=host_path
Whether to resolve any symbolic links and include the target files or directories instead of the links.
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.
If you specify +followlink or omit it, whenever an item taken from the host filesystem is a symbolic link, mkefs resolves the link and includes its target file or directory.
If you specify -followlink, then:
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 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=filename
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.
The default 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:
[who] operator permissions[, ...]
| Character | Meaning |
|---|---|
| u | User |
| g | Group |
| o | Others |
| a | All (the default if you don't specify who) |
| Character | Meaning |
|---|---|
| - | Delete the specified permissions |
| = | Explicitly set the permissions |
| + | Add the specified permissions |
| 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 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:
or:
YYYY-MM-DD-HH:MM:SS
You must provide all six elements. The time is always interpreted as UTC.
Timestamps specified with the mtime attribute aren't affected by the -n option.
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 true.
perms attribute
perms=perms_spec
Set the access permissions of the file. The perms_spec can be one of the following:
[who] operator permissions[, ...]
| Character | Meaning |
|---|---|
| u | User |
| g | Group |
| o | Others |
| a | All (the default if you don't specify who) |
| Character | Meaning |
|---|---|
| - | Delete the specified permissions |
| = | Explicitly set the permissions |
| + | Add the specified permissions |
| 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 perms_spec is *.
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.
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.
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.
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:
[type=dir]/usr/bin=/usr/nto/x86/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/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 *.
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.
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.