mkqnx6fsimg

Updated: May 06, 2022

Build a Power-Safe filesystem image (QNX)

Syntax:

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

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

Runs on:

Linux, Mac, Microsoft Windows

Options:

-?
(QNX Neutrino 7.0 or later) Display some help information.
-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 patch file, 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.
-f path
Fill the specified text file with a list of all files in the output image, including a hash of the file contents, and data similiar to that returned by the ls -l command. The file is truncated if it already exists. Each line has the form:
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.

-h
(QNX Neutrino 7.0 or later) Import hard links from the host filesystem as hard links. The default behavior is to create copies of the linked files.
-l inputline
(“el”) Process inputline before interpreting the buildfile. Input lines given to mkqnx6fsimg should be quoted to prevent interpretation by the shell. Multiple -l options are processed in the order specified. This option is especially useful for setting global attributes when the input is a directory only.
-n[n..]
Don't use timestamps in the files. Using the -n option permits identical images in binary format. One n strips timestamps from files that vary from run to run. More than one strips ALL time information, which is necessary on Windows NTFS with daylight saving time.
-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 mkqnx6fsimg 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 mkqnx6fsimg 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, mkqnx6fsimg 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.

-v[v..]
Operate verbosely. Specifying additional v options increases the verbosity. The default is quiet operation.

Description:

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.

Note: Don't confuse this command with mkqnx6fs, which initializes an empty Power-Safe filesystem and is available for Neutrino hosts only.
You specify the input and output on the command line:
buildfile
The filename of the buildfile that describes the properties and contents of the Power-Safe filesystem; use a hyphen (-) 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 Power-Safe filesystem; use a hyphen (-) to specify standard output (the default). Note that you can specify the output file only if you specified at least either a buildfile or a directory.

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: A Power-Safe filesystem must always be exactly the same size as the partition (or unpartitioned medium) it resides on. If it differs in size, then it will be reported as being corrupted. Be also aware that many [pseudo] hard-disk drives report a virtual geometry of 255 heads and 63 sectors per track, providing the maximum of 16065 sectors per cylinder. Since partitions are always defined in units of entire cylinders, any Power-Safe filesystem image intended to be put onto a [pseudo] hard-disk should have a sector count that's a multiple of the reported number of sectors per cylinder.

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.

Buildfiles

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.

Note:

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

You can use forward slashes (/) as directory delimiters in mkqnx6fsimg 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 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:

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 mkqnx6fsimg 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 mkqnx6fsimg 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, mkqnx6fsimg 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 mkqnx6fsimg utility doesn't parse the contents of an inline file for anything but the closing brace. For example, mkqnx6fsimg 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.

For information on the owner and permissions assigned to the resulting target file, see the explanation about inline files permissions in the Building Embedded Systems guide.

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

Attributes

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

acl attribute

acl=acl_spec
Set the access control list for the file, directory, or symbolic link. An ACL specification consists of an arbitrary number of entries, separated by commas (,). Each entry has the following form:

tag:opt_qualifier:permset

The components are as follows:

tag
One of u (user), g (group), or o (other).
opt_qualifier
Either empty or a decimal numeric user ID or group ID if tag was uor g.
permset
The set of permissions granted. Valid characters are r (read), w (write), x (execute), and - (a fill character that doesn't affect permissions). The r, w, and x characters can appear in any order, but at most once each.

This is fairly similar to the “short text” form of ACLs in other implementations of IEEE 1003.1e draft 17 ACLs, with a few exceptions:

Note: This attribute interacts with any perms and dperms attribute that you specified for the file or directory. Any basic permission (u::*, g::*, o::*) that isn't specified in the ACL is taken from the perms or dperms specification (the =permission bits in st_mode). Any basic permission given in the acl attribute overwrites the corresponding bits in the item’s st_mode. If the attribute specifies only basic permissions, it's discarded after these permissions have been applied to the item’s st_mode.

For more information about ACLs, see Access Control Lists in the “Working with Files” chapter of the QNX Neutrino User's Guide.

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

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

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.

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

Note: If you explicitly specify an mtime attribute for the boot image with dflt_boot set, mkqnx6fsimg might ignore the mtime attribute.

dom attribute

dom=ref
Assign a file, directory, or symlink to a static encryption domain. The ref argument must have the form:

nr | *

where nr must be either 0 or the number of a static domain previously defined using the newdom attribute. The special value 0 means no encryption; this is the default. The value “*” means the encryption domain is inherited from the parent directory.

dperms attribute

dperms=dperms_spec

Set the access permissions of the directory. The dperms_spec can be one of the following:

The default dperms_spec is *.

Note: When running on a Windows host, mkqnx6fsimg 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).

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]

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, mkqnx6fsimg follows the link and includes its target. If you omit the attribute, this is the default behavior.

If you specify -followlink (disable it):

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

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 mkqnx6fsimg 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 mkqnx6fsimg 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, mkqnx6fsimg 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, mkqnx6fsimg 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 mkqnx6fsimg 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_sectors attribute

max_sectors=count

Set the maximum size of the storage medium, in sectors, that this filesystem supports. This attribute allows you to use the output filesystem image on media that are larger than what num_sectors specifies, either now or later in its lifetime.

