Build a FAT filesystem image (QNX)
mkfatfsimg [option...] [buildfile] [directory] [outputfile] mkxfs -t fatfsimg [option...] [buildfile] [directory] [outputfile]
Linux, Mac, Microsoft Windows
The mkfatfsimg utility reads a text buildfile and/or a specified directory and produces a binary image file containing a FAT (fs-dos.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 with these parameters:
If you don't define buildfile or directory, a buildfile is expected as input from standard input. If you don't define outputfile, image-file data will be produced on standard output.
This utility supports long filenames (VFAT).
By default, the FAT type (12, 16, or 32) is derived from the volume size and other geometry parameters. You can use the fat attribute to override this.
License checking
The mkfatfsimg 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 mkfatfsimg 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 FAT image file when it's built by mkfatfsimg. 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 make individual files read-only.
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 the search path on the host system and declare the file as mandatory), enclose both attribute tokens in the same pair of square brackets. For example:
# correct way [search=/tmp -optional] filename # incorrect way [search=/tmp] [-optional] filename
?+followlinksets the +followlink attribute only if +followlink or -followlink 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 mkfatfsimg buildfiles, the following attributes are supported:
The following attributes are recognized, but not semantically supported by mkfatfsimg:
The following attributes are recognized, but are only partly supported by mkfatfsimg:
Since the default values will generate only a 1,44MB FAT12 image, you should explicitly specify at least the image size by specifying num_sectors, to make sure that the image produced will be large enough to hold all specified files and that it will be 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., +|-followlink means either +followlink or -followlink, but not +-followlink).
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 mkfatfsimg.
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, mkfatfsimg 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
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 *.
Note that FAT filesystems don't support permissions; they have only a read-only attribute. If the combination of permissions indicates that the directory should not be writeable for anyone, then the read-only attribute is set.
fat attribute
fat=type
Set the FAT type of the target filesystem. The type must be one of 12, 16, or 32. Note that by defining a specific target FAT type, you may limit the parameter choices so far that no valid filesystem can be constructed. It's usually best to leave this as the default, which is to auto-determine a reasonable FAT type. See the sec_per_clus attribute for how this works.
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 FAT 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 file links and include the target files 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 file link, mkfatfsimg follows the link and includes its target. If you specify -followlink, the resulting behavior depends on how the optional attribute is set. If it's enabled (+optional), mkfatfsimg displays a warning and skips the file; if it's disabled (-optional), the utility prints an error and exits with a failure code.
gid attribute
gid=id_spec
This attribute is supposed to set the group ID number for the file. Since FAT filesystems have no provision to store file ownership information, this attribute is silently disregarded.
media attribute
media=number
Specify a media indicator code. The default value is 0xF8.
mountperms attribute
This attribute is supposed to set the access permissions for the filesystem mountpoint. Since the FAT 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_sectors attribute
num_sectors=count
Set the number of sectors on the volume. The count argument is an integer, optionally followed by K, M, or G (the case doesn't matter). The default value is 2880. Note that the sector size is controlled by a different attribute, sector_size.
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 mkfatfsimg. 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 *.
FAT filesystems don't support permissions; they have only a read-only attribute. If the combination of permissions indicates that the file shouldn't be writeable for anyone, the read-only attribute is set.
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.
search attribute
search=path[:path...]
This attribute specifies that mkfatfsimg 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 FAT 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.
sec_per_clus attribute
sec_per_clus=number
Define the number of sectors assigned per each cluster. This must be one of 1, 2, 4, 8, 16, 32, or 64. Note that while officially allowed, you can't choose a value of 128 because it would necessarily result in a cluster size > 32K and would likely be incompatible with many systems.
The default is to auto-detect a reasonable sectors/cluster ratio. The built-in algorithm tries to use as few sectors per cluster as possible and use the smallest-possible FAT type. This strategy is meant to minimize allocation overhead (the average over-allocation is 1/2 cluster per each file). Of course, small clusters will go along with large FATs which also take up some space. If you know that your filesystem will contain only few files, you may choose a larger sectors/cluster ratio to keep the FATs smaller.
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 (the case doesn't matter). The default value is 512; valid values are 512, 1k, 2k, 4k, 8k, 16k, and 32k. Note that any sector size greater than 4k may be incompatible with some operating systems and will cause a warning to be issued.
sha256 attribute
sha256=hex_string
Specify the expected SHA256 hash of the file that the attribute applies to. If you specify this attribute, mkfatfsimg 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
[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
Note that link is an accepted type, but because FAT filesystems don't support symbolic links, you shouldn't use this setting with mkfatfsimg. If you do, it either prints a warning message (if +optional is specified), or prints an error message and exits in failure (if -optional is specified).
uid attribute
uid=id_spec
This attribute is supposed to set the user ID number for the file. Since FAT filesystems have no provision to store file ownership information, this attribute is silently disregarded.
vol_lbl attribute
vol_lbl=string
Set the volume label to the given string. The default is no label.
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 first character. The entire line is treated 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. As mentioned above, the FAT filesystem ignores any settings for the user ID and group ID.
To create a FAT filesystem to copy onto a target system's hard-disk partition:
# A sample buildfile for mkfatfsimg
[num_sectors=512k]
/home/thaupt
In this example, we've specified a sector count of 512*1024, which relates to 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 FAT filesystem.
mkfatfsimg my_fatfs.bld my_fatfs.img
dd if=my_fatfs.img of=/dev/hd0t7 count=524288
To create a GPT disk image:
[num_sectors=16k] tst.txt={ hello! }
mkfatfsimg fat.bld fat.fsi
[cylinders=80 heads=16 sectors_per_track=16 start_at_cylinder=1] [partition=1 type_guid="ms" name="FAT"] "fat.fsi"
diskimage -g -c disk.cfg -o disk.img
# ls /dev/hd1* /dev/hd1 /dev/hd1.ms.0 # pted /dev/hd1 show -vv Partition 1: Attributes: Type: Microsoft File System Type GUID: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7 Unique GUID: 2DA3EE00-5103-4A5A-A780-C70C2202867A Starting LBA: 256 Ending LBA: 16639 Sectors: 16384 Name: FAT