mkqnx6fsimg

Build a Power-Safe filesystem image (QNX)

Syntax:

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

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

Runs on:

Linux, Microsoft Windows

Options:

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

-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 root
Search the default paths in this directory before the default.
-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 an integer multiple of the reported number of sectors per cylinder. This requirement is relaxed for resizable images; see the alloc_bnd=size_spec attribute.

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.

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

The file_specification takes one of the following forms:

path
The file is copied from the host to the location in the image defined by the prefix attribute. If path isn't absolute, mkqnx6fsimg looks for it in the locations identified by the search attribute.
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.
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.

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

alloc_bnd attribute

alloc_bnd=size_spec

Specify an allocation boundary for the Power-Safe filesystem, indicating that a resizable image is to be generated. When you use the alloc_bnd attribute, mkqnx6fsimg creates a filesystem image as would be output by dprepresize. This image isn't a valid Power-Safe filesystem, but can later be resized with the dresize utility to fit potentially smaller media than specified at creation time. This attribute defines the allocation boundary; it ensures that in the generated image, no more than size_spec blocks will be used. The size_spec is an integer, optionally followed by K, M, or G (the case doesn't matter). The default value is 0, which means "create a regular filesystem image."

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 and must be an integer multiple of the sector size. Valid values for the block size are 512, 1024, 2048, and 4096. size_spec is an integer, optionally followed by K, M, or G (the case doesn't matter). The default value is 1024.

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.

dperms attribute

dperms=perm_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 you specify the permissions as an asterisk (*), the host directory's permissions are used; for an inline directory, the permissions are 0755 (rwxr-xr-x). 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:

  1. a combination of u, g, o, and a
  2. one of -, =, or +
  3. 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 *.

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.

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]target_path=host_path

If you specify +followlink or omit it, then whenever an item x is taken from the host filesystem and x is a symbolic link, mkqnx6fsimg resolves the symbolic link and includes its target file or directory.

If you specify -followlink, then:

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:

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

num_blocks attribute

num_blocks=size_spec

Set the number of blocks in the Power-Safe filesystem. If you don't specify the number of blocks, then it's calculated from the number of sectors. If you have both the sector and the blocks count specified explicitly in the buildfile, be aware that the maximum number of blocks that a Power-Safe filesystem can have is:

( ( num_sectors * sector_size ) - 16 KB ) / block_size

The size_spec is an integer, optionally followed by K, M, or G (the case doesn't matter). The default is 262128 (255K), 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=size_spec

Set the number of allocation groups in the Power-Safe filesystem. You should let mkqnx6fsimg calculate a reasonable value for this attribute. The default is 4; the maximum is 64.

num_inodes attribute

num_inodes=size_spec

Set the number of file metadata entries in the filesystem. One individual inode is required for each file, directory, hard link, or symbolic link. This means that the inode count ultimately limits the number of files in the filesystem. The size_spec is an integer, optionally followed by K, M, or G (the case doesn't matter). The default value is 32768.

num_sectors attribute

num_sectors=size_spec

Set the total number of sectors occupied by your image. This is the best way to ensure your image will fit a specific target device. The size_spec is an integer, optionally followed by K, M, or G (the case doesn't matter). The default value is 524288 (512k); at the default sector size of 512 bytes, this equals an image size of 256 MB.

The value you specify for size_spec must be the total number of sectors in your partition rounded down to multiple of 8; if it isn't, the filesystem won't be mountable.

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.
Note: A Power-Safe filesystem must always be exactly the same size (rounded down to the nearest multiple of 8) as the partition (or partitionless 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 an integer multiple of the reported number of sectors per cylinder, which also must be rounded down to the nearest multiple of 8. This requirement is relaxed for resizable images; see the alloc_bnd=size_spec attribute.

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

Set the access permissions of the file, hard link, or symbolic link. 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, permissions of 0666 are used. 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:

  1. a combination of u, g, o, and a
  2. one of -, =, or +
  3. 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 *.

Note: When running on a Windows host, 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 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=path

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

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

sector_size attribute

sector_size=size_spec

Specify the sector size of the filesystem's target device. The size_spec 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.

type attribute

type=file_type

Sets the type of the files being created in the Power-Safe filesystem. Allowable types are:

Note: Specifying [type=dir] tells mkqnx6fsimg 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

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

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 be created and target-path refers to an existing path in the Power-Safe filesystem that's being created. Note that it isn't possible to 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

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

Exit status:

0
Successful completion.
1
An error occurred.