mkfatfsimg

Runs on:

Linux, Microsoft Windows

Options:

-?

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.

-l inputline

(el) Process inputline before interpreting the buildfile. Input lines given to mkfatfsimg 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 mkfatfsimg 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 mkfatfsimg 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, mkfatfsimg 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 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.

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.

Buildfiles

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:

• on the same line as a filename, in which case the attribute modifies only that file. In this example, the attribute modifies only file A:

  [attribute] A
  B
  C
  

• on a line by itself, in which case the attribute modifies all subsequent files. In this example, the attribute modifies files A, B, and 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

?+followlink 

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 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 mkfatfsimg 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 mkfatfsimg 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, mkfatfsimg 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 mkfatfsimg utility doesn't parse the contents of an inline file for anything but the closing brace. For example, mkfatfsimg 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 mkfatfsimg buildfiles, the following attributes are supported:

• cd=pathname
• cksum=number
• dperms=perms_spec
• drop=[pattern]
• +|-dupignore
• fat=type
• filter=filter_spec
• +|-followlink
• +|-include
• media=number
• mtime=time_spec
• num_sectors=count
• +|-optional
• perms=perms_spec
• prefix=path
• search=path[:path...]
• sec_per_clus=number
• sector_size=size_spec
• sha256=hex_string
• sha512=hex_string
• type=file_type
• vol_lbl=string

The following attributes are recognized, but not semantically supported by mkfatfsimg:

• gid=id_spec
• mountperms=perms_spec
• uid=id_spec

The following attributes are recognized, but are only partly supported by mkfatfsimg:

• dperms=perms_spec
• +|-followlink
• perms=perms_spec

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

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

