fscoll(1) — USER COMMANDS
NAME
fscoll − Filesystem image generator - Pass 1
SYNOPSIS
fscoll [-Vv] fileprefix
SUMMARY
fscoll is designed to be used as a first pass on .cnf files when preparing filesystem images with fsgen. The images built using fscoll and fsgen. are intended to be used as master images for CD-ROM production, but other uses, such as UNIX filesystem re-organization, are possible. The usual sequence of operations in preparing a CD-ROM image is to first prepare a .cnf file holding configuration information for the CD-ROM image. The fscoll utility is then run on the .cnf file to produce a complete file and directory list which is automatically saved in a .lst file. The .lst file is used by the fsgen utility to create filesystem images, usually to a tape device.
DESCRIPTION
fscoll requires one file name prefix as an argument. It attempts to open a configuration file named prefix.cnf, which it will use as input. If the file does not exist as specified, the program aborts with an error message.
fscoll accepts just two command-line options. The -v (verbose) option causes the generation of extra progress information to the stderr file, and the -V option simply causes fscoll to print a version number and exit. The latter option is intended as a means of checking on which version of fscoll is running.
Two operations are performed on the input configuration file. First, all configuration statements are checked for acceptable content. Any missing or invalid statements cause fscoll to abort with a suitable error message. Secondly, for each input partition, fscoll uses the Root configuration statement, which must be present at least once for all partition types, to generate a complete list of directories and files for inclusion on the final image.
CONFIGURATION FILE FORMAT
The user supplied configuration file is expected to have a hierarchical structure based on the desired slicing of the final CD-ROM image. Up to 15 partition statements are permitted. Each creates a separate partition on the final image, most of which will map directly to a disk slice as defined by Motorola’s disk slicing scheme.
Between each Partition statement and the next are the various configuration statements that apply to that partition. The type and number of the configuration statements depend on the partition type code specified on the Partition statement. Some configuration entries are required, some are optional. In general, where it is possible to supply a reasonable default value for a configuration item, that statement is optional and the default value is assumed.
Usually the configuration statements that apply to a partition are active for the entire partition. In the case of the ISOFS partition, multiple volumes are permitted within the partition definition, and each Volume has its own set of configuration statements.
At least one occurrence of the Root configuration entry is required for all partitions that generate filesystems (ISOFS & UNIXS5). The Root statement indicates a base directory to be used when collecting the file and directory list for the final filesystem. All files and directories found in and below this ´root´ directory are copied into the final image. Although not required by the program, the Root statement is, by convention, the final configuration entry in each partition or ISO9660 volume.
The usual format of the .cnf file may be represented as:
Partition Statement
Configuration statements for Partition 0
Partition Statement
Configuration statements for Partition 1
.
.
Partition Statement
Configuration statements for Partition n
However, the format for ISOFS partitions is more accurately represented by:
Partition Statement
Volume Statement
Configuration statements for Volume 0
Volume Statement
Configuration statements for Volume 1
.
.
Volume Statement
Configuration statements for Volume n
Comments are permitted in the configuration file and are introduced with ´#´ signs. Keywords are not case sensitive and may be typed in any combination of upper- and lowercase. Whitespace is considered a field delimited for all strings unless they are quoted.
For example, the following is a simple configuration file that generates a CD-ROM image with a Motorola Volume Identification (VID) header followed by an ISO9660 filesystem (ISOFS), followed by a UNIX Filesystem (UNIXS5).
#
Partition MOTVID
BootLoader ../boot/romboot
#
# ISO9660 Filesystem
#
Partition ISOFS
Volume ONE
Publisher MOTOROLA INC.
Preparer MOTOROLA INC.
Root /usr/catman
#
# UNIX Filesystem
#
Partition Unixfs
Volume CDVOL1
block 2048
root /user/tmp/cdromdir
CONFIGURATION STATEMENT SYNTAX
Except for comment lines, which are skipped, the only recognized configuration statement fscoll initially expects is the partition statement. The partition statement takes the form of a single text line having the keyword Partition as the first word on the line, followed by a second keyword that identifies the desired partition type. Currently supported partition type keywords are:
| Type String | Meaning |
| MOTVID | Create a Motorola Volume Identifier (VID) partition, that can include a bootloader program. The partition size will default to 16 blocks (of 2048 bytes), but will be allowed to grow beyond 16 blocks if the bootloader is too large. The VID block at the front of the partition will always be configured with parameters suitable for a standard CD-ROM drive. |
| UNIXS5 | Create a standard UNIX System-V file system partition. By default, all files found in the supplied ´root´ directory are recreated exactly as they were found in the final UNIXS5 file system partition. |
| ISOFS | Create an ISO9660 compliant CD-ROM Filesystem. Multiple ´Volumes´ may be created in an ISOFS Filesystem, each Volume has its own set of configuration parameters. |
| IMAGE | Create a partition that is an image copy from another device or file. |
Once a Partition statement is recognized, all statements following that Partition statement up to the next recognized Partition statement are assumed to apply to that partition. In the case of the ISOFS partition, the next statement is expected to be a Volume statement, and all statements up to the next Volume or Partition statement, are considered to apply to that Volume. Configuration statements consist of a keyword, followed by an argument. The argument may be an integer numeric value or a string value. Permitted configuration statements are shown in alphabetical order in the following table.
| Argument | Partition | ||
| Keyword | Format | Type(s) | Effect |
| AbstractFile | String | ISOFS | Supplies a UNIX file name to be recorded in the ISO9660 Volume Descriptor as the file containing an abstract statement for this volume set. The name must exist as a UNIX file in the supplied Root directory. The name will be translated as required before being recorded in the V.D. By default, there is no AbstractFile. |
| Application | String | ISOFS | Supplies a string of up to 128 ISO a-characters to identify the intended application use of the data on the CD-ROM. There is no default value, but secondary Volumes will use the same value as the Primary Volume unless a new string is supplied. |
| ApplicationFile | String | ISOFS | Supplies a UNIX file name to be recorded in the ISO9660 Volume Descriptor as the Application Identifier in place of any string supplied by the Application statement above. The name must exist as a UNIX file in the supplied Root directory. The name will be translated as required before being recorded in the V.D. with an underscore prefix as specified in the ISO9660 standard. By default, there is no ApplicationFile. |
| BibliographicFile | String | ISOFS | Supplies a UNIX file name to be recorded in the ISO9660 Volume Descriptor as the file containing Bibliographic records. The name must exist as a UNIX file in the supplied Root directory. The name will be translated as required before being recorded in the V.D. with an underscore prefix as specified in the ISO9660 standard. By default, there is no BibliographicFile. |
| Argument | Partition | ||
| Keyword | Format | Type(s) | Effect |
| Block | Integer | UNIXS5 IMAGE ISOFS | Specifies a logical block-size for the partition. Or in the case of IMAGE partitions, specifies the block size of the source image. In general, block sizes must be a power of 2 greater than, or equal to 2048. For ISOFS partitions, the block size must be 512,1024 or 2048. Default values are chosen depending on partition type. |
| BootLoader | String | MOTVID | Supplies a path to the desired bootloader program. The bootloader is included in the MOTVID partition. There is no default BootLoader. |
| CopyrightFile | String | ISOFS | Supplies a UNIX file name to be recorded in the ISO9660 Volume Descriptor as the file containing Copyright information. The name must exist as a UNIX file in the supplied Root directory. The name will be translated as required before being recorded in the V.D. with an underscore prefix as specified in the ISO9660 standard. By default, there is no CopyrightFile. |
| DataType | String | IMAGE | An optional keyword that specifies the type of data held in an IMAGE source file. The argument is one of three strings, RAW,ISO or BFS. (Note: The BFS keyword is only available on SVR4 versions of these tools). Normally, this keyword is automatically supplied by fscoll; it is needed by fsgen to allow partition table adjustments for ISO-9660 format image files, and to make internal adjustments to the MOTVID partition. |
| Argument | Partition | ||
| Keyword | Format | Type(s) | Effect |
| Description | String | MOTVID | Supplies a description string for MOTVID partitions. This is a string of up to 20 characters, which is recorded in the first block of the image. The default string is ´fsgen CD-ROM image´. |
| Extensions | String(s) | ISOFS | Supplies a list of extensions that will be applied to the ISO9660 standard filesystem. At present the only supported argument is XAR. The XAR argument causes extended attribute records to be recorded on the ISO9660 filesystem. By default, no extensions are used but secondary Volumes will use the same extensions set in previous volumes unless changed. To stop the use of any extensions use ´Extensions None´. |
| FollowList | String | UNIXS5 | Specifies a file containing a list of symbolic links to ´follow´. Symbolic links are normally recreated exactly as found on the output image. A follow list allows the user to specify which symbolic links are followed when creating the first file. |
| FreeInodes | Integer | UNIXS5 | Specifies a MINIMUM number of free inodes to record in a UNIXS5 file system. This statement is usually used in with the Size statement. (Not generally useful for CD-ROM file systems). |
| Packname | String | UNIXS5 | Specifies a UNIX file system pack name. This name is limited to six characters. |
| Preparer | String | ISOFS | Supplies a string of up to 128 ISO a-characters to identify the data preparer of this ISO Volume. The default string is ´FSGEN VERSION N.N´. Secondary Volumes will use the same string as the primary volume unless it is specifically changed. |
| Argument | Partition | ||
| Keyword | Format | Type(s) | Effect |
| PreparerFile | String | ISOFS | Supplies a UNIX file name to be recorded in the ISO9660 Volume Descriptor as the Preparer Identifier in place of any string supplied by the Preparer statement above. The name must exist as a UNIX file in the supplied Root directory. The name will be translated as required before being recorded in the V.D. with an underscore prefix as specified in the ISO9660 standard. There is no default PreparerFile. |
| Publisher | String | ISOFS | Supplies a string of up to 128 ISO a-characters to identify the data publisher of this ISO Volume. There is no default string, but secondary Volumes will inherit a default value from any previous Volume. |
| PublisherFile | String | ISOFS | Supplies a UNIX file name to be recorded in the ISO9660 Volume Descriptor as the Publisher Identifier in place of any string supplied by the Publisher statement above. The name must exist as a UNIX file in the supplied Root directory. The name will be translated as required before being recorded in the V.D. with an underscore prefix as specified in the ISO9660 standard. There is no default PublisherFile. |
| Root | String | UNIXS5 ISOFS | Supplies a base directory location. All files below the base directory are copied into the target filesystem. In the case of an ISOFS partition, certain file types may be ignored as not applicable to the ISO9660 format. |
| Size | Integer | IMAGE UNIXS5 | Specifies a fixed size for an IMAGE or UNIXS5 partition. The size is the number of Block sized blocks to record in this partition. In the case of IMAGE partitions, the source file may be truncated or zero padded to fit. In the case of UNIXS5 partitions, all files must fit or an error is generated by fsgen when it is run. Padding space in UNIXS5 partitions is recorded as free space in the file system. |
| Argument | Partition | ||
| Keyword | Format | Type(s) | Effect |
| Skip | Integer | IMAGE | Specifies a number of BLOCK sized input blocks to skip when recording this IMAGE partition. The specified number of blocks from the source file is not copied to the image. |
| Source | String | IMAGE | Supplies a source path for an IMAGE partition. The source path can be any file or device. It is used as the source of the image for the IMAGE partition type. |
| System | String | ISOFS | Supplies an identifier for the system that can recognize and act upon the first 16 blocks of the ISO9660 FileSystem. The default value for the Primary Volume is ´MOTOROLA´. Secondary Volumes will inherit a default value from any previous Volume. |
| VolCreateDate | Date | ISOFS | Supplies a date to be used in the ISO Creation Date field of the Volume Descriptor for this Volume. The default value will be the current date and time. Dates are specified using ´MM/DD/CCYY HH:MM:SS´ format, but see LIMITATIONS. |
| VolEffectiveDate | Date | ISOFS | Supplies a date to be used in the ISO Effective Date field of the Volume Descriptor for this Volume. The default value will be the current date and time. |
| VolExpireDate | Date | ISOFS | Supplies a date to be used in the ISO Expiration Date field of the Volume Descriptor for this Volume. By default no expiration date will be set. |
| VolModDate | Date | ISOFS | Supplies a date to be used in the ISO Modification Date field of the Volume Descriptor for this Volume. By default the current date and time will be used. |
| Argument | Partition | ||
| Keyword | Format | Type(s) | Effect |
| Volume | String | UNIXS5 ISOFS | Specifies a volume name. The string size limit depends on partition type. For UNIX it is six characters. For ISOFS partitions it is 32 ISO d-characters. For ISOFS partitions all configuration file lines between one Volume statement and the next are considered to apply to that Volume. Multiple Volume statements are permitted only in ISOFS partitions. |
| VolSet | String | ISOFS | Supplies an ISO9660 string to be used as the Volume Set identifier in the Volume Descriptor for this Volume. The string may consist of up to 128 ISO d-characters. |
Integer arguments should consist only of the digits 0 through 9. The fscoll program collects string arguments by scanning any characters that remain on the line after first skipping any white space after the keyword. Since whitespace is regarded as a delimiter, quote strings that contain whitespace with double or single quotes, in which case any quotes within the string, and any backslash characters must also be escaped.
For example, if the desired string is:
abcdefg\\ hij“klmn
Enter it as:
“abcdefg\\ hij\“klmn“
The use of the backslash to introduce a three-digit octal character code is not supported.
OUTPUT FILE FORMAT
The fscoll utility generates an output file with a name constructed from the same prefix as the input file. For example, if the input file was named demo.cnf, the prefix supplied to the fscoll program is demo and the output file is named demo.lst .
The .lst file contains all configuration information from the original .cnf file and all defaulted values. In addition, after each partition’s configuration statements, the complete directory and file lists are appended. Each directory or file entry consists of a single character identifier: D(irectory), F(ile), B(lock device), C(haracter device), S(ymbolic link) or P(ipe/FIFO), followed by a space and 13 fields separated by commas. The values in the 13 fields (skipping the prefix character) are arranged as in the following table.
| Field | Type | Content |
| 0 | Decimal Integer | Directory or File index number (identifier) |
| 1 | String | Filename to be used in the final CD-ROM image. In the case of ISOFS Filesystems, this name will be an ISO conforming translation of the original UNIX file name. |
| 2 | String | UNIX Pathname to be used as the source file. |
| 3 | Decimal Integer | Parent index number. Indicates the parent directories index. |
| 4 | Decimal Integer | Link Index. If a file can be recreated as a link, this field holds the decimal file index of the target file plus one. |
| 5 | Decimal Integer | Size. This field holds the file size of the source file. |
| 6 | Octal Integer | Mode. This field holds the mode bits of the original file. (see chmod(2)). |
| 7 | Decimal Integer | Userid. This field holds the original User I.D. of the source file. |
| 8 | Decimal Integer | Groupid. This field holds the original Group I.D. of the source file. |
| 9 | Decimal Integer | Dev. If the source file was a device node, this field holds the mknod(2) device I.D. |
| 10 | Decimal Integer | Access Time. The last access time of the file, represented as the number of seconds since 00:00 1/1/1970. |
| 11 | Decimal Integer | Modification Time. The last modification time of the file, represented as the number of seconds since 00:00 1/1/1970. |
| 12 | Decimal Integer | Create Time. The creation time of the file, represented as the number of seconds since 00:00 1/1/1970. |
NOTE
Where file or path names contain backslashes, quotes (") or
commas, they are automatically escaped with extra ´\´s.
The user supplied comments in the original .cnf file are not copied to the .lst file. Certain comments are automatically supplied by fscoll in the .lst file to help break up the output and identify the individual partitions.
ISO9660 NAME TRANSLATION
One of the functions of fscoll when processing ISOFS partitions, is to perform automatic name translation from UNIX file names to ISO9660 file names. Because the ISO9660 standard is far more restrictive than UNIX on file-name length and content, the name translation process involves making names unique by adding integer extensions onto the file name.
For example, if we have two unix files named unixfileone and unixfiletwo then fscoll will initially translate both names into ISO9660 format by changing them both into UNIXFILE.;1. Obviously, two files with the same name cannot be allowed in the same directory, so fscoll will then ´increment´ the name of the second file it finds, turning it into UNIXFIL1.;1. Subsequent name clashes will generate UNIXFIL2.;1 then UNIXFIL3.;1 and so on down the series.
The only way to avoid name translation altogether, is to make sure the initial name is a valid ISO9660 file name. Provided the name does not clash with one of the already translated names collected into the same directory, fscoll will not perform any further translation. Remember, directory names must not use ISO9660 extensions, but file names must have both the extension and the version number.
For more information on ISO9660 file names, consult the ISO9660 standard.
SYMBOLIC LINKS IN UNIXS5 SLICES
The default procedure when building a .lst file is to recreate all symbolic links as found in the original ´root´ directory. In some cases, it may be desirable to follow a symbolic link. In other words, to create it as a ´real´ file (or directory) on the resulting image. This allows, for example, the use of symbolic links to collect certain files and directories into the ’root’ directory without having to physically copy them.
The FollowList statement in a UNIXS5 partition configuration supplies the name of a file that holds a simple list of symbolic links that the user wants to be followed rather than recreated on the target image. The file can contain comments prefixed with ´#´ and paths listed should be relative to the supplied ’root’ directory with no preceding ´/´. For example, if the following command is typed while in the /user/tmp/cdromdir directory and the user wants all the files in /usr/bin to be recreated in the final image, the user must supply a FollowList specifying to follow mysymlink.
# ln -s /usr/bin mysymlink
First, add an entry to the .cnf file:
#
Partition MOTVID
BootLoader ../boot/romboot
#
# ISO9660 Filesystem
#
Partition ISOFS
Volume ONE
Publisher MOTOROLA INC.
Preparer MOTOROLA INC.
Root /usr/catman
#
# UNIX Filesystem
#
Partition Unixfs
Volume CDVOL1
block 2048
root /user/tmp/cdromdir
FollowList CDVOL1.flw
Then edit the CDVOL1.flw file to contain:
#
# Symlink follow list for CDVOL1
#
mysymlink
Note that the path to the FollowList file is specified relative to the directory in which fscoll is run. It is not necessarily in the same directory as the .cnf file. As each entry in a FollowList file is read, the fscoll program checks that it exists and that it is a symbolic link. If either of these tests fail, the program exits with an error.
WARNINGS AND DIAGNOSTICS.
Most error and warning diagnostics are intended to be self-explanatory. It is not possible to list here all the illegal and out of range configuration values because they depend on partition type. In general, configuration error checking in fscoll is extensive and diagnostics should give both the problem, the errno number (where appropriate), and the line number location in the input file. After fscoll has run, a log file is created, named fileprefix.log. This file contains all warning and error messages displayed during the execution of fscoll. Always examine this file for possible problems.
fscoll exits with a value of 0 unless a fatal error was encountered. In the case of an error, exit values are picked from the following table, depending on the class of problem. This set of exit codes is common to all the CD-ROM generation tools.
| Error Class | Exit Value |
| Incorrect user input (.cnf file problem) | 10 (BADCONF) |
| Out of memory, or corrupted memory detected | 11 (BADMEM) |
| File access problems (including missing files) | 12 (BADFILE) |
| I/O operation errors | 13 (BADIO) |
| Illegal input data format | 14 (BADFMT) |
| Internal program errors detected | 15 (INTERR) |
LIMITATIONS
On Motorola machines, there is currently no way to mount secondary volumes from an ISO filesystem. If an ISO9660 Filesystem is being generated for use Motorola machine, then only one Primary Volume should be used, with no secondary Volume statements.
Fscoll and fsgen currently only support interchange level 1 as described in the ISO9660 document. This means that all file names recorded in an ISOFS partition will have a maximum of 8 characters, with a maximum extension of 3 characters.
CD-ROM Volume Sets, or the recording of a file tree over several physical CD-ROM volumes are not supported. Each ISO9660 Volume recorded by fsgen will be logically complete.
Due to way dates are stored internally, no expiration date later then January 18th 2038 can be specified. Keep all dates earlier than this.
SEE ALSO
fsgen(1), loadimg(1).
CD-ROM Image Generation Tools User’s Guide
— Motorola, Inc.