mkfatfsimg (Patch ID 4392)

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.

-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 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 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 on the command line:

buildfile

The filename of the buildfile that describes the contents of the FAT 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 FAT 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.

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.

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

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:

?+followlink 

sets the +followlink attribute only if +followlink or -followlink 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, mkfatfsimg 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 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=path
• dperms=perm_spec
• fat=type
• filter=filter_spec
• +|-followlink
• media=number
• mtime=time_spec
• num_sectors=size_spec
• +|-optional
• perms=perm_spec
• prefix=path
• search=path[:path...]
• sec_per_clus=number
• sector_size=size_spec
• type=file_type
• vol_lbl=string

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

• gid=id_spec
• mountperms=perm_spec
• uid=id_spec

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

• dperms=perm_spec
• +|-followlink
• perms=perm_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=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.

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 obtained from the umask of the user running mkfatfsimg. 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 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

If you specify +followlink or omit it, then whenever an item x is taken from the host filesystem and x is a symbolic link, mkfatfsimg resolves the symbolic link and includes its target file or directory. You shouldn't change this behavior, since FAT filesystems don't support symbolic links. If you specify -followlink, and mkfatfsimg encounters a symbolic link, it issues a warning message and skips to the next file.

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:

• 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=size_spec

Set the number of 512-byte sectors on the volume. The size_spec is an integer, optionally followed by K, M, or G (the case doesn't matter). The default value is 2880.

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

Set the access permissions of the file. 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 that FAT filesystems don't support permissions; they have only a read-only attribute. If the combination of permissions indicates that the file should not be writeable for anyone, then the read-only attribute is set.

prefix attribute

prefix=path

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

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.

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

type attribute

type=file_type

Sets the type of the files being created in the FAT filesystem. Allowable types are:

• file—a regular, everyday file (the default)
• dir—a directory

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

/usr/bin=/usr/nto/x86/bin

Note that link is also an accepted type name, but since FAT filesystems don't support symbolic links, a warning will be issued and all attempts to create symbolic links will be skipped.

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 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. As mentioned above, the FAT filesystem ignores any settings for the user ID and group ID.

Examples:

Here's a sample 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. To create a FAT filesystem image file using above buildfile, invoke mkfatfsimg as follows:

mkfatfsimg my_fatfs.bld my_fatfs.img

This creates the my_fatfs.img file containing the FAT filesystem, which you could then copy to a target system's hard-disk partition as follows:

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

Exit status:

0

Successful completion.

1

An error occurred.