• a number (just as with the chmod command)
• an asterisk (*) to use the host directory's permissions. For directories that don't exist on the host but are created in the buildfile, the permissions are 0777 (rwxrwxrwx). For more information about these target-only directories, see the explanation about directory permissions in the Building Embedded Systems guide.
• a symbolic mode string to delete, add, or set permissions. This string is similar (but not identical) to chmod's and is as follows (with spaces added for clarity):

  [who] operator permissions[, ...]

  The components are as follows:

  who

  A combination of zero or more of the following:

  Character	Meaning
  u	User
  g	Group
  o	Others
  a	All (the default if you don't specify who)

  operator

  One of the following:

  Character	Meaning
  -	Delete the specified permissions
  =	Explicitly set the permissions
  +	Add the specified permissions

  permissions

  A combination of one or more of the following:

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

drop attribute

drop=[pattern[|pattern]...]

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:

• Exclusion applies only during the recursive inclusion of directories; it doesn't apply to any items that you explicitly name in the buildfile.
• Exclusion applies only to files and symbolic links, not subdirectories.
• The pattern is compared only to the filename portion of the items encountered during directory import, not to any directory components of their pathnames.
• The pattern refers to both the host and the target filename (because individual names can't be altered during recursive inclusion).
• Pattern-matching is case-sensitive (as it would on the target).

Specifying the drop attribute without a pattern turns off exclusion in subsequent directories (unless you specify another drop attribute).

dupignore attribute

+|-dupignore

Specify whether mkfatfsimg should ignore duplicate file entries. When buildfiles are defined from templates by external tools, or when the content is split across multiple files that are then combined with the include attribute, there might be multiple entries defining the same target path. Enabling this attribute (+dupignore) allows you to continue using your buildfile structures when you can't change some parts of the image specification and might have to handle duplicate file entries.

If this attribute is undefined for a file entry, the default value is disabled (-dupignore).

When an entry is ignored, mkfatfsimg reports it if the verbosity level is greater than one (e.g., if -vv is used).

For file entries to be considered duplicates, the target path is the only thing that must match. Other attributes that affect files, such as uid, gid, and perms can differ, but the dupignore settings in effect for any entries containing a given target path determine which entry gets included in the image. It's up to the buildfile writer or systems integrator who generates the target image to ensure that what's included at a given target path has all the appropriate attribute settings.

[-dupignore] sshd = path/to/sshd

[+dupignore, uid=0] xyz = /etc/abc

[+dupignore, uid=1] xyz = /vars/def

In this last example, the two host files specified for the common target location are not identical, but again, the target path is the only thing that determines whether their entries are duplicates.

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]

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

If you specify -followlink (disable it):

• If a symbolic link is named explicitly in the buildfile and is a link to a directory, mkfatfsimg follows the link and recurses into the directory. For directory links included indirectly as part of an explicitly named parent directory, they will not be followed but included as symbolic links.
• If the symbolic link is a link to a file, mkfatfsimg includes the link itself in the image filesystem. It's up to you to include in the image whatever the link points to.

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.

include attribute (boolean)

+|-include

[+include] buildfile_path

[+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 development host, or a disk volume label followed by a backslash (\) on a Windows host, it's absolute and mkfatfsimg 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 mkfatfsimg searches the following directories (in this order):

• the current directory
• all paths specified by search attributes
• the boot/build directory under the current root (specified with the -r command-line option)
• the boot/build directory under ${QNX_TARGET}/${PROCESSOR}

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, mkfatfsimg 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, mkfatfsimg 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 mkfatfsimg issues a diagnostic message.

The default is -include, which causes files (if found) to be added to the filesystem, not to the buildfile.

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:

• a single asterisk (*), meaning that the host file's timestamp should be used (the default behavior)

  or:

• in a format based on ISO8601:

  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

This attribute applies only to those items explicitly included in the buildfile.

perms attribute

perms=perms_spec

Set the access permissions of the file. The perms_spec can be one of the following:

• a number (just as with the chmod command)
• an asterisk (*) to use the host file's permissions (or 0666 for inline files)
• a symbolic mode string to delete, add, or set permissions. This string is similar (but not identical) to chmod's and is as follows (with spaces added for clarity):

  [who] operator permissions[, ...]

  The components are as follows:

  who

  A combination of zero or more of the following:

  Character	Meaning
  u	User
  g	Group
  o	Others
  a	All (the default if you don't specify who)

  operator

  One of the following:

  Character	Meaning
  -	Delete the specified permissions
  =	Explicitly set the permissions
  +	Add the specified permissions

  permissions

  A combination of one or more of the following:

  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.

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.

search attribute

search=path[:path...]

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

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

sha512 attribute

sha512=hex_string

Specify the expected SHA512 hash of the file that the attribute applies to. This attribute behaves exactly the same as sha256 except that it uses a 512-bit hash.

type attribute

type=file_type

[type=dir]/usr/bin=/usr/nto/x86_64/bin

/usr/bin=/usr/nto/x86_64/bin

Although link is an accepted type, FAT filesystems don't support symbolic links, so 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

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.

Examples:

To create a FAT filesystem to copy onto a target system's hard-disk partition:

1. Create a buildfile, my_fatfs.bld:

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

2. Create a FAT filesystem image file, my_fatfs.img, using the above buildfile:

   mkfatfsimg my_fatfs.bld my_fatfs.img
   

3. Copy the image file to a target system's hard-disk partition as follows:

   dd if=my_fatfs.img of=/dev/hd0t7 count=524288
   

To create a GPT disk image:

1. Create a buildfile, fat.bld, for the FAT filesystem:

   [num_sectors=16k]
   tst.txt={
   hello!
   }
   

2. Generate a FAT filesystem image:

   mkfatfsimg fat.bld fat.fsi
   

3. Create a configuration file, disk.cfg, for the disk image:

   [cylinders=80 heads=16 sectors_per_track=16 start_at_cylinder=1]
   [partition=1 type_guid="ms" name="FAT"] "fat.fsi"
   

4. Create the disk image:

   diskimage -g -c disk.cfg -o disk.img
   

5. Transfer the disk.img image onto the target system, copy the image onto the disk, and reboot. You can then use pted to get information about the partitions:

   # 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
   

Environment variables:

PFS

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

Exit status:

0

Successful completion.

>0

An error occurred.

129

License not found.

130

Product is not covered under your license.

131

License expired.

132

License not activated.

133

Can't connect to the license server.