.\"
.\" Copyright (c) 2006, Sun Microsystems, Inc.
.\" Copyright 2021 Oxide Computer Company
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.Dd March 30, 2022
.Dt HSFS 4FS
.Os
.Sh NAME
.Nm hsfs
.Nd High Sierra & ISO 9660 CD-ROM file system
.Sh DESCRIPTION
.Nm
is a file system type that allows users to access files on High Sierra or ISO
9660 format CD-ROM disks from within the SunOS operating system.
Once mounted, a
.Nm
file system provides standard read-only file system operations and semantics,
meaning that you can read and list files in a directory on a High Sierra or ISO
9660 CD-ROM and applications can use standard UNIX system calls on these files
and directories.
.Pp
This file system contains support for Rock Ridge, ISO 9660 Version 2 and Joliet
extensions.
These extensions provide support for file names with a length of at least 207
bytes, but only Rock Ridge extensions
.Pq with the exception of writability and hard links
can provide file system semantics and file types as they are found in UFS.
The presence of Rock Ridge, ISO 9660 Version 2, and Joliet is autodetected and
the best-suitable available extension is used by the HSFS driver for file name
and attribute lookup.
.Pp
If your
.Pa /etc/vfstab
file contains a line similar to the following:
.Bd -literal
/dev/dsk/c0t6d0s0 - /hsfs hsfs - no ro
.Ed
.Pp
and
.Pa /hsfs
exists, you can mount an
.Nm
file system with either of the following commands:
.Bd -literal -offset indent
mount -F hsfs -o ro device-special directory-name
.Ed
or
.Bd -literal -offset indent
mount /hsfs
.Ed
.Pp
By default, Rock Ridge extensions are used if available, otherwise ISO 9660
Version 2, then Joliet are used.
If neither extension is present HSFS defaults to the standard capabilities of
ISO 9660.
Since so-called hybrid CD-ROMs that contain multiple extensions are possible,
you can use the following mount options to deliberately disable the search for a
specific extension or to force the use of a specific extension even if a
preferable type is present:
.Bd -literal
mount -F hsfs -o ro,nrr device-special directory-name
.Ed
.Pp
Mount options are:
.Bl -tag -width Ds
.It rr
Request HSFS to use Rock Ridge extensions, if present.
This is the default behavior and does not need to be explicitly specified.
.It nrr
Disable detection and use of Rock Ridge extensions, even if present.
.It vers2
Request HSFS to use ISO 9660 Version 2 extensions, even if Rock Ridge is
available.
.It novers2
Disable detection and use of ISO 9660 Version 2 extensions.
.It joliet
Request HSFS to use Joliet extensions, even if Rock Ridge or ISO 9660 Version 2
extensions are available.
.It nojoliet
Disable detection and use of Joliet extensions.
.El
.Pp
Files on a High Sierra or ISO 9660 CD-ROM disk have names of the form
.Pa filename.ext;versio ,
where
.Fa filename
and the optional
.Fa ext
consist of a sequence of uppercase alphanumeric characters
.Po
including
.Sq _
.Pc ,
while the
.Fa version
consists of a sequence of digits, representing the version number of the file.
.Nm
converts all the uppercase characters in a file name to lowercase, and truncates
the
.Sq ;
and version information.
If more than one version of a file is present on the CD-ROM, only the file with
the highest version number is accessible.
.Pp
Conversion of uppercase to lowercase characters may be disabled by using the
.Fl o
.Ar nomaplcase
option to
.Xr mount 8 .
See
.Xr mount_hsfs 8 .
.Pp
If the CD-ROM contains Rock Ridge, ISO 9660 version 2 or Joliet extensions, the
file names and directory names may contain any character supported under
.Xr ufs 4FS .
The names may also be upper and/or lower case and are case sensitive.
File name lengths can be as long as those of
.Xr ufs 4FS .
.Pp
Files accessed through
.Nm
have mode 555
.Pq owner, group and world readable and executable ,
uid 0 and gid 3. If a directory on the CD-ROM has read permission,
.Nm
grants execute permission to the directory, allowing it to be searched.
.Pp
With Rock Ridge extensions, files and directories can have any permissions that
are supported on a
.Xr ufs 4FS
file system.
However, under all write permissions, the file system is read-only, with
.Er EROFS
returned to any write operations.
.Pp
Like High Sierra and ISO 9660 CD-ROMs, HSFS supports only regular files and
directories.
A Rock Ridge CD-ROM can support regular files, directories, and symbolic links,
as well as device nodes, such as block, character, and FIFO.
.Sh EXAMPLES
.Sy Example 1
Sample Display of File System Files
.Pp
If there is a file
.Pa BIG.BAR
on a High Sierra or ISO 9660 format CD-ROM it will show up as
.Pa big.bar
when listed on a
.Nm
file system.
.Pp
If there are three files
Pa BAR.BAZ;1 ,
Pa BBAR.BAZ;2 ,
and
.Pa BAR.BAZ;3
on a High Sierra or ISO 9660 format CD-ROM, only the file
.Pa BAR.BAZ;3
will be accessible.
It will be listed as
.Pa bar.baz .
.Sh DIAGNOSTICS
.Bl -tag -width Ds
.It "hsfs: Warning: the file system...  does not conform to the ISO-9660 spec"
The specific reason appears on the following line.
You might be attempting to mount a CD-ROM containing a different file system,
such as
.Xr ufs 4FS
.It "hsfs: Warning: the file system... contains a file [with an] unsupported"
type"
The
.Nm
file system does not support the format of some file or directory on the CD-ROM,
for example a record structured file.
.It "hsfs: hsnode table full, %d nodes allocated"
There are not enough
.Nm
internal data structure elements to handle all the files currently open.
This problem may be overcome by adding a line of the form
.Ql set hsfs:nhsnode=number
to the
.Pa /etc/system
system configuration file and rebooting.
See
.Xr system 5 .
.El
.Sh SEE ALSO
.Xr vfstab 5 ,
.Xr mount 8 ,
.Xr mount_hsfs 8
.Pp
.Rs
.%A N. V. Phillips
.%A Sony Corporation
.%T System Description Compact Disc Digital Audio, ("Red Book")
.Re
.Rs
.%A N. V. Phillips
.%A Sony Corporation
.%T System Description of Compact Disc Read Only Memory, ("Yellow Book")
.Re
.Rs
.%T Volume and File Structure of CD-ROM for Information Interchange
.%N ISO 9660:1988(E)
.Re
.Sh WARNINGS
Do not physically eject a CD-ROM while the device is still mounted as a
.Nm
file system.
.Pp
Under MS-DOS
.Pq for which CD-ROMs are frequently targeted ,
files with no extension may be represented either as:
.Pa filename\&.
or
.Pa filename
that is, with or without a trailing period.
These names are not equivalent under UNIX systems.
For example, the names:
.Pa BAR\&.
and
.Pa BAR
are not names for the same file under the UNIX system.
This may cause confusion if you are consulting documentation for CD-ROMs
originally intended for MS-DOS systems.
.Pp
Use of the
.Fl o
.Ar notraildot
option to
.Xr mount 8
makes it optional to specify the trailing dot.
See
.Xr mount_hsfs 8 .
.Sh NOTES
No translation of any sort is done on the contents of High Sierra or ISO 9660
format CD-ROMs; only directory and file names are subject to interpretation by
.Nm .