Build a Power-Safe filesystem image (QNX)
mkqnx6fsimg [option...] [buildfile] [directory] [outputfile] mkxfs -t qnx6fsimg [option...] [buildfile] [directory] [outputfile]
Linux, Mac, Microsoft Windows
target-path uid:gid mode_in_octal size [SHA256]
You can express the mode_in_octal as a 6-digit octal number; see the st_mode member in the stat structure.
The mkqnx6fsimg utility reads a text buildfile and/or a specified directory and produces a binary image file containing a Power-Safe (fs-qnx6.so) filesystem created from the given input. You can copy this file to target media at a later stage.
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 mkqnx6fsimg 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 mkqnx6fsimg command uses the same buildfile grammar as mkifs, but supports a different set of attributes. The buildfile is basically just a list of files that you want to be included in the Power-Safe image file when it's built by mkqnx6fsimg. As well as identifying 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 are 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:
?+bigendiansets 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.
In mkqnx6fsimg buildfiles, the following attributes are supported:
The following attributes are recognized, but not semantically supported by mkqnx6fsimg:
Although default values are defined to generate a 256 MB image, you should explicitly specify at least the image size, preferably by specifying at least num_sectors, to ensure that the image produced is fully compatible with your specific target device.
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).
alimit attribute (boolean)
+|-alimit
Set the allocation limit extended mode bit (QNX6FS_EMODE_ALIMIT) for files that the attribute applies to. When this bit is set, operations fail with ENOSPC if they attempt to grow the file to a size that would cause the mounted volume's free space to drop below its allocation limit value. (For information on setting the allocation limit, see the alimit option for fs-qnx6.so .) The default is QNX6FS_EMODE_ALIMIT is not set.
If the file you set the allocation limit extended mode bit for is a directory, any new files created within that directory inherit the set bit.
bigendian attribute (boolean)
+|-bigendian
Set the byte order for the Power-Safe filesystem to either big (via +bigendian) or little (via -bigendian) endian. The default is host's native endian-ness.
blksize attribute
blksize=size_spec
Set the block size for the Power-Safe filesystem. The block size determines the minimum allocatable amount in the filesystem. You can specify any power-of-two block size from 512 to 32768 bytes. The size_spec argument is an integer, optionally followed by K (the case doesn't matter). The default value is 4096 bytes.
boot_cls attribute (boolean)
+|-boot_cls
Clear (+) or don't clear (-) the screen while booting. The default is not to clear.
boot_quiet attribute (boolean)
+|-boot_quiet
If set, instructs the boot loader to silently boot the latest boot image, without presenting a boot-image selection menu. The default is not to boot quietly.
cd attribute
cd=path
Set the current working directory to the specified pathname before attempting to open the host file. The default is the directory from which you invoked mkqnx6fsimg.
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, mkqnx6fsimg 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.
dflt_boot attribute (boolean)
+|-dflt_boot
Specify the boot image to use by default at system startup. You can set this to true on at most one file in the image. That file must be a regular file and reside in /.boot/ in the target filesystem.
Since the boot loader chooses the .boot entry with the most recent st_mtime as the default boot image, this flag may affect the modification time of the file it was set on. The file's st_mtime is modified, if necessary, such that it's one more than the maximum of all modification times in .boot.
dperms attribute
dperms=dperms_spec
Set the access permissions of the directory. The dperms_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 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 Power-Safe filesystem. Default is no filter. 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 the attribute, whenever an item taken from the host filesystem is a symbolic link, mkqnx6fsimg follows the link and includes its target.
If you specify -followlink:
fsys_lfncks attribute (boolean)
+|-fsys_lfncks
This attribute determines whether checksums are calculated for long filenames in the Power-Safe filesystem. The default is true.
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 mkqnx6fsimg. The default value for this attribute is *.
mountperms attribute
This attribute is supposed to set the access permissions for the filesystem mountpoint. Since the Power-Safe filesystem has no provision to store mount information, this attribute is silently disregarded.
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.
num_blocks attribute
num_blocks=count
For a Power-Safe filesystem, you must use the following formula to determine the maximum number of blocks:
((num_bytes - 16384) rounded down to a multiple of 4096) / blksizeIf blksize is greater than 4096:
((num_bytes - (12288 + abs(blksize - 12288) + blksize) rounded down to a multiple of 4096) / blksizewhere num_bytes equals num_sectors * sector_size.
The count argument is an integer, optionally followed by K, M, or G (the case doesn't matter). The default is 65532, which is the block count resulting from the above formula for the default number of sectors, using the default sector size and block size.
num_groups attribute
num_groups=count
Set the number of allocation groups in the Power-Safe filesystem. Valid values are in the range 1–64. QNX recommends that you do not set this attribute and instead let mkqnx6fsimg calculate a reasonable number of allocation groups. When mkqnx6fsimg calculates the value, it selects one in the range 4–64.
num_inodes attribute
num_inodes=count
Set the number of file metadata entries in the filesystem. One individual inode is required for each file, directory, or symbolic link. This means that the inode count ultimately limits the number of files in the filesystem. You specify count using the following format:
absolute_value | *spare[%]
where absolute_value and spare are integers, optionally followed by k, M, or G.
If absolute_value is specified, it specifies the exact number of inodes in the resulting filesystem.
If the alternative value (indicated by a leading *) is used, mkqnx6fsimg automatically determines the required number of inodes and adds spare additional inodes to the result. If spare is followed by %, then mkqnx6fsimg adds spare percent of the required inode count.
For example, if a buildfile specifies a total of 1000 items (files, directories, and so on), then the total number of required inodes is 1002 (including / and /.boot). The following buildfile entry creates a filesystem with 1012 inodes (1002 + 10):
num_inodes=*10
Alternatively, the following entry creates a filesystem with 1102 inodes (1002 + 1002*10%):
num_inodes=*10%
num_sectors attribute
num_sectors=count
Set the total number of sectors occupied by your image. This is the best way to ensure that your image will fit a specific target device.
You specify count using the following format:
absolute_value[:multiple_of] | *spare[%][:multiple_of]
where absolute_value, spare, and multiple_of are integers, optionally followed by k, M, or G.
If absolute_value is specified, it specifies the exact number of sectors in the resulting image.
If the alternative value (indicated by a leading *), is used, then mkqnx6fsimg automatically determines the number of sectors required and adds spare extra sectors to the result. If spare is followed by %, then mkqnx6fsimg adds spare percent of the required sector count.
If multiple_of is specified, mkqnx6fsimg rounds up the number of sectors to the next multiple of multiple_of that is an integer. This option allows you to align image sizes to disk cylinder sizes.
The default num_sectors value is 524288 (512k).
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 mkqnx6fsimg. The default is true.
perms attribute
perms=perms_spec
Set the access permissions of the file, hard link, or symbolic link. 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=path
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.
reserve attribute
reserve=number
Set the percentage of filesystem blocks to reserve for reclaim, as an integer in the range [0, 99]. The default value is 3.
search attribute
search=path[:path...]
This attribute specifies that mkqnx6fsimg 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 Power-Safe filesystem. Colon separators and forward slashes in the paths are the standard Unix conventions, but for Windows searches, you must use the standard Windows conventions, such as semicolon separators and backslashes in the paths.
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.
sector_size attribute
sector_size=size_spec
Specify the sector size of the filesystem's target device. The size_spec argument is an integer, optionally followed by K, M, or G (the case doesn't matter). Valid values are 512 and 4096; the default is 512.
sha256 attribute
sha256=hex_string
Specify the expected SHA256 hash of the file that the attribute applies to. If you specify this attribute, mkqnx6fsimg 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....
type attribute
type=file_type
Sets the type of the files being created in the Power-Safe filesystem. Allowable types are:
[type=dir]/usr/bin=/usr/nto/x86/bincreates 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
You must always specify hard links using commands of the form:
[type=hlink] link-path=target-path
where link-path is the new link to create and target-path is an existing path in the Power-Safe filesystem being created. You can't specify attributes such as uid, gid, or permissions for hard links. If you define any of these attributes together with the [type=hlink] attribute, they're silently ignored.
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 mkqnx6fsimg. The default value for this attribute is *.
usage attribute
usage=usage
Give a hint about the expected predominant usage of the Power-Safe filesystem. This hint will affect default values chosen for blksize, num_blocks, num_groups, and num_inodes. Valid values are:
There is no default.
uuid attribute
uuid=uuid
Use this attribute to provide an explicit universally-unique identifier (UUID) for the Power-Safe filesystem. The UUID string must be in the form XXXXXXXX-XXXX-XXXX-XXXXXXXX, where X is a hexadecimal digit. The default is to use an IPv4/random-number-based UUID. Note that when you set the UUID, you must not provide a volume name.
vol_name attribute
vol_name=string
Set the volume name to the given string. The maximum volume label length is 16 characters. Note that when you specify a volume name, you must not provide a UUID. The default is to use the UUID.
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_qnx6fs.bld:
# A sample buildfile for mkqnx6fsimg [num_sectors=256k] /home/thaupt
In this example, we've specified a sector count of 256k (i.e., 256*1024). With the default sector size of 512 bytes, this results in an image size of 128 MB. The files and subdirectories from the /home/thaupt directory on the host system are to be recursively copied into the root directory of the Power-Safe filesystem. To create a Power-Safe filesystem image file using above buildfile, invoke mkqnx6fsimg as follows:
mkqnx6fsimg my_qnx6fs.bld my_qnx6fs.img
This creates the my_qnx6fs.img file containing the Power-Safe filesystem, which you could then copy to a target system's hard-disk partition as follows:
dd if=my_qnx6fs.img of=/dev/hd0t179 count=262144