diff options
Diffstat (limited to 'genisoimage/genisoimage.1')
| -rw-r--r-- | genisoimage/genisoimage.1 | 2823 |
1 files changed, 2823 insertions, 0 deletions
diff --git a/genisoimage/genisoimage.1 b/genisoimage/genisoimage.1 new file mode 100644 index 0000000..d05b24a --- /dev/null +++ b/genisoimage/genisoimage.1 @@ -0,0 +1,2823 @@ +'\" t +.\" genisoimage.1 -*- nroff -*- To render, first run through tbl +.\" Copyright 1993-1998 by Yggdrasil Computing +.\" Copyright 1996-1997 by Robert Leslie +.\" Copyright 1997-2001 by James Pearson +.\" Copyright 1999-2006 by Joerg Schilling +.\" Copyright 2002-2003 by Jungshik Shin +.\" Copyright 2003 by Jaakko Heinonen +.\" Copyright 2006 by the Cdrkit maintainers +.\" +.TH GENISOIMAGE 1 "13 Dec 2006" +.\" ---------------------------------------- +.SH NAME +genisoimage \- create ISO9660/Joliet/HFS filesystem with optional Rock Ridge attributes +.\" ---------------------------------------- +.SH SYNOPSIS +.B genisoimage +.RI [ options ] +.RB [ \-o +.IR filename ] +.IR pathspec " [" "pathspec ..." ] +.\" ---------------------------------------- +.SH DESCRIPTION +.B genisoimage +is a pre-mastering program to generate ISO9660/Joliet/HFS hybrid +filesystems. +.PP +.B genisoimage +is capable of generating the +.B System Use Sharing Protocol records (SUSP) +specified by the +.BR "Rock Ridge Interchange Protocol" . +This is used to further describe the +files in the ISO9660 filesystem to a Unix host, and provides information such +as long filenames, UID/GID, POSIX permissions, symbolic links, and +block and character device files. +.PP +If Joliet or HFS hybrid command line options are specified, +.B genisoimage +will create the additional filesystem metadata needed for Joliet or HFS. +Otherwise +.B genisoimage +will generate a pure ISO9660 filesystem. +.PP +.B genisoimage +can generate a +.I true +(or +.IR shared ) +HFS hybrid filesystem. The same files are seen as HFS files when +accessed from a Macintosh and as ISO9660 files when accessed from other +machines. HFS stands for +.I Hierarchical File System +and is the native filesystem used on Macintosh computers. +.PP +As an alternative, +.B genisoimage +can generate the +.I Apple Extensions to ISO9660 +for each file. These extensions provide each file with CREATOR, TYPE and +certain Finder flags when accessed from a Macintosh. See the +.B HFS MACINTOSH FILE FORMATS +section below. +.PP +.B genisoimage +takes a snapshot of a given directory tree, and generates a +binary image which will correspond to an ISO9660 and/or HFS filesystem when +written to a block device. +.PP +Each file written to the ISO9660 filesystem must have a filename in the 8.3 +format (up to 8 characters, period, up to 3 characters, all uppercase), even +if Rock Ridge is in use. This filename is used on systems that are not able +to make use of the Rock Ridge extensions (such as MS-DOS), and each filename +in each directory must be different from the other filenames in the same +directory. +.B genisoimage +generally tries to form correct names by forcing the Unix filename to +uppercase and truncating as required, but often this yields unsatisfactory +results when the truncated names are not all unique. +.B genisoimage +assigns weightings to each filename, and if two names that are otherwise the +same are found, the name with the lower priority is renamed to include a +3-digit number (guaranteed to be unique). For example, the two files +.I foo.bar +and +.I foo.bar.~1~ +could be rendered as +.I FOO.BAR;1 +and +.IR FOO000.BAR;1 . +.PP +When used with various HFS options, +.B genisoimage +will attempt to recognise files stored in a number of Apple/Unix file formats +and will copy the data and resource forks as well as any +relevant Finder information. See the +.B HFS MACINTOSH FILE FORMATS +section below for more about formats +.B genisoimage +supports. +.PP +Note that +.B genisoimage +is not designed to communicate with the writer directly. Most writers +have proprietary command sets which vary from one manufacturer to +another, and you need a specialized tool to actually burn the disc. +.B wodim +is one such tool. The latest version of +.B wodim +is available from +.IR http://www.cdrkit.org/ . +.PP +.B pathspec +is the path of the directory tree to be copied into the ISO9660 filesystem. +Multiple paths can be specified, and +.B genisoimage +will merge the files found in all of the specified path components to +form the filesystem image. +.PP +If the option +.B \-graft\-points +has been specified, it is possible to graft the paths at points other +than the root directory, and it is possible to graft files or +directories onto the cdrom image with names different than what they +have in the source filesystem. This is easiest to illustrate with a +couple of examples. Let's start by assuming that a local file +.I ../old.lis +exists, and you wish to include it in the cdrom image. +.IP +foo/bar/=../old.lis +.PP +will include +.I old.lis +in the cdrom image at +.IR /foo/bar/old.lis , +while +.IP +foo/bar/xxx=../old.lis +.PP +will include +.I old.lis +in the cdrom image at +.IR /foo/bar/xxx . +The same sort of syntax can be used with directories as well. +.B genisoimage +will create any directories required such that the graft +points exist on the cdrom image \(em the directories do not need to +appear in one of the paths. By default, any directories that are created on +the fly like this will have permissions 0555 and appear to be owned by the +person running +.BR genisoimage . +If you wish other permissions or owners of +the intermediate directories, see +.BR \-uid ", " \-gid ", " \-dir\-mode ", " \-file\-mode " and " \-new\-dir\-mode . +.PP +.B genisoimage +will also run on Windows machines when compiled with Cygnus' cygwin +(available from +.IR http://www.cygwin.com/ ). +Therefore most references in this man page to +.I Unix +can be replaced with +.IR Win32 . +.\" ---------------------------------------- +.SH OPTIONS +.PP +Several options can be specified as defaults in a +.I .genisoimagerc +configuration file, as well as on the command line. If a parameter is +specified in both places, the setting from the command line is used. +For details on the format and possible locations of this file, see +.BR genisoimagerc (5). +.TP +.BI \-abstract " file" +Specifies the abstract filename. There is space for 37 characters. +Equivalent to +.B ABST +in the +.I .genisoimagerc +file. +.TP +.BI \-A " application_id" +Specifies a text string that will be written into the volume header. +This should describe the application that will be on the disc. There +is space for 128 characters. Equivalent to +.B APPI +in the +.I .genisoimagerc +file. +.TP +.B \-allow\-limited\-size +When processing files larger than 2GiB which cannot be easily represented in +ISO9660, add them with a shrunk visible file size to ISO9660 and with the +correct visible file size to the UDF system. The result is an inconsistent +filesystem and users need to make sure that they really use UDF rather than +ISO9660 driver to read a such disk. Implies enabling +.BR \-udf. +.TP +.B \-allow\-leading\-dots +.TP +.B \-ldots +Allow ISO9660 filenames to begin with a period. Usually, a leading dot is +replaced with an underscore in order to maintain MS-DOS compatibility. +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.B \-allow\-lowercase +This options allows lowercase characters to appear in ISO9660 filenames. +.br +This violates the ISO9660 standard, but it happens to work on some systems. +Use with caution. +.TP +.B \-allow\-multidot +This options allows more than one dot to appear in ISO9660 filenames. +A leading dot is not affected by this option, it +may be allowed separately using +.BR \-allow\-leading\-dots . +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.BI \-biblio " file" +Specifies the bibliographic filename. There is space for 37 characters. +Equivalent to +.B BIBL +in the +.I .genisoimagerc +file. +.TP +.B \-cache\-inodes +.TP +.B \-no\-cache\-inodes +Enable or disable caching inode and device numbers to find hard links +to files. If +.B genisoimage +finds a hard link (a file with multiple names), the file will also be +hard-linked on the CD, so the file contents only appear once. This +helps to save space. +.B \-cache\-inodes +is default on Unix-like operating systems, but +.B \-no\-cache\-inodes +is default on some other systems such as Cygwin, because it is not safe +to assume that inode numbers are unique on those systems. (Some +versions of Cygwin create fake inode numbers using a weak hashing +algorithm, which may produce duplicates.) If two files have the same +inode number but are not hard links to the same file, +.B genisoimage \-cache\-inodes +will not behave correctly. +.B \-no\-cache\-inodes +is safe in all situations, but in that case +.B genisoimage +cannot detect hard links, so the resulting CD image may be larger +than necessary. +.TP +.BI \-alpha\-boot " alpha_boot_image" +Specifies the path and filename of the boot image to be used when +making an Alpha/SRM bootable CD. The pathname must be relative to the +source path specified to +.BR genisoimage . +.TP +.BI \-hppa\-bootloader " hppa_bootloader_image" +Specifies the path and filename of the boot image to be used when +making an HPPA bootable CD. The pathname must be relative to the +source path specified to +.BR genisoimage . +Other options are required, at the very least a kernel filename and +a boot command line. See the +.B HPPA NOTES +section below for more information. +.TP +.BI \-hppa\-cmdline " hppa_boot_command_line" +Specifies the command line to be passed to the HPPA boot loader when +making a bootable CD. Separate the parameters with spaces or +commas. More options must be passed to +.B genisoimage, +at the very least a kernel filename and the boot loader filename. +See the +.B HPPA NOTES +section below for more information. +.TP +.BI \-hppa\-kernel\-32 " hppa_kernel_32" +.TP +.BI \-hppa\-kernel\-64 " hppa_kernel_64" +Specifies the path and filename of the 32-bit and/or 64-bit kernel images +to be used when making an HPPA bootable CD. The pathnames must be +relative to the source path specified to +.BR genisoimage . +Other options are required, at the very least the boot loader filename +and the boot command line. See the +.B HPPA NOTES +section below for more information. +.TP +.BI \-hppa\-ramdisk " hppa_ramdisk_image" +Specifies the path and filename of the ramdisk image to be used when +making an HPPA bootable CD. The pathname must be relative to the +source path specified to +.BR genisoimage . +This parameter is optional. Other options are required, at the very +least a kernel filename and the boot command line. See the +.B HPPA NOTES +section below for more information. +.TP +.BI \-mips\-boot " mips_boot_image" +Specifies the path and filename of the boot image to be used when +making an SGI/big-endian MIPS bootable CD. The pathname must be +relative to the source path specified to +.BR genisoimage . +This option may be specified several times, to store up to 15 boot +images. +.TP +.BI \-mipsel\-boot " mipsel_boot_image" +Specifies the path and filename of the boot image to be used when +making an DEC/little-endian MIPS bootable CD. The pathname must be +relative to the source path specified to +.BR genisoimage . +.TP +.BI \-B " img_sun4,img_sun4c,img_sun4m,img_sun4d,img_sun4e" +.TP +.BI \-sparc\-boot " img_sun4,img_sun4c,img_sun4m,img_sun4d,img_sun4e" +Specifies a comma-separated list of boot images that are needed to make +a bootable CD for SPARC systems. +Partition 0 is used for the ISO9660 image, the first image file is mapped +to partition 1. +The comma-separated list may have up to 7 fields, including empty fields. +This option is required to make a bootable CD for Sun SPARC systems. +If +.B \-B +or +.B \-sparc\-boot +has been specified, the first sector of the resulting image will +contain a Sun disk label. This disk label specifies slice 0 for the +ISO9660 image and slices 1 to 7 for the boot images that +have been specified with this option. Byte offsets 512 to 8191 +within each of the additional boot images must contain a primary boot +that works for the appropriate SPARC architecture. The rest of each +of the images usually contains a UFS filesystem used for the primary +kernel boot stage. +.IP +The implemented boot method is the one found with SunOS 4.x and SunOS 5.x. +However, it does not depend on SunOS internals but only on properties of +the Open Boot prom, so it should be usable for any OS for SPARC systems. +For more information also see the +.B NOTES +section below. +.IP +If the special filename +.B ... +is used, the actual and all following boot partitions are mapped to the +previous partition. If +.B genisoimage +is called with +.BI \-G " image " \-B " ..." +all boot partitions are mapped to the partition that contains the ISO9660 +filesystem image and the generic boot image that is located in the first +16 sectors of the disc is used for all architectures. +.TP +.BI \-G " generic_boot_image" +Specifies the path and filename of the generic boot image to be used when making +a generic bootable CD. The boot image will be placed on the first 16 +sectors of the CD, before the ISO9660 primary volume descriptor. +If this option is used together with +.BR \-sparc\-boot , +the Sun disk label will overlay the first 512 bytes of the generic +boot image. +.TP +.BI \-b " eltorito_boot_image" +Specifies the path and filename of the boot image to be used when making +an El Torito bootable CD for x86 PCs. The pathname must be relative to +the source path specified to +.BR genisoimage . +This option is required to make an El Torito bootable CD. +The boot image must be exactly 1200 kB, 1440 kB or 2880 kB, and +.B genisoimage +will use this size when creating the output ISO9660 filesystem. The PC +BIOS will use the image to emulate a floppy disk, so the first 512-byte +sector should contain PC boot code. This will work, for example, if +the boot image is a LILO-based boot floppy. +.IP +If the boot image is not an image of a floppy, you need to add either +.BR \-hard\-disk\-boot " or " \-no\-emul\-boot . +If the system should not boot off the emulated disk, use +.BR \-no\-boot . +.IP +If +.B \-sort +has not been specified, the boot images are sorted +with low priority (+2) to the beginning of the medium. +If you don't like this, you need to specify a sort weight of 0 for the boot images. +.TP +.B \-eltorito\-alt\-boot +Start with a new set of El Torito boot parameters. Up to 63 El Torito +boot entries may be stored on a single CD. +.TP +.BI \-hard\-disk\-boot +Specifies that the boot image used to create El Torito bootable CDs is +a hard disk image. The image must begin with a master boot +record that contains a single partition. +.TP +.BI \-no\-emul\-boot +Specifies that the boot image used to create El Torito bootable CDs is +a "no emulation" image. The system will load and execute this image without +performing any disk emulation. +.TP +.BI \-no\-boot +Specifies that the created El Torito CD should be marked as not bootable. The +system will provide an emulated drive for the image, but will boot off +a standard boot device. +.TP +.BI \-boot\-load\-seg " segment_address" +Specifies the load segment address of the boot image for no-emulation +El Torito CDs. +.TP +.BI \-boot\-load\-size " load_sectors" +Specifies the number of "virtual" (512-byte) sectors to load in +no-emulation mode. The default is to load the entire boot file. Some +BIOSes may have problems if this is not a multiple of 4. +.TP +.B \-boot\-info\-table +Specifies that a 56-byte table with information of the CD-ROM layout +will be patched in at offset 8 in the boot file. If this option is +given, the boot file is +.IR "modified in the source filesystem" , +so make a copy of this file if it cannot be easily regenerated! +See the +.B EL TORITO BOOT INFO TABLE +section for a description of this table. +.TP +.BI \-C " last_sess_start,next_sess_start" +This option is needed to create a CD Extra or the image of a second +session or a higher-level session for a multisession disc. +.B \-C +takes two numbers separated by a comma. The first is the first sector +in the last session of the disc that should be appended to. +The second number is the starting sector number of the new session. +The correct numbers may be retrieved by calling +.B wodim \-msinfo ... +If +.B \-C +is used in conjunction with +.BR \-M , +.B genisoimage +will create a filesystem image that is intended to be a continuation +of the previous session. +If +.B \-C +is used without +.BR \-M , +.B genisoimage +will create a filesystem image that is intended to be used for a second +session on a CD Extra. This is a multisession CD that holds audio data +in the first session and an ISO9660 filesystem in the second session. +.TP +.BI \-c " boot_catalog" +Specifies the path and filename of the boot catalog, which is required +for an El Torito bootable CD. The pathname must be relative to the source +path specified to +.BR genisoimage . +This file will be inserted into the output tree and not created +in the source filesystem, so be +sure the specified filename does not conflict with an existing file, or +it will be excluded. Usually a name like +.I boot.catalog +is chosen. +.IP +If +.B \-sort +has not been specified, the boot catalog sorted +with low priority (+1) to the beginning of the medium. +If you don't like this, you need to specify a sort weight of 0 for the boot catalog. +.TP +.B \-check\-oldnames +Check all filenames imported from the old session for compliance with +the ISO9660 file naming rules. +Without this option, only names longer than 31 characters are checked, +as these files are a serious violation of the ISO9660 standard. +.TP +.BI \-check\-session " file" +Check all old sessions for compliance with actual +.B genisoimage +ISO9660 file naming rules. +This is a high-level option that combines +.B \-M +.I file +.BR "\-C 0,0 \-check\-oldnames" . +For the parameter +.IR file , +see the description of +.BR \-M . +.TP +.BI \-copyright " file" +Specifies copyright information, typically a filename on the disc. +There is space for 37 characters. Equivalent to +.B COPY +in the +.I .genisoimagerc +file. +.TP +.B \-d +Do not append a period to files that do not have one. +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.B \-D +Do not use deep directory relocation, and instead just pack them in the +way we see them. +.br +If ISO9660:1999 has not been selected, +this violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.BI \-dir\-mode " mode" +Overrides the mode of directories used to create the image to +.IR mode , +specified as 4 digits of permission bits as in +.BR chmod (1). +This option automatically enables Rock Ridge extensions. +.TP +.B \-dvd\-video +Generate a DVD-Video compliant UDF filesystem. This is done by sorting the +order of the content of the appropriate files and by adding padding +between the files if needed. +Note that the sorting only works if the DVD-Video filenames include uppercase +characters only. +.IP +Note that in order to get a DVD-Video compliant filesystem image, you +need to prepare a DVD-Video compliant directory tree. This requires a +directory +.B VIDEO_TS +(all caps) in the root directory of the resulting DVD, and usually +another directory +.BR AUDIO_TS . +.B VIDEO_TS +needs to include all needed files (filenames must be all caps) for a +compliant DVD-Video filesystem. +.TP +.B \-f +Follow symbolic links when generating the filesystem. When this option is not +in use, symbolic links will be entered using Rock Ridge if enabled, otherwise +they will be ignored. +.TP +.BI \-file\-mode " mode" +Overrides the mode of regular files used to create the image to +.IR mode , +specified as 4 digits of permission bits as in +.BR chmod (1). +This option automatically enables Rock Ridge extensions. +.TP +.BI \-gid " gid" +Overrides the group ID read from the source files to the value of +.IR gid . +Specifying this option automatically enables Rock Ridge extensions. +.TP +.B \-gui +Switch the behaviour for a GUI. This currently makes the output more verbose +but may have other effects in the future. +.TP +.B \-graft\-points +Allow use of graft points for filenames. If this option is used, all +filenames are checked for graft points. The filename is divided at the +first unescaped equal sign. All occurrences of `\(rs' and `=' characters +must be escaped with `\(rs' if +.B \-graft\-points +has been specified. +.TP +.BI \-hide " glob" +Hide any files matching +.IR glob , +a shell wildcard pattern, from being seen in the ISO9660 or Rock Ridge +directory. +.I glob +may match any part of the filename or path. If +.I glob +matches a directory, the contents of that directory will be hidden. +In order to match a directory name, make sure the pathname does not include +a trailing `/' character. +All the hidden files will still be written to the output CD image file. +See also +.BR \-hide\-joliet , +and +.IR README.hide . +This option may be used multiple times. +.TP +.BI \-hide\-list " file" +A file containing a list of shell wildcards to be hidden. See +.BR \-hide . +.TP +.BI \-hidden " glob" +Add the hidden (existence) ISO9660 directory attribute for files and +directories matching +.IR glob , +a shell wildcard pattern. This attribute will prevent the files from +being shown by some MS-DOS and Windows commands. +.I glob +may match any part of the filename or path. +In order to match a directory name, make sure the pathname does not include +a trailing `/' character. +This option may be used multiple times. +.TP +.BI \-hidden\-list " file" +A file containing a list of shell wildcards to get the hidden +attribute. See +.BR \-hidden . +.TP +.BI \-hide\-joliet " glob" +Hide files and directories matching +.IR glob , +a shell wildcard pattern, from being seen in the Joliet directory. +.I glob +may match any part of the filename or path. If +.I glob +matches a directory, the contents of that directory will be hidden. +In order to match a directory name, make sure the pathname does not include +a trailing `/' character. +All the hidden files will still be written to the output CD image file. +This option is usually used with +.BR \-hide . +See also +.IR README.hide . +This option may be used multiple times. +.TP +.BI \-hide\-joliet\-list " file" +A file containing a list of shell wildcards to be hidden from the +Joliet tree. See +.BR \-hide\-joliet . +.TP +.B \-hide\-joliet\-trans\-tbl +Hide the +.I TRANS.TBL +files from the Joliet tree. +These files usually don't make sense in the Joliet world as they list +the real name and the ISO9660 name which may both be different from the +Joliet name. +.TP +.B \-hide\-rr\-moved +Rename the directory +.I RR_MOVED +to +.I .rr_moved +in the Rock Ridge tree. +It seems to be impossible to completely hide the +.I RR_MOVED +directory from the Rock Ridge tree. +This option only makes the visible tree less confusing for +people who don't know what this directory is for. +If you need to have no +.I RR_MOVED +directory at all, you should use +.BR \-D . +Note that if +.B \-D +has been specified, the resulting filesystem is not ISO9660 +level-1 compliant and will not be readable on MS-DOS. +See also the +.B NOTES +section. +.TP +.BI \-input\-charset " charset" +Input charset that defines the characters used in local filenames. +To get a list of valid charset names, call +.BR "genisoimage \-input\-charset help" . +To get a 1:1 mapping, you may use +.B default +as charset name. The default initial values are +.I cp437 +on DOS-based systems and +.I iso8859-1 +on all other systems. See the +.B CHARACTER SETS +section below for more details. +.TP +.BI \-output\-charset " charset" +Output charset that defines the characters that will be used in Rock Ridge +filenames. Defaults to the input charset. See +.B CHARACTER SETS +section below for more details. +.TP +.BI \-iso\-level " level" +Set the ISO9660 conformance level. Valid numbers are 1 to 4. +.IP +With level 1, files may only consist of one section and filenames are +restricted to 8.3 characters. +.IP +With level 2, files may only consist of one section. +.IP +With level 3, no restrictions (other than ISO-9660:1988) do apply. +.IP +With all ISO9660 levels from 1 to 3, all filenames are restricted to +uppercase letters, numbers and underscores (_). Filenames are +limited to 31 characters, directory nesting is limited to 8 +levels, and pathnames are limited to 255 characters. +.IP +Level 4 officially does not exist but +.B genisoimage +maps it to ISO-9660:1999, which is ISO9660 version 2. +.IP +With level 4, an enhanced volume descriptor with version number +and file structure version number set to 2 is emitted. +Directory nesting is not limited to 8 levels, +there is no need for a file to contain a dot and the dot has no +special meaning, filenames do not have version numbers, +.\" (f XXX ??? The character used for filling byte positions which are +.\" specified to be characters is subject to agreement between the +.\" originator and the recipient of the volume), +and filenames can be up to 207 characters long, or 197 characters if +Rock Ridge is used. +.IP +When creating Version 2 images, +.B genisoimage +emits an enhanced volume descriptor, similar but not identical to a +primary volume descriptor. Be careful not to use broken software +to make ISO9660 images bootable by assuming a second PVD copy and patching +this putative PVD copy into an El Torito VD. +.TP +.B \-J +Generate Joliet directory records in addition to regular ISO9660 +filenames. This is primarily useful when the discs are to be used on +Windows machines. Joliet filenames are specified in Unicode and each +path component can be up to 64 Unicode characters long. +Note that Joliet is not a standard \(em only Microsoft Windows and Linux +systems can read Joliet extensions. For greater portability, consider +using both Joliet and Rock Ridge extensions. +.TP +.B \-joliet\-long +Allow Joliet filenames to be up to 103 Unicode characters, instead of +64. This breaks the Joliet specification, but appears to work. Use +with caution. +.\" The number 103 is derived from: the maximum Directory Record Length +.\" (254), minus the length of Directory Record (33), minus CD-ROM XA +.\" System Use Extension Information (14), divided by the UTF-16 +.\" character size (2). +.TP +.BI \-jcharset " charset" +A combination of +.B \-J \-input\-charset +.IR charset . +See the +.B CHARACTER SETS +section below for more details. +.TP +.B \-l +Allow full 31-character filenames. Normally the ISO9660 filename will be in an +8.3 format which is compatible with MS-DOS, even though the ISO9660 standard +allows filenames of up to 31 characters. If you use this option, the disc may +be difficult to use on a MS-DOS system, but will work on most other systems. +Use with caution. +.TP +.B \-L +Outdated option; use +.B \-allow\-leading\-dots +instead. +.TP +.BI \-jigdo\-jigdo " jigdo_file" +Produce a +.B jigdo +.I .jigdo +metadata file as well as the filesystem image. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-template " template_file" +Produce a +.B jigdo +.I .template +file as well as the filesystem image. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-min\-file\-size " size" +Specify the minimum size for a file to be listed in the +.I .jigdo +file. Default (and minimum allowed) is 1KB. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-force\-md5 " path" +Specify a file pattern where files +.I must +be contained in the externally-supplied MD5 list as supplied by +.BR \-md5\-list . +See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-exclude " path" +Specify a file pattern where files will not be listed in the +.I .jigdo +file. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-map " path" +Specify a pattern mapping for the jigdo file +(e.g. +.IR Debian=/mirror/debian ). +See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-md5\-list " md5_file" +Specify a file containing the MD5sums, sizes and pathnames of the +files to be included in the +.I .jigdo +file. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-jigdo\-template\-compress " algorithm +Specify a compression algorithm to use for template date. gzip and +bzip2 are currently supported, and gzip is the default. See the +.B JIGDO NOTES +section below for more information. +.TP +.BI \-log\-file " log_file" +Redirect all error, warning and informational messages to +.I log_file +instead of the standard error. +.TP +.BI \-m " glob" +Exclude files matching +.IR glob , +a shell wildcard pattern, from being written to CD-ROM. +.I glob +may match either the filename component or the full pathname. +This option may be used multiple times. For example: +.sp + genisoimage \-o rom \-m \(aq*.o\(aq \-m core \-m foobar +.sp +would exclude all files ending in `.o', or called +.IR core " or " foobar +from the image. Note that if you had a directory called +.IR foobar , +it too (and of course all its descendants) would be excluded. +.TP +.BI \-exclude\-list " file" +A file containing a list of shell wildcards to be excluded. See +.BR \-m . +.TP +.B \-max\-iso9660\-filenames +Allow ISO9660 filenames to be up to 37 characters long. +This option enables +.B \-N +as the extra name space is taken from the space reserved for +file version numbers. +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Although a conforming application needs to provide a buffer space of at +least 37 characters, discs created with this option may cause a buffer +overflow in the reading operating system. Use with extreme care. +.TP +.BI \-M " path" +.TP +.BI \-M " device" +.TP +.BI \-dev " device" +Specifies path to existing ISO9660 image to be merged. The alternate form +takes a SCSI device specifier that uses the same syntax as the +.B dev= +parameter of +.BR wodim . +The output of +.B genisoimage +will be a new session which should get written to the end of the +image specified in +.BR \-M . +Typically this requires multisession capability for the CD recorder +used to write the image. This option may only be used in conjunction +with +.BR \-C . +.TP +.B \-N +Omit version numbers from ISO9660 filenames. +.br +This violates the ISO9660 standard, but no one really uses the +version numbers anyway. Use with caution. +.TP +.BI \-new\-dir\-mode " mode" +Specify the mode, a 4-digit number as used in +.BR chmod (1), +to use when creating new directories in the filesystem image. The +default is 0555. +.TP +.B \-nobak +.TP +.B \-no\-bak +Exclude backup files files on the ISO9660 filesystem; that is, +filenames that contain the characters `~' or `#' or end in +.IR .bak . +These are typically backup files for Unix text editors. +.TP +.B \-force\-rr +Do not use the automatic Rock Ridge attributes recognition for previous sessions. +This can work around problems with images created by, e.g., NERO Burning ROM. +.TP +.B \-no\-rr +Do not use the Rock Ridge attributes from previous sessions. +This may help to avoid problems when +.B genisoimage +finds illegal Rock Ridge signatures on an old session. +.TP +.B \-no\-split\-symlink\-components +Don't split the symlink components, but begin a new Continuation Area (CE) +instead. This may waste some space, but the SunOS 4.1.4 cdrom driver +has a bug in reading split symlink components. +.IP +It is questionable whether this option is useful nowadays. +.TP +.B \-no\-split\-symlink\-fields +Don't split the symlink fields, but begin a new Continuation Area (CE) +instead. This may waste some space, but the SunOS 4.1.4 and +Solaris 2.5.1 cdrom driver have a bug in reading split symlink fields +(a `/' can be dropped). +.IP +It is questionable whether this option is useful nowadays. +.TP +.BI \-o " filename" +Specify the output file for the the ISO9660 filesystem image. +This can be a disk file, a tape drive, or it can correspond directly +to the device name of the optical disc writer. If not specified, stdout is +used. Note that the output can also be a block device for a regular +disk partition, in which case the ISO9660 filesystem can be mounted +normally to verify that it was generated correctly. +.TP +.B \-pad +Pad the end of the whole image by 150 sectors (300 kB). This option is +enabled by default. If used in combination with +.BR \-B , +padding is inserted between the ISO9660 partition and the boot +partitions, such that the first boot partition starts +on a sector number that is a multiple of 16. +.IP +The padding is needed as many operating systems (e.g. Linux) +implement read-ahead bugs in their filesystem I/O. These bugs result in read +errors on files that are located near the end of a track, particularly +if the disc is written in Track At Once mode, or where a CD audio track +follows the data track. +.\" XXX: Someone should check to see if the Linux readahead bug is +.\" XXX: still present, and update this comment accordingly. +.TP +.B \-no\-pad +Do not pad the end by 150 sectors (300 kB) and do not make the the boot partitions +start on a multiple of 16 sectors. +.TP +.BI \-path\-list " file" +A file containing a list of +.I pathspec +directories and filenames to be added to the ISO9660 filesystem. This list +of pathspecs are processed after any that appear on the command line. If the +argument is +.IR \- , +the list is read from the standard input. +.TP +.B \-P +Outdated option; use +.B \-publisher +instead. +.TP +.BI \-publisher " publisher_id" +Specifies a text string that will be written into the volume header. +This should describe the publisher of the CD-ROM, usually with a +mailing address and phone number. There is space for 128 characters. +Equivalent to +.B PUBL +in the +.I .genisoimagerc +file. +.TP +.BI \-p " preparer_id" +Specifies a text string that will be written into the volume header. +This should describe the preparer of the CD-ROM, usually with a mailing +address and phone number. There is space for 128 characters. +Equivalent to +.B PREP +in the +.I .genisoimagerc +file. +.TP +.B \-print\-size +Print estimated filesystem size in multiples of the sector size (2048 bytes) +and exit. This option is needed for +Disk At Once mode and with some CD-R drives when piping directly into +.BR wodim , +cases where +.B wodim +needs to know the size of the filesystem image in advance. +Old versions of +.B mkisofs +wrote this information (among other information) to +.IR stderr . +As this turns out to be hard to parse, the number without any other information +is now printed on +.I stdout +too. +If you like to write a simple shell script, redirect +.I stderr +and catch the number from +.IR stdout . +This may be done with: +.sp + cdblocks=\` genisoimage \-print\-size \-quiet .\|.\|. \` +.br + genisoimage .\|.\|. | wodim .\|.\|. tsize=${cdblocks}s \- +.TP +.B \-quiet +This makes +.B genisoimage +even less verbose. No progress output will be provided. +.TP +.B \-R +Generate SUSP and RR records using the Rock Ridge protocol to further describe +the files on the ISO9660 filesystem. +.TP +.B \-r +This is like the \-R option, but file ownership and modes are set to +more useful values. The uid and gid are set to zero, because they are +usually only useful on the author's system, and not useful to the +client. All the file read bits are set true, so that files and +directories are globally readable on the client. If any execute bit is +set for a file, set all of the execute bits, so that executables are +globally executable on the client. If any search bit is set for a +directory, set all of the search bits, so that directories are globally +searchable on the client. All write bits are cleared, because the +filesystem will be mounted read-only in any case. If any of the special +mode bits are set, clear them, because file locks are not useful on a +read-only filesystem, and set-id bits are not desirable for uid 0 or +gid 0. +When used on Win32, the execute bit is set on +.I all +files. This is a result of the lack of file permissions on Win32 and the +Cygwin POSIX emulation layer. See also +.BR \-uid ", " \-gid , +.BR \-dir\-mode ", " \-file\-mode +and +.BR \-new\-dir\-mode . +.TP +.B \-relaxed\-filenames +Allows ISO9660 filenames to include all 7-bit ASCII characters except +lowercase letters. +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.BI \-root " dir" +Moves all files and directories into +.I dir +in the image. This is essentially the +same as using +.B \-graft\-points +and adding +.I dir +in front of every pathspec, but is easier to use. +.I dir +may actually be several levels deep. It is +created with the same permissions as other graft points. +.TP +.BI \-old-root " dir" +This option is necessary when writing a multisession +image and the previous (or even older) session was written with +.B -root +.IR dir . +Using a directory name not found in the previous session +causes +.B genisoimage +to abort with an error. +Without this option, +.B genisoimage +would not be able to find unmodified files and would +be forced to write their data into the image once more. +.B \-root +and +.B \-old-root +are meant to be used together to do incremental backups. +The initial session would e.g. use: +.B genisoimage \-root backup_1 +.IR dirs . +The next incremental backup with +.B genisoimage \-root backup_2 \-old-root backup_1 +.I dirs +would take another snapshot of these directories. The first +snapshot would be found in +.BR backup_1 , +the second one in +.BR backup_2 , +but only modified or new files need to be written +into the second session. +Without these options, new files would be added and old ones would be +preserved. But old ones would be overwritten if the file was +modified. Recovering the files by copying the whole directory back +from CD would also restore files that were deleted +intentionally. Accessing several older versions of a file requires +support by the operating system to choose which sessions are to be +mounted. +.TP +.BI \-sort " sort_file" +Sort file locations on the media. Sorting is controlled by a file that +contains pairs of filenames and sorting offset weighting. +If the weighting is higher, the file will be located closer to the +beginning of the media, if the weighting is lower, the file will be located +closer to the end of the media. There must be only one space or tabs +character between the filename and the +weight and the weight must be the last characters on a line. The filename +is taken to include all the characters up to, but not including the last +space or tab character on a line. This is to allow for space characters to +be in, or at the end of a filename. +This option does +.B not +sort the order of the filenames that appear +in the ISO9660 directory. It sorts the order in which the file data is +written to the CD image, which is useful in order to optimize the +data layout on a CD. See +.B README.sort +for more details. +.TP +.BI \-sparc\-boot " img_sun4,img_sun4c,img_sun4m,img_sun4d,img_sun4e" +See +.B \-B +above. +.TP +.BI \-sparc\-label " label" +Set the Sun disk label name for the Sun disk label that is created with +.BR \-sparc-boot . +.TP +.B \-split\-output +Split the output image into several files of approximately 1 GB each. +This helps to create DVD-sized ISO9660 images on operating systems without +large file support. +.B wodim +will concatenate more than one file into a single track if writing to a DVD. +To make +.B \-split\-output +work, +.BI \-o " filename" +must be specified. The resulting output images will be named: +.IR filename_00 ", " filename_01 ", " filename_02 .... +.TP +.BI \-stream\-media\-size " #" +Select streaming operation and set the media size to # sectors. +This allows you to pipe the output of the +.BR tar (1) +program into +.B genisoimage +and to create an ISO9660 filesystem without the need of an intermediate +tar archive file. +If this option has been specified, +.B genisoimage +reads from +.I stdin +and creates a file with the name +.IR STREAM.IMG . +The maximum size of the file (with padding) is 200 sectors less than the +specified media size. If +.B \-no\-pad +has been specified, the file size is 50 sectors less than the specified media size. +If the file is smaller, +.B genisoimage +will write padding. This may take awhile. +.IP +The option +.B \-stream\-media\-size +creates simple ISO9660 filesystems only and may not used together with multisession +or hybrid filesystem options. +.TP +.BI \-stream\-file\-name " name" +Reserved for future use. +.TP +.BI \-sunx86\-boot " UFS_img,,,AUX1_img" +Specifies a comma-separated list of filesystem images that are needed to make +a bootable CD for Solaris x86 systems. +.IP +Note that partition 1 is used for the ISO9660 image and that partition 2 is +the whole disk, so partition 1 and 2 may not be used by external partition data. +The first image file is mapped to partition 0. +There may be empty fields in the comma-separated list, +and list entries for partition 1 and 2 must be empty. +The maximum number of supported partitions is 8 (although the Solaris x86 +partition table could support up to 16 partitions), so it is impossible +to specify more than 6 partition images. +This option is required to make a bootable CD for Solaris x86 systems. +.IP +If +.B \-sunx86\-boot +has been specified, the first sector of the resulting image will +contain a PC fdisk label with a Solaris type 0x82 fdisk partition that +starts at offset 512 and spans the whole CD. +In addition, for the Solaris type 0x82 fdisk partition, there is a +SVr4 disk label at offset 1024 in the first sector of the CD. +This disk label specifies slice 0 for the first (usually UFS type) +filesystem image that is used to boot the PC and slice 1 for +the ISO9660 image. +Slice 2 spans the whole CD slice 3 .\|.\|. slice 7 may be used for additional +filesystem images that have been specified with this option. +.IP +A Solaris x86 boot CD uses a 1024 byte sized primary boot that uses the +.B El-Torito no-emulation +boot mode and a secondary generic boot that is in CD sectors 1\|.\|.15. +For this reason, both +.BI "-b " bootimage " \-no\-emul\-boot" +and +.BI \-G " genboot" +must be specified. +.TP +.BI \-sunx86\-label " label" +Set the SVr4 disk label name for the SVr4 disk label that is created with +.BR \-sunx86-boot . +.TP +.BI \-sysid " ID" +Specifies the system ID. There is space for 32 characters. +Equivalent to +.B SYSI +in the +.I .genisoimagerc +file. +.TP +.B \-T +Generate a file +.I TRANS.TBL +in each directory on the CD-ROM, which can be used +on non-Rock\ Ridge-capable systems to help establish the correct filenames. +There is also information present in the file that indicates the major and +minor numbers for block and character devices, and each symlink has the name of +the link file given. +.TP +.BI \-table\-name " table_name" +Alternative translation table filename (see above). Implies +.BR \-T . +If you are creating a multisession image you must use the same name +as in the previous session. +.TP +.BI \-ucs\-level " level" +Set Unicode conformance level in the Joliet SVD. The default level is 3. +It may be set to 1..3 using this option. +.TP +.B \-udf +Include UDF filesystem support in the generated filesystem image. UDF +support is currently in alpha status and for this reason, it is not +possible to create UDF-only images. UDF data structures are currently +coupled to the Joliet structures, so there are many pitfalls with the +current implementation. There is no UID/GID support, there is no POSIX +permission support, there is no support for symlinks. Note that UDF +wastes the space from sector ~20 to sector 256 at the beginning of the +disc in addition to the space needed for real UDF data structures. +.TP +.BI \-uid " uid" +Overrides the uid read from the source files to the value of +.IR uid . +Specifying this option automatically enables Rock Ridge extensions. +.TP +.B \-use\-fileversion +The option +.B \-use\-fileversion +allows +.B genisoimage +to use file version numbers from the filesystem. +If the option is not specified, +.B genisoimage +creates a version number of 1 for all files. +File versions are strings in the range +.I ;1 +to +.I ;32767 +This option is the default on VMS. +.TP +.B \-U +Allows "untranslated" filenames, completely violating the ISO9660 standards +described above. Enables the following flags: +.B \-d \-l \-N \-allow\-leading\-dots \-relaxed\-filenames +.BR "\-allow\-lowercase \-allow\-multidot \-no\-iso\-translate" . +Allows more than one `.' character in the filename, as well as +mixed-case filenames. This is useful on HP-UX, where the built-in +.I cdfs +filesystem does not recognize any extensions. Use with extreme caution. +.TP +.B \-no\-iso\-translate +Do not translate the characters `#' and `~' which are invalid for ISO9660 filenames. +Although invalid, these characters are often used by Microsoft systems. +.br +This violates the ISO9660 standard, but it happens to work on many systems. +Use with caution. +.TP +.BI \-V " volid" +Specifies the volume ID (volume name or label) to be written into the +master block. There is space for 32 characters. Equivalent to +.B VOLI +in the +.I .genisoimagerc +file. The volume ID is used as the mount point by the Solaris volume +manager and as a label assigned to a disc on various other platforms +such as Windows and Apple Mac OS. +.TP +.BI \-volset " ID" +Specifies the volume set ID. There is space for 128 characters. +Equivalent to +.B VOLS +in the +.I .genisoimagerc +file. +.TP +.BI \-volset\-size " #" +Sets the volume set size to #. +The volume set size is the number of CDs that are in a CD volume set. +A volume set is a collection of one or more volumes, on which a set of +files is recorded. +.IP +Volume Sets are not intended to be used to create a set numbered CDs +that are part of e.g. a Operation System installation set of CDs. +Volume Sets are rather used to record a big directory tree that would not +fit on a single volume. +Each volume of a Volume Set contains a description of all the directories +and files that are recorded on the volumes where the sequence numbers +are less than, or equal to, the assigned Volume Set Size of the current +volume. +.IP +.B genisoimage +currently does not support a +.B \-volset\-size +that is larger than 1. +.IP +The option +.B \-volset\-size +must be specified before +.B \-volset\-seqno +on each command line. +.TP +.BI \-volset\-seqno " #" +Sets the volume set sequence number to #. +The volume set sequence number is the index number of the current +CD in a CD set. +The option +.B \-volset\-size +must be specified before +.B \-volset\-seqno +on each command line. +.TP +.B \-v +Verbose execution. If given twice on the command line, extra debug information +will be printed. +.TP +.BI \-x " glob" +Identical to +.B \-m +.IR glob . +.TP +.B \-z +Generate special +.I RRIP +records for transparently compressed files. +This is only of use and interest for hosts that support transparent +decompression, such as Linux 2.4.14 or later. You must specify +.BR \-R " or " \-r +to enable Rock Ridge, and generate compressed files using the +.B mkzftree +utility before running +.BR genisoimage . +Note that transparent compression is a nonstandard Rock Ridge extension. +The resulting disks are only transparently readable if used on Linux. +On other operating systems you will need to call +.B mkzftree +by hand to decompress the files. +.\" ---------------------------------------- +.SH "HFS OPTIONS" +.TP +.B \-hfs +Create an ISO9660/HFS hybrid CD. This option should be used in conjunction +with the +.BR \-map , +.B \-magic +and/or the various +.I double dash +options given below. +.TP +.B \-apple +Create an ISO9660 CD with Apple's extensions. Similar to +.BR \-hfs , +except that the Apple Extensions to ISO9660 are added instead of +creating an HFS hybrid volume. +Former +.B genisoimage +versions did include Rock Ridge attributes by default if +.B \-apple +was specified. This versions of +.B genisoimage +does not do this anymore. If you like to have Rock Ridge attributes, +you need to specify this separately. +.TP +.BI \-map " mapping_file" +Use the +.I mapping_file +to set the CREATOR and TYPE information for a file based on the +filename's extension. A filename is +mapped only if it is not one of the know Apple/Unix file formats. See the +.B HFS CREATOR/TYPE +section below. +.TP +.BI \-magic " magic_file" +The CREATOR and TYPE information is set by using a file's +.I magic number +(usually the first few bytes of a file). The +.I magic_file +is only used if a file is not one of the known Apple/Unix file formats, or +the filename extension has not been mapped using +.BR \-map . +See the +.B HFS CREATOR/TYPE +section below for more details. +.TP +.BI \-hfs\-creator " creator" +Set the default CREATOR for all files. Must be exactly 4 characters. See the +.B HFS CREATOR/TYPE +section below for more details. +.TP +.BI \-hfs\-type " type" +Set the default TYPE for all files. Must be exactly 4 characters. See the +.B HFS CREATOR/TYPE +section below for more details. +.TP +.B \-probe +Search the contents of files for all the known Apple/Unix file formats. +See the +.B HFS MACINTOSH FILE FORMATS +section below for more about these formats. +However, the only way to check for +.I MacBinary +and +.I AppleSingle +files is to open and read them, so this option may +increase processing time. It is better to use one or more +.I double dash +options given below if the Apple/Unix formats in use are known. +.TP +.B \-no\-desktop +Do not create (empty) Desktop files. New HFS Desktop files will be created +when the CD is used on a Macintosh (and stored in the System Folder). +By default, empty Desktop files are added to the HFS volume. +.TP +.B \-mac\-name +Use the HFS filename as the starting point for the ISO9660, Joliet and +Rock Ridge filenames. See the +.B HFS MACINTOSH FILENAMES +section below for more information. +.TP +.BI \-boot\-hfs\-file " driver_file" +Installs the +.I driver_file +that +.I may +make the CD bootable on a Macintosh. See the +.B HFS BOOT DRIVER +section below. (Alpha). +.TP +.B \-part +Generate an HFS partition table. By default, no partition table is generated, +but some older Macintosh CD-ROM drivers need an HFS partition table on the +CD-ROM to be able to recognize a hybrid CD-ROM. +.TP +.BI \-auto " AutoStart_file" +Make the HFS CD use the QuickTime 2.0 Autostart feature to launch an +application or document. The given filename must be the name of a document or +application located at the top level of the CD. The filename must be less +than 12 characters. (Alpha). +.TP +.BI \-cluster\-size " size" +Set the size in bytes of the cluster or allocation units of PC Exchange +files. Implies +.BR \-\-exchange . +See the +.B HFS MACINTOSH FILE FORMATS +section below. +.TP +.BI \-hide\-hfs " glob" +Hide +.IR glob , +a shell wildcard pattern, from the HFS volume. The file or directory +will still exist in the ISO9660 and/or Joliet directory. +.I glob +may match any part of the filename. Multiple globs may be excluded. +Example: +.sp + genisoimage \-o rom \-hfs \-hide\-hfs \(aq*.o\(aq \-hide\-hfs foobar +.sp +would exclude all files ending in `.o' or called +.I foobar +from the HFS volume. Note that if you had a directory called +.IR foobar , +it too (and of course all its descendants) would be excluded. The +.I glob +can also be a path name relative to the source directories given on the +command line. Example: +.sp + genisoimage \-o rom \-hfs \-hide\-hfs src/html src +.sp +would exclude just the file or directory called +.I html +from the +.I src +directory. Any other file or directory called +.I html +in the tree will not be excluded. Should be used with +.B \-hide +and/or +.BR \-hide\-joliet . +In order to match a directory name, make sure the pattern does not +include a trailing `/' character. See +.I README.hide +for more details. +.TP +.BI \-hide\-hfs\-list " file" +Specify a file containing a list of wildcard patterns to be hidden as in +.BR \-hide\-hfs . +.TP +.BI \-hfs\-volid " hfs_volid" +Volume name for the HFS partition. This is the name that is +assigned to the disc on a Macintosh and replaces the +.I volid +used with +.BR \-V . +.TP +.B \-icon\-position +Use the icon position information, if it exists, from the Apple/Unix file. +The icons will appear in the same position as they would on a Macintosh +desktop. Folder location and size on screen, its scroll positions, folder +View (view as Icons, Small Icons, etc.) are also preserved. +.\" This option may become set by default in the future. +(Alpha). +.TP +.BI \-root\-info " file" +Set the location, size on screen, scroll positions, folder View etc. for the +root folder of an HFS volume. See +.I README.rootinfo +for more information. (Alpha) +.TP +.BI \-prep\-boot " file" +PReP boot image file. Up to 4 are allowed. See +.I README.prep_boot +for more information. (Alpha) +.TP +.BI \-chrp\-boot +Add CHRP boot header. +.TP +.BI \-input\-hfs\-charset " charset" +Input charset that defines the characters used in HFS filenames when +used with +.BR \-mac\-name . +The default charset is +.I cp10000 +(Mac Roman). See the +.B CHARACTER SETS +and +.B HFS MACINTOSH FILENAMES +sections below for more details. +.TP +.BI \-output\-hfs\-charset " charset" +Output charset that defines the characters that will be used in the HFS +filenames. Defaults to the input charset. See the +.B CHARACTER SETS +section below for more details. +.TP +.B \-hfs\-unlock +By default, +.B genisoimage +will create an HFS volume that is locked. +This option leaves the volume unlocked so that other applications (e.g. +.BR hfsutils ) +can modify the volume. See the +.B HFS PROBLEMS/LIMITATIONS +section below for warnings about using this option. +.TP +.BI \-hfs\-bless " folder_name" +"Bless" the given directory (folder). This is usually the +.I System Folder +and is used in creating HFS bootable CDs. The name of the directory must +be the whole path name as +.B genisoimage +sees it. E.g., if the given pathspec is +.I ./cddata +and the required folder is called +.IR "System Folder" , +the whole path name is +.I \(dq/cddata/System Folder\(dq +(remember to use quotes if the name contains spaces). +.TP +.BI \-hfs\-parms " parameters" +Override certain parameters used to create the HFS filesystem. Unlikely to +be used in normal circumstances. See the +.I libhfs_iso/hybrid.h +source file for details. +.TP +.B \-\-cap +Look for AUFS CAP Macintosh files. Search for CAP Apple/Unix file formats +only. Searching for the other possible Apple/Unix file formats is disabled, +unless other +.I double dash +options are given. +.TP +.B \-\-netatalk +Look for NETATALK Macintosh files +.TP +.B \-\-double +Look for AppleDouble Macintosh files +.TP +.B \-\-ethershare +Look for Helios EtherShare Macintosh files +.TP +.B \-\-ushare +Look for IPT UShare Macintosh files +.TP +.B \-\-exchange +Look for PC Exchange Macintosh files +.TP +.B \-\-sgi +Look for SGI Macintosh files +.TP +.B \-\-xinet +Look for XINET Macintosh files +.TP +.B \-\-macbin +Look for MacBinary Macintosh files +.TP +.B \-\-single +Look for AppleSingle Macintosh files +.TP +.B \-\-dave +Look for Thursby Software Systems DAVE Macintosh files +.TP +.B \-\-sfm +Look for Microsoft's Services for Macintosh files (NT only) (Alpha) +.TP +.B \-\-osx\-double +Look for Mac OS X AppleDouble Macintosh files +.TP +.B \-\-osx\-hfs +Look for Mac OS X HFS Macintosh files +.\" ---------------------------------------- +.SH "CHARACTER SETS" +.B genisoimage +processes filenames in a POSIX-compliant way as strings of 8-bit characters. +To represent all codings for all languages, 8-bit characters are not +sufficient. Unicode or ISO-10646 +define character codings that need at least 21 bits to represent all +known languages. They may be represented with +.IR UTF-32 ", " UTF-16 " or " UTF-8 +coding. UTF-32 uses a plain 32-bit coding but seems to be uncommon. +UTF-16 is used by Microsoft with Win32 with the disadvantage that +16-bit characters are not compliant with the POSIX filesystem +interface. +.PP +Modern Unix operating systems may use UTF-8 coding for filenames. +Each 32-bit character is represented by one or more 8-bit characters. +If a character is coded in +.I ISO-8859-1 +(used in Central Europe and North America) is maps 1:1 to a +UTF-32 or UTF-16 coded Unicode character. +If a character is coded in +.I 7-Bit ASCII +(used in USA and other countries with limited character set) +is maps 1:1 to a UTF-32, UTF-16 or UTF-8 coded Unicode character. +Character codes that cannot be represented as a single byte in UTF-8 +(if the value is > 0x7F) use escape sequences that map to more than +one 8-bit character. +.PP +If all operating systems used UTF-8, +.B genisoimage +would not need to recode characters in filenames. +Unfortunately, Apple uses completely nonstandard codings and Microsoft +uses a Unicode coding that is not compatible with the POSIX filename +interface. +.PP +For all non-UTF-8-coded operating systems, the actual character +that each byte represents depends on the +.I character set +or +.I codepage +(the name used by Microsoft) +used by the local operating system \(em the characters in a character +set will reflect the region or natural language set by the user. +.PP +Usually character codes 0x00-0x1f are control characters, codes 0x20-0x7f +are the 7-bit ASCII characters and (on PCs and Macs) 0x80-0xff are used +for other characters. +.PP +As there are a lot more than 256 characters/symbols in use, only a small +subset are represented in a character set. Therefore the same character code +may represent a different character in different character sets. So a filename +generated, say in central Europe, may not display the same character +when viewed on a machine in, say eastern Europe. +.PP +To make matters more complicated, different operating systems use +different character sets for the region or language. For example, the +character code for `\('e' (small e with acute accent) +may be character code 0x82 on a PC, +code 0x8e on a Macintosh, code 0xe9 on a Unix system in western Europe, +and code 0x000e9 in Unicode. +.PP +As long as not all operating systems and applications use the same +character set as the basis for filenames, it may be +necessary to specify which character set your filenames use in and which +character set the filenames should appear on the CD. +.PP +There are four options to specify the character sets you want to use: +.TP +.B \-input\-charset +Defines the local character set you are using on your host machine. +Any character set conversions that take place will use this character +set as the starting point. The default input character sets are +.I cp437 +on MS-DOS-based systems and +.I iso8859-1 +on all other systems. If +.B \-J +is given, the Unicode equivalents of the input character set +will be used in the Joliet directory. +.B \-jcharset +is the same as +.BR "\-input\-charset \-J" . +.TP +.B \-output\-charset +Defines the character set that will be used with for the Rock Ridge names +on the CD. Defaults to the input character set. +.TP +.B \-input\-hfs\-charset +Defines the HFS character set used for HFS filenames decoded from +any of the various Apple/Unix file formats. Only useful when used with +.BR \-mac\-name . +See the +.B HFS MACINTOSH FILENAMES +for more information. Defaults to +.I cp10000 +(Mac Roman). +.TP +.B \-output\-hfs\-charset +Defines the HFS character set used to create HFS filenames from the input +character set in use. In most cases this will be from the character set +given with +.BR \-input\-charset . +Defaults to the input HFS character set. +.PP +There are a number of character sets built in to +.BR genisoimage . +To get a listing, use +.BR "\-input\-charset help" . +This list doesn't include the charset derived from the current locale, +if +.B genisoimage +is built with +.I iconv +support. +.PP +Additional character sets can be read from file for any of the character +set options by giving a filename as the argument to the options. The given +file will only be read if its name does not match one of the built-in +character sets. +.PP +The format of the character set files is the same as the mapping files +available from +.IR http://www.unicode.org/Public/MAPPINGS . +This format is: +.IP +Column #1 is the input byte code (in hex as 0xXX) +.br +Column #2 is the Unicode (in hex as 0xXXXX) +.br +The rest of the line is ignored. +.PP +Any blank line, line without two (or more) columns in the above format +or comments lines (starting with the # character) are ignored without any +warnings. Any missing input code is mapped to Unicode character 0x0000. +.PP +Note that, while UTF-8 is supported, other Unicode encodings such as +UCS-2/UTF-16 and UCS-4/UTF-32 are not, as POSIX operating systems +cannot handle them natively. +.PP +A 1:1 character set mapping can be defined by using the keyword +.I default +as the argument to any of the character set options. This is the behaviour +of old versions of +.BR mkisofs . +.PP +The ISO9660 filenames generated from the input filenames are not converted +from the input character set. The ISO9660 character set is a very limited +subset of the ASCII characters, so any conversion would be pointless. +.PP +Any character that +.B genisoimage +cannot convert will be replaced with a `_' character. +.\" ---------------------------------------- +.SH "HFS CREATOR/TYPE" +A Macintosh file has two properties associated with it which define +which application created the file, the +.I CREATOR +and what data the file contains, the +.IR TYPE . +Both are (exactly) 4 letter strings. Usually this +allows a Macintosh user to double-click on a file and launch the correct +application etc. The CREATOR and TYPE of a particular file can be found by +using something like ResEdit (or similar) on a Macintosh. +.PP +The CREATOR and TYPE information is stored in all the various Apple/Unix +encoded files. +For other files it is possible to base the CREATOR and TYPE on the +filename's extension using a +.I mapping +file (with +.BR \-map ) +and/or using the +.I magic number +(usually a +.I signature +in the first few bytes) of a file (with +.BR \-magic ). +If both these options are given, their order on the command +line is significant. If +.B \-map +is given first, a filename extension match is attempted +before a magic number match. However, if +.B \-magic +is given first, a magic number match is attempted before a +filename extension match. +.PP +If a mapping or magic file is not used, or no match is found, the default +CREATOR and TYPE for all regular files can be set by using entries in the +.I .genisoimagerc +file or using +.B \-hfs\-creator +and/or +.BR \-hfs\-type , +otherwise the default CREATOR and TYPE are +.IR Unix " and " TEXT . +.PP +The format of the +.I mapping +file is the same +.I afpfile +format as used by +.BR aufs . +This file has five columns for the +.IR extension , +.IR "file translation" , +.IR CREATOR , +.IR TYPE " and" +.IR Comment . +Lines starting with the `#' character are +comment lines and are ignored. An example file would be like: +.PP +.TS +tab (/); +l s s s s +l s s s s +l l l l l . +# Example filename mapping file +# +# EXTN/XLate/CREATOR/TYPE/Comment +\&.tif/Raw/\(aq8BIM\(aq/\(aqTIFF\(aq/\(dqPhotoshop TIFF image\(dq +\&.hqx/Ascii/\(aqBnHq\(aq/\(aqTEXT\(aq/\(dqBinHex file\(dq +\&.doc/Raw/\(aqMSWD\(aq/\(aqWDBN\(aq/\(dqWord file\(dq +\&.mov/Raw/\(aqTVOD\(aq/\(aqMooV\(aq/\(dqQuickTime Movie\(dq +*/Ascii/\(aqttxt\(aq/\(aqTEXT\(aq/\(dqText file\(dq +.TE +.PP +Where: +.IP +The first column +.I EXTN +defines the Unix filename extension to be +mapped. The default mapping for any filename extension that doesn't +match is defined with the `*' character. +.IP +The +.I Xlate +column defines the type of text translation between the Unix and +Macintosh file it is ignored by +.BR genisoimage , +but is kept to be compatible with +.BR aufs (1). +Although +.B genisoimage +does not alter the contents of a file, if a binary file has its TYPE +set as +.IR TEXT ", it " may +be read incorrectly on a Macintosh. Therefore a better choice for the +default TYPE may be +.IR ???? . +.IP +The +.I CREATOR +and +.I TYPE +keywords must be 4 characters long and enclosed in single quotes. +.IP +The comment field is enclosed in double quotes \(em it is ignored by +.BR genisoimage , +but is kept to be compatible with +.BR aufs . +.PP +The format of the +.I magic +file is almost identical to the +.BR magic (5) +file used by the +.BR file (1) +command. +.PP +This file has four tab-separated columns for the +.IR "byte offset" , +.IR type , +.I test +and +.IR message . +Lines starting with the `#' character are +comment lines and are ignored. An example file would be like: +.PP +.TS +tab (/); +l s s s +l s s s +l l l l . +# Example magic file +# +# off/type/test/message +0/string/GIF8/8BIM GIFf GIF image +0/beshort/0xffd8/8BIM JPEG image data +0/string/SIT!/SIT! SIT! StuffIt Archive +0/string/\(rs037\(rs235/LZIV ZIVU standard Unix compress +0/string/\(rs037\(rs213/GNUz ZIVU gzip compressed data +0/string/%!/ASPS TEXT Postscript +0/string/\(rs004%!/ASPS TEXT PC Postscript with a ^D to start +4/string/moov/txtt MooV QuickTime movie file (moov) +4/string/mdat/txtt MooV QuickTime movie file (mdat) +.TE +.PP +The format of the file is described in +.BR magic (5). +The only difference here is that for each entry in the magic file, the +.I message +for the initial offset must be be 4 characters for the CREATOR followed +by 4 characters for the TYPE \(em white space is +optional between them. Any other characters on this line are ignored. +Continuation lines (starting with a `>') are also ignored, i.e., only +the initial offset lines are used. +.PP +Using +.B \-magic +may significantly increase processing time as each file has to opened +and read to find its magic number. +.PP +In summary, for all files, the default CREATOR is +.I Unix +and the default TYPE is +.IR TEXT . +These can be changed by using entries in the +.I .genisoimagerc +file or by using +.B \-hfs\-creator +and/or +.BR \-hfs\-type . +.PP +If the a file is in one of the known Apple/Unix formats (and the format +has been selected), the CREATOR and TYPE are taken from the values +stored in the Apple/Unix file. +.PP +Other files can have their CREATOR and TYPE set from their filename +extension (with +.BR \-map ), +or their magic number (with +.BR \-magic ). +If the default match is used in the +.I mapping +file, these values override the default CREATOR and TYPE. +.PP +A full CREATOR/TYPE database can be found at +.IR http://www.angelfire.com/il/szekely/ . +.\" ---------------------------------------- +.SH "HFS MACINTOSH FILE FORMATS" +Macintosh files have two parts called the +.I Data +and +.IR "Resource fork" . +Either may be empty. Unix (and many other OSs) can only +cope with files having one part (or fork). To add to this, Macintosh files +have a number of attributes associated with them \(em probably the most +important are the TYPE and CREATOR. Again, Unix has no concept of these +types of attributes. +.PP +E.g., a Macintosh file may be a JPEG image where the image is stored in the +Data fork and a desktop thumbnail stored in the Resource fork. It is usually +the information in the data fork that is useful across platforms. +.PP +Therefore to store a Macintosh file on a Unix filesystem, a way has to be +found to cope with the two forks and the extra attributes (which are +referred to as the +.IR "Finder info" ). +Unfortunately, it seems that every software package that stores Macintosh +files on Unix has chosen a completely different storage method. +.PP +The Apple/Unix formats that +.B genisoimage +(partially) supports are: +.IP "CAP AUFS format" +Data fork stored in a file. Resource fork in subdirectory +.I .resource +with same filename as data fork. Finder info in subdirectory +.I .finderinfo +with same filename. +.IP "AppleDouble/Netatalk" +Data fork stored in a file. Resource fork stored in a file with +same name prefixed with `%'. Finder info also stored in same +`%' file. Netatalk uses the same format, but the resource +fork/Finder info stored in subdirectory +.I .AppleDouble +with same filename as data fork. +.IP AppleSingle +Data structures similar to above, except both forks and Finder +info are stored in one file. +.IP "Helios EtherShare" +Data fork stored in a file. Resource fork and Finder info together in +subdirectory +.I .rsrc +with same filename as data fork. +.IP "IPT UShare" +Like the EtherShare format, but the Finder info +is stored slightly differently. +.IP MacBinary +Both forks and Finder info stored in one file. +.IP "Apple PC Exchange" +Used by Macintoshes to store Apple files on DOS (FAT) disks. +Data fork stored in a file. Resource fork in subdirectory +.IR resource.frk " (or " RESOURCE.FRK ). +Finder info as one record in file +.IR finder.dat " (or " FINDER.DAT ). +Separate +.I finder.dat +for each data fork directory. +.IP +Note: +.B genisoimage +needs to know the native FAT cluster size of the disk that the PC Exchange +files are on (or have been copied from). This size is given by +.BR \-cluster\-size . +The cluster or allocation size can be found by using the DOS utility +.BR chkdsk . +.IP +May not work with PC Exchange v2.2 or higher files (available with MacOS 8.1). +DOS media containing PC Exchange files should be mounted as type +.I msdos +(not +.IR vfat ) +when using Linux. +.IP SGI/XINET +Used by SGI machines when they mount HFS disks. Data fork stored +in a file. Resource fork in subdirectory +.I .HSResource +with same filename. Finder info as one record in file +.IR .HSancillary ". Separate " .HSancillary +for each data fork directory. +.IP "Thursby Software Systems DAVE" +Allows Macintoshes to store Apple files on SMB servers. +Data fork stored in a file. Resource fork in subdirectory +.IR resource.frk . +Uses the AppleDouble format to store resource fork. +.IP "Services for Macintosh" +Format of files stored by NT Servers on NTFS filesystems. Data fork is +stored as +.IR filename . +Resource fork stored as a NTFS stream called +.IR filename:AFP_Resource . +The Finder info is stored as a NTFS stream called +.IR filename:Afp_AfpInfo . +NTFS streams are normally invisible to the user. +.IP +Warning: +.B genisoimage +only partially supports the SFM format. If an HFS file +or folder stored on the NT server contains an illegal +NT character in its name, NT converts these characters to +.I Private Use Unicode +characters. The characters are: \(dq * / < > ? \(rs | and a space or +period if it is the last character of the filename, character codes 0x01 +to 0x1f (control characters) and Apple's apple logo. +.IP +Unfortunately, these private Unicode characters are not readable by the +.B genisoimage +NT executable. Therefore any file or directory +name containing these characters will be ignored \(em including the contents of +any such directory. +.IP "Mac OS X AppleDouble" +When HFS/HFS+ files are copied or saved by Mac OS X on to a non-HFS +filesystem (e.g. UFS, NFS etc.), the files are stored in AppleDouble format. +Data fork stored in a file. Resource fork stored in a file with +same name prefixed with `._'. Finder info also stored in same `._' file. +.IP "Mac OS X HFS (Alpha)" +Not really an Apple/Unix encoding, but actual HFS/HFS+ files on a Mac\ OS\ X +system. Data fork stored in a file. Resource fork stored in a pseudo file +with the same name with the suffix +.IR /rsrc . +The Finder info is only available via a Mac OS X library call. +.IP +See also +.IR README.macosx . +.IP +Only works when used on Mac OS X. +.IP +If a file is found with a zero +length resource fork and empty finderinfo, it is assumed not to have +any Apple/Unix encoding \(em therefore a TYPE and CREATOR can be set using +other methods. +.PP +.B genisoimage +will attempt to set the CREATOR, TYPE, date and possibly other flags from +the finder info. Additionally, if it exists, the Macintosh filename is set +from the finder info, otherwise the Macintosh name is based on the Unix +filename \(em see the +.B HFS MACINTOSH FILENAMES +section below. +.PP +When using +.BR \-apple , +the TYPE and CREATOR are stored in the optional System Use or +.I SUSP +field +in the ISO9660 Directory Record \(em in much the same way as the Rock Ridge +attributes are. In fact to make life easy, the Apple extensions are added +at the beginning of the existing Rock Ridge attributes (i.e., to get the Apple +extensions you get the Rock Ridge extensions as well). +.PP +The Apple extensions require the resource fork to be stored as an ISO9660 +.I associated +file. This is just like any normal file stored in the ISO9660 filesystem +except that the associated file flag is set in the Directory Record (bit +2). This file has the same name as the data fork (the file seen by +non-Apple machines). Associated files are normally ignored by other OSs +.PP +When using +.BR \-hfs , +the TYPE and CREATOR plus other finder info, are stored in a separate +HFS directory, not visible on the ISO9660 volume. The HFS directory references +the same data and resource fork files described above. +.PP +In most cases, it is better to use +.B \-hfs +instead of +.BR \-apple , +as the latter imposes the limited ISO9660 characters allowed in +filenames. However, the Apple extensions do give the advantage that the +files are packed on the disk more efficiently and it may be possible to fit +more files on a CD. +.\" ---------------------------------------- +.SH "HFS MACINTOSH FILENAMES" +Where possible, the HFS filename that is stored with an Apple/Unix file +is used for the HFS part of the CD. However, not all the Apple/Unix +encodings store the HFS filename with the finderinfo. In these cases, +the Unix filename is used \(em with escaped special characters. Special +characters include `/' and characters with codes over 127. +.PP +AUFS escapes these characters by using `:' followed by the character code +as two hex digits. Netatalk and EtherShare have a similar scheme, but uses +`%' instead of a `:'. +.PP +If +.B genisoimage +cannot find an HFS filename, it uses the Unix name, with any +.IR %xx " or " :xx +characters +.RI ( xx +are two hex digits) converted to a single character code. If +.I xx +are not hex digits ([0-9a-fA-F]), they are +left alone \(em although any remaining `:' is converted to `%', as `:' +is the HFS directory separator. Care must be taken, as an ordinary Unix +file with +.I %xx +or +.I :xx +will also be converted. e.g. +.PP +.TS +l l +l s +l l +l s +l l . +This:2fFile converted to This/File + +This:File converted to This%File + +This:t7File converted to This%t7File +.TE +.PP +Although HFS filenames appear to support uppercase and lowercase letters, +the filesystem is case-insensitive, i.e., the filenames +.IR aBc " and " AbC +are the same. If a file is found in a directory with the same HFS name, +.B genisoimage +will attempt to make a unique name by adding `_' characters +to one of the filenames. +.PP +If an HFS filename exists for a file, +.B genisoimage +can use this name as the starting point for the ISO9660, Joliet and +Rock Ridge filenames using +.BR \-mac\-name . +Normal Unix files without an HFS name will still use their Unix name. +e.g. +.PP +If a MacBinary (or PC Exchange) file is stored as +.I someimage.gif.bin +on the Unix filesystem, but contains a HFS file called +.IR someimage.gif , +this is the name that would appear on the HFS part of the CD. However, as +.B genisoimage +uses the Unix name as the starting point for the other names, +the ISO9660 name generated will probably be +.I SOMEIMAG.BIN +and the Joliet/Rock Ridge would be +.IR someimage.gif.bin . +This option will use +the HFS filename as the starting point and the ISO9660 name will probably be +.I SOMEIMAG.GIF +and the Joliet/Rock Ridge would be +.IR someimage.gif . +.PP +.B \-mac\-name +will not currently work with +.B \-T +\(em the Unix name will be used in the +.I TRANS.TBL +file, not the Macintosh name. +.PP +The character set used to convert any HFS filename to a Joliet/Rock Ridge +filename defaults to +.I cp10000 +(Mac Roman). +The character set used can be specified using +.BR \-input\-hfs\-charset . +Other built-in HFS character sets are: +.I cp10006 +(MacGreek), +.I cp10007 +(MacCyrillic), +.I cp10029 +(MacLatin2), +.I cp10079 +(MacIcelandandic) and +.I cp10081 +(MacTurkish). +.PP +Note: the character codes used by HFS filenames taken from the various +Apple/Unix formats will not be converted as they are assumed to be in the +correct Apple character set. Only the Joliet/Rock Ridge names derived from +the HFS filenames will be converted. +.PP +The existing +.B genisoimage +code will filter out any illegal characters for the ISO9660 and Joliet +filenames, but as +.B genisoimage +expects to be dealing directly with Unix names, it leaves the Rock +Ridge names as is. But as `/' is a legal HFS filename character, +.B \-mac\-name +converts `/' to a `_' in Rock Ridge filenames. +.PP +If the Apple extensions are used, only the ISO9660 filenames will +appear on the Macintosh. However, as the Macintosh ISO9660 drivers can use +.I Level 2 +filenames, you can use options like +.B \-allow\-multidot +without problems on +a Macintosh \(em still take care over the names, for example +.I this.file.name +will be converted to +.I THIS.FILE +i.e. only have one `.', also filename +.I abcdefgh +will be seen as +.I ABCDEFGH +but +.I abcdefghi +will be seen as +.I ABCDEFGHI. +i.e. with a `.' at the end \(em don't know if this is a Macintosh +problem or a +.BR genisoimage / mkhybrid +problem. All filenames will be in uppercase +when viewed on a Macintosh. Of course, DOS/Win3.X machines will not be able +to see Level 2 filenames... +.\" ---------------------------------------- +.SH "HFS CUSTOM VOLUME/FOLDER ICONS" +To give a HFS CD a custom icon, make sure the root (top level) folder includes +a standard Macintosh volume icon file. To give a volume a custom icon on +a Macintosh, an icon has to be pasted over the volume's icon in the "Get Info" +box of the volume. This creates an invisible file called +.I Icon\(rsr +(`\(rsr' is the carriage return character) in the root folder. +.P +A custom folder icon is very similar \(em an invisible file called +.I Icon\(rsr +exists in the folder itself. +.P +Probably the easiest way to create a custom icon that +.B genisoimage +can use is to format a blank HFS floppy disk on a Mac and paste an icon +to its "Get Info" box. If using Linux with the HFS module installed, +mount the floppy: +.IP +mount \-t hfs /dev/fd0 /mnt/floppy +.PP +The floppy will be mounted as a CAP filesystem by default. Then run +.B genisoimage +using something like: +.IP +genisoimage \-\-cap \-o output source_dir /mnt/floppy +.PP +If you are not using Linux, you can use +.B hfsutils +to copy the icon file from the floppy. However, care has to be taken, +as the icon file contains a control character. For example: +.IP +hmount /dev/fd0 +.br +hdir \-a +.br +hcopy \-m Icon^V^M icon_dir/icon +.PP +Where `^V^M' is control-V followed by control-M. Then run +.B genisoimage +by using something like: +.IP +genisoimage \-\-macbin \-o output source_dir icon_dir +.PP +The procedure for creating/using custom folder icons is very similar \(em paste +an icon to folder's "Get Info" box and transfer the resulting +.I Icon\(rsr +file to the relevant directory in the +.B genisoimage +source tree. +.PP +You may want to hide the icon files from the ISO9660 and Joliet trees. +.PP +To give a custom icon to a Joliet CD, follow the instructions found at +.IR http://www.cdrfaq.org/faq03.html#S3-21-1 . +.\" ---------------------------------------- +.SH "HFS BOOT DRIVER" +It +.I may +be possible to make the hybrid CD bootable on a Macintosh. +.PP +A bootable HFS CD requires an Apple CD-ROM (or compatible) driver, a bootable +HFS partition and the necessary System, Finder, etc. files. +.PP +A driver can be obtained from any other Macintosh bootable CD-ROM using the +.B apple_driver +utility. This file can then be used with +.BR \-boot\-hfs\-file . +.PP +The HFS partition (i.e. the hybrid disk in our case) must contain a +suitable System Folder, again from another CD-ROM or disk. +.PP +For a partition to be bootable, it must have its +.I boot block +set. The boot +block is in the first two blocks of a partition. For a non-bootable partition +the boot block is full of zeros. Normally, when a System file is copied to +partition on a Macintosh disk, the boot block is filled with a number of +required settings \(em unfortunately I don't know the full spec for the boot +block, so I'm guessing that the following will work. +.PP +Therefore, the utility +.B apple_driver +also extracts the boot block from the +first HFS partition it finds on the given CD-ROM and this is used for the +HFS partition created by +.BR genisoimage . +.PP +.I Please note: +By using a driver from an Apple CD and copying Apple software to your CD, +you become liable to obey Apple Computer, Inc. Software License Agreements. +.\" ---------------------------------------- +.SH "EL TORITO BOOT INFORMATION TABLE" +When +.B \-boot\-info\-table +is given, +.B genisoimage +will modify the boot file specified by +.B \-b +by inserting a 56-byte +.I boot information table +at offset 8 in +the file. This modification is done in the source filesystem, so make +sure you use a copy if this file is not easily recreated! This file +contains pointers which may not be easily or reliably obtained at boot +time. +.PP +The format of this table is as follows; all integers are in +section 7.3.1 ("little endian") format. +.sp +.RS +.2i +.ta 1.0i 2.5i 3.5i +.nf +Offset Name Size Meaning + 8 bi_pvd 4 bytes LBA of primary volume descriptor +12 bi_file 4 bytes LBA of boot file +16 bi_length 4 bytes Boot file length in bytes +20 bi_csum 4 bytes 32-bit checksum +24 bi_reserved 40 bytes Reserved +.fi +.RE +.IP +The 32-bit checksum is the sum of all the 32-bit words in the boot +file starting at byte offset 64. All linear block addresses (LBAs) +are given in CD sectors (normally 2048 bytes). +.\" ---------------------------------------- +.SH "HPPA NOTES" +To make a bootable CD for HPPA, at the very least a boot loader file +.RB ( \-hppa\-bootloader ), +a kernel image file (32-bit, 64-bit, or both, depending on hardware) +and a boot command line +.RB ( \-hppa\-cmdline ) +must be specified. Some systems can boot either a 32- or a 64-bit +kernel, and the firmware will choose one if both are present. +Optionally, a ramdisk can be used for the root filesystem using +.BR \-hppa\-cmdline . +.\" ---------------------------------------- +.SH "JIGDO NOTES" +Jigdo is a tool to help in the distribution of large files like CD and +DVD images; see +.I http://atterer.org/jigdo/ +for more details. Debian CDs and DVD ISO +images are published on the web in jigdo format to allow end users to download +them more efficiently. +.PP +To create jigdo and template files alongside the ISO image from +.BR genisoimage , +you must first generate a list of the files that will be +used, in the following format: +.sp +.RS +.2i +.ta 2.0i 2.0i 5.0i +.nf +MD5sum File size Path +32 chars 12 chars to end of line +.fi +.RE +.IP +.PP +The MD5sum must be written in standard hexadecimal notation, the +file size must list the size of the file in bytes, and the path +must list the absolute path to the file. For example: +.sp +.nf +00006dcd58ff0756c36d2efae21be376 14736 /mirror/debian/file1 +000635c69b254a1be8badcec3a8d05c1 211822 /mirror/debian/file2 +00083436a3899a09633fc1026ef1e66e 22762 /mirror/debian/file3 +.fi +.PP +Once you have this file, call +.B genisoimage +with all of your normal command-line parameters. Specify the output +filenames for the jigdo and template files using +.BR \-jigdo\-jigdo " and " \-jigdo\-template , +and pass in the location of your MD5 list with +.BR \-md5\-list . +.PP +If there are files that you do NOT want to be added into the jigdo +file (e.g. if they are likely to change often), specify them using +\-jigdo\-exclude. If you want to verify some of the files as they are +written into the image, specify them using \-jigdo\-force\-md5. If any +files don't match, +.B genisoimage +will then abort. Both of these options take +regular expressions as input. It is possible to restrict the set of +files that will be used further based on size \(em use the +\-jigdo\-min\-file\-size option. +.PP +Finally, the jigdo code needs to know how to map the files it is given +onto a mirror-style configuration. Specify how to map paths using +.BR \-jigdo\-map . +Using +.I Debian=/mirror/debian +will cause all +paths starting with +.I /mirror/debian +to be mapped to +.I Debian:<file> +in the output jigdo file. +.\" ---------------------------------------- +.SH EXAMPLES +.PP +To create a vanilla ISO9660 filesystem image in the file +.IR cd.iso , +where the directory +.I cd_dir +will become the root directory of the CD, call: +.IP +% genisoimage \-o cd.iso cd_dir +.PP +To create a CD with Rock Ridge extensions of +the source directory +.IR cd_dir : +.IP +% genisoimage \-o cd.iso \-R cd_dir +.PP +To create a CD with Rock Ridge extensions of +the source directory +.I cd_dir +where all files have at least read permission and all files +are owned by +.IR root , +call: +.IP +% genisoimage \-o cd.iso \-r cd_dir +.PP +To write a tar archive directly to a CD that will later contain a simple +ISO9660 filesystem with the tar archive call: +.IP +% tar cf \- . | genisoimage \-stream\-media\-size 333000 | \(rs +.br + wodim dev=b,t,l \-dao tsize=333000s \- +.PP +To create a HFS hybrid CD with the Joliet and Rock Ridge extensions of +the source directory +.IR cd_dir : +.IP +% genisoimage \-o cd.iso \-R \-J \-hfs cd_dir +.PP +To create a HFS hybrid CD from the source directory +.I cd_dir +that contains +Netatalk Apple/Unix files: +.IP +% genisoimage \-o cd.iso \-\-netatalk cd_dir +.PP +To create a HFS hybrid CD from the source directory +.IR cd_dir , +giving all files +CREATOR and TYPES based on just their filename extensions listed in the file +"mapping".: +.IP +% genisoimage \-o cd.iso \-map mapping cd_dir +.PP +To create a CD with the Apple Extensions to ISO9660, from the source +directories +.I cd_dir +and +.IR another_dir . +Files in all the known Apple/Unix format +are decoded and any other files are given CREATOR and TYPE based on their +magic number given in the file +.IR magic : +.IP +% genisoimage \-o cd.iso \-apple \-magic magic \-probe \(rs +.br + cd_dir another_dir +.PP +The following example puts different files on the CD that all have +the name README, but have different contents when seen as a +ISO9660/Rock Ridge, Joliet or HFS CD. +.PP +Current directory contains: +.IP +% ls \-F +.br +README.hfs README.joliet README.Unix cd_dir/ +.PP +The following command puts the contents of the directory +.I cd_dir +on the +CD along with the three README files \(em but only one will be seen from +each of the three filesystems: +.IP +% genisoimage \-o cd.iso \-hfs \-J \-r \-graft\-points \(rs +.br + \-hide README.hfs \-hide README.joliet \(rs +.br + \-hide\-joliet README.hfs \-hide\-joliet README.Unix \(rs +.br + \-hide\-hfs README.joliet \-hide\-hfs README.Unix \(rs +.br + README=README.hfs README=README.joliet \(rs +.br + README=README.Unix cd_dir +.PP +i.e. the file README.hfs will be seen as README on the HFS CD and the +other two README files will be hidden. Similarly for the Joliet and +ISO9660/Rock Ridge CD. +.PP +There are probably all sorts of strange results possible with +combinations of the hide options ... +.\" ---------------------------------------- +.SH NOTES +.PP +.B genisoimage +may safely be installed suid root. This may be needed to allow +.B genisoimage +to read the previous session when creating a multisession image. +.PP +If +.B genisoimage +is creating a filesystem image with Rock Ridge attributes and the +directory nesting level of the source directory tree is too much +for ISO9660, +.B genisoimage +will do deep directory relocation. +This results in a directory called +.B RR_MOVED +in the root directory of the CD. You cannot avoid this directory. +.PP +Many boot code options for different platforms are mutualy exclusive because +the boot blocks cannot coexist, ie. different platforms share the same data +locations in the image. See +http://lists.debian.org/debian-cd/2006/12/msg00109.html for details. +.\" ---------------------------------------- +.SH BUGS +.PP +Any files that have hard links to files not in the tree being copied to the +ISO9660 filesystem will have an incorrect file reference count. +.PP +Does not check for SUSP record(s) in `.' entry of the +root directory to verify the existence of Rock Ridge +enhancements. +This problem is present when reading old sessions while +adding data in multisession mode. +.PP +Does not properly read relocated directories in multisession +mode when adding data. +Any relocated deep directory is lost if the new session does not +include the deep directory. +.\" Repeat by: create first session with deep directory relocation +.\" then add new session with a single dir that differs from the +.\" old deep path. +.PP +Does not re-use +.I RR_MOVED +when doing multisession from +.IR TRANS.TBL . +.PP +Does not create whole_name entry for +.I RR_MOVED +in multisession mode. +.PP +There may be other bugs. Please, report them to the maintainers. +.\" ---------------------------------------- +.SH "HFS PROBLEMS/LIMITATIONS" +I have had to make several assumptions on how I expect the modified +libhfs routines to work, however there may be situations that either +I haven't thought of, or come across when these assumptions fail. +Therefore I can't guarantee that +.B genisoimage +will work as expected +(although I haven't had a major problem yet). Most of the HFS features work +fine, but some are not fully tested. These are marked as +.I Alpha +above. +.PP +Although HFS filenames appear to support uppercase and lowercase letters, +the filesystem is case-insensitive, i.e., the filenames +.IR aBc " and "AbC +are the same. If a file is found in a directory with the same HFS name, +.B genisoimage +will attempt to make a unique name by adding `_' characters +to one of the filenames. +.PP +HFS file/directory names that share the first 31 characters have +`_N' (a decimal number) substituted for the last few characters +to generate unique names. +.PP +Care must be taken when "grafting" Apple/Unix files or directories (see +above for the method and syntax involved). It is not possible to use a +new name for an Apple/Unix encoded file/directory. e.g. If a Apple/Unix +encoded file called +.I oldname +is to added to the CD, you cannot use the command line: +.IP +genisoimage \-o output.raw \-hfs \-graft\-points newname=oldname cd_dir +.PP +.B genisoimage +will be unable to decode +.IR oldname . +However, you can graft +Apple/Unix encoded files or directories as long as you do not attempt to +give them new names as above. +.PP +When creating an HFS volume with the multisession options, +.B \-M +and +.BR \-C , +only files in the last session will be in the HFS volume. i.e. +.B genisoimage +cannot +.I add +existing files from previous sessions to the HFS volume. +.PP +However, if each session is created with +.BR \-part , +each session will appear as +separate volumes when mounted on a Mac. In this case, it is worth using +.BR \-V " or " \-hfs\-volid +to give each session a unique volume name, +otherwise each "volume" will appear on the Desktop with the same name. +.PP +Symbolic links (as with all other non-regular files) are not added to +the HFS directory. +.PP +Hybrid volumes may be larger than pure ISO9660 volumes +containing the same data. In some cases (e.g. DVD sized volumes) the +difference can be significant. As an HFS volume gets bigger, so does the +allocation block size (the smallest amount of space a file can occupy). +For a 650MB CD, the allocation block is 10kB, for a 4.7GB DVD it will be +about 70kB. +.PP +The maximum number of files in an HFS volume is about 65500 \(em although +the real limit will be somewhat less than this. +.PP +The resulting hybrid volume can be accessed on a Unix machine by using +the hfsutils routines. However, no changes can be made to the volume as it +is set as +.B locked. +The option +.B \-hfs\-unlock +will create an output image that is unlocked \(em however no changes should be +made to the contents of the volume (unless you really know what you are +doing) as it's not a "real" HFS volume. +.PP +.B \-mac\-name +will not currently work with +.B \-T +\(em the Unix name will be used in the +.I TRANS.TBL +file, not the Macintosh name. +.PP +Although +.B genisoimage +does not alter the contents of a file, if a binary file has its TYPE +set as +.IR TEXT ", it " may +be read incorrectly on a Macintosh. Therefore a better choice for the +default TYPE may be +.IR ???? . +.PP +.B \-mac\-boot\-file +may not work at all... +.PP +May not work with PC Exchange v2.2 or higher files (available with MacOS 8.1). +DOS media containing PC Exchange files should be mounted as type +.B msdos +(not +.BR vfat ) +when using Linux. +.PP +The SFM format is only partially supported \(em see +.B HFS MACINTOSH FILE FORMATS +section above. +.PP +It is not possible to use +.BR \-sparc\-boot " or " \-generic\-boot " with" +.BR \-boot\-hfs\-file " or " \-prep\-boot . +.PP +.B genisoimage +should be able to create HFS hybrid images over 4Gb, although this has not +been fully tested. +.\" ---------------------------------------- +.SH "SEE ALSO" +.BR genisoimagerc (5), +.BR wodim (1), +.BR mkzftree (8), +.BR magic (5). +.\" ---------------------------------------- +.SH AUTHORS +.B genisoimage +is derived from +.B mkisofs +from the +.B cdrtools 2.01.01a08 +package from May 2006 (with few updates extracted from cdrtools 2.01.01a24 from +March 2007) from .IR http://cdrecord.berlios.de/ , +but is now part of the +.B cdrkit +suite, maintained by Joerg Jaspert, Eduard Bloch, Steve McIntyre, Peter +Samuelson, Christian Fromme, Ben Hutchings, and other contributors. +The maintainers can be contacted at +.IR debburn-devel@lists.alioth.debian.org , +or see the +.B cdrkit +project web site at +.IR http://www.cdrkit.org/ . +.PP +Eric Youngdale wrote the first versions (1993\(en1998) of +.BR mkisofs . +J\(:org Schilling wrote the SCSI transport library and its +interface, and has maintained +.B mkisofs +since 1999. James Pearson wrote the HFS hybrid code, using +.I libhfs +by Robert Leslie. Pearson, Schilling, Jungshik Shin and Jaakko +Heinonen contributed to the character set conversion code. The +.B cdrkit +maintainers have maintained +.B genisoimage +since 2006. +.PP +.nf +Copyright 1993-1998 by Yggdrasil Computing, Inc. +Copyright 1996-1997 by Robert Leslie +Copyright 1997-2001 by James Pearson +Copyright 1999-2006 by J\(:org Schilling +Copyright 2007 by J\(:org Schilling (originating few updates) +Copyright 2002-2003 by Jungshik Shin +Copyright 2003 by Jaakko Heinonen +Copyright 2006 by the Cdrkit maintainers +.fi +.PP +If you want to take part in the development of +.BR genisoimage , +you may join the +.B cdrkit +developer mailing list by following the instructions on +.IR http://alioth.debian.org/mail/?group_id=31006 . +The email address of the list is +.IR debburn-devel@lists.alioth.debian.org . +This is also the address for user support questions. Note that +.BR cdrkit " and " cdrtools +are not affiliated. +.PP +.\" ---------------------------------------- +.SH ACKNOWLEDGEMENTS +UNIX is a registered trademark of The Open Group in the US and other countries. |