The count argument is a decimal, octal, or hexadecimal integer, optionally followed by K, M, or G (the case doesn't matter).

If you specify this attribute, mkqnx6fsimg creates an expandable filesystem. In this case, mkqnx6fsimg rounds up the specified maximum number of sectors to yield the maximum capacity. This capacity is the maximum number of sectors that the filesystem can support, which may be larger than what's specified by max_sectors. For information on expanding a filesystem to fit the partition it is installed on, see the chkqnx6fs -x option.

Also, mkqnx6fsimg calculates the bitmap file size based on the max_sectors setting. For information on the bitmap file, see the Power-Safe filesystem chapter in the QNX Neutrino System Architecture Guide.

Note: It's possible to boot from an expandable filesystem that doesn't entirely fill the device partition that hosts it. You can create a minimally sized but expandable filesystem image and transfer it to the target, and the image will expand to fill the partition upon first boot.

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:

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

name_enc attribute

+|-name_enc

Specify whether the file's name should be encrypted. If this attribute is set (+name_enc) for any file, then a filename encryption domain must have been specified using the namedom attribute (see below). The default is unset (-name_enc), meaning the name is unencrypted.

namedom attribute

namedom=nr

Specify which static domain should be used for name encryption. This attribute can be specified at most once per filesystem, and must be provided to use filename encryption (see name_enc).

The given nr must be the non-zero number of a static domain defined anywhere in the build file using the newdom attribute (see below). The default is no filename encryption.

newdom attribute

newdom=nr,key[,type[,hmac]]

Define a new static domain to be created. Here, nr is the domain number, key is the key used to lock/unlock the domain, type describes the cipher to use for encryption, and hmac defines a digest type to use for authentication.

The fields in the argument have these semantics:
Domain number
The domain number must be an integer in the range of 1..122. Each domain number may be defined (using newdom) at most once. Static domains must be defined before they are referenced by any dom attributes.
Key
The key (which is later used to unlock the domain) can be provided in different ways. The type of key is identified by the first character of the key string (which is the first of possibly multiple special characters):
  • .salt.str — a 64-bit salt value expressed as a string of up to 16 hexadecimal digits, followed by a period and a plain-text string
  • +str — a plain-text password, to be hashed into a key
  • #str — a base-64-encoded raw key. The length of the provided string must be a multiple of 4 characters.
  • @file — the name of a file that contains raw binary key data
If the provided key data is shorter than the key size for the specified encryption type (see below), then the key is padded with zeroes.
Type
A numeric or symbolic representation of the encryption type to use. The following types are currently supported:
Symbolic name Numeric value Key length (bytes)
none 0 0
xts 1 64
cbc 2 32

The default value is xts.

HMAC
A numeric or symbolic representation of the hash type to use for authentication. The following types are currently supported:
Symbolic name Numeric value
none 0
sha256 1

The default value is sha256.

num_blocks attribute

num_blocks=count

For a Power-Safe filesystem, you must use the following formula to determine the maximum number of blocks:

If blksize is less than or equals 4096:
((num_bytes - 16384) rounded down to a multiple of 4096) / blksize
If blksize is greater than 4096:
((num_bytes - (12288 + abs(blksize - 12288) + blksize) rounded down to a multiple of 4096) / blksize
where 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 (inodes) 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.

If the number of inodes is not specified, mkqnx6fsimg uses one of the following methods to calculate the number of inodes:
  • If num_sectors or num_blocks specify an absolute value, the inode count is calculated using a heuristically determined blocks/file ratio. This is the same algorithm mkqnx6fs uses.
  • If num_sectors was set to let mkqnx6fsimg automatically determine the required size of the filesystem, then the program adds spare inodes in the same ratio as it applied spare sectors.

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%

The number of inodes determines the inodes file size. For information on the inodes file, see the Power-Safe filesystem chapter in the QNX Neutrino System Architecture Guide.

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

Note: A Power-Safe filesystem must always be exactly the same size as the partition (or unpartioned medium) that it resides on. If it differs in size, it is reported as corrupted. In addition, be aware that many [pseudo] hard-disk drives report a virtual geometry of 255 heads and 63 sectors per track, which provides a maximum of 16065 sectors per cylinder. Because partitions are always defined in units of entire sectors, if you want to put a Power-Safe filesystem image onto a [pseudo] hard-disk, ensure that the filesystem has a sector count that is a multiple of 16065.
Note: For an x86-based target, a Power-Safe filesystem won't initially boot when it's transferred to a partition on physical media. Ensure that you mount the Power-Safe filesystem at least one time to put the superblocks in the correct state for it to boot.

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, mkqnx6fsimg 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, hard link, or symbolic link. The perms_spec can be one of the following:

The default perms_spec is *.

Note: When running on Windows, mkqnx6fsimg 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 set the permissions. You might also have to use the uid and gid attributes to set the ownership correctly. To learn whether a utility needs to have the setuid or setgid permission set, see its entry in the Utilities Reference.

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.

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.

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=path[:path...]

This attribute specifies that mkqnx6fsimg 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 Power-Safe filesystem. The default setting is empty, meaning only the current working directory will be searched for the host files. To make mkqnx6fsimg 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)

sector_size attribute

sector_size=size_spec

Specify the sector size of the filesystem's target device. The size_spec argument is an integer. Valid values are 512 and 4096 (or 4k or 4K); 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:

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

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-XXXX-XXXXXXXXXXXX, 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

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

Environment variables:

PFS
Specifies the Path Field Separator (PFS). The mkqnx6fsimg utility automatically sets this variable to the character used to separate paths in path lists. That is, mkqnx6fsimg 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 mkqnx6fsimg utility will set the environment variable to the path separator appropriate for the host platform.

Exit status:

0
Successful completion.
1
An error occurred.