1 files changed, 540 insertions, 0 deletions
diff --git a/usr/src/man/man4fs/pcfs.4fs b/usr/src/man/man4fs/pcfs.4fs
new file mode 100644
index 0000000000..2b51e2032b
--- /dev/null
+++ b/usr/src/man/man4fs/pcfs.4fs
@@ -0,0 +1,540 @@
+.\"
+.\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved.
+.\" 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 November 29, 2021
+.Dt PCFS 4FS
+.Os
+.Sh NAME
+.Nm pcfs
+.Nd FAT formatted file system
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/mount.h
+.In sys/fs/pc_fs.h
+.Ft int
+.Fo mount
+.Fa "const char *spec"
+.Fa "const char *dir"
+.Fa "int mflag"
+.Fa \(dqpcfs\(dq
+.Fa NULL
+.Fa 0
+.Fa "const char *optptr"
+.Fa "int optlen"
+.Fc
+.Sh DESCRIPTION
+.Nm
+is a file system type that enables direct access to files on FAT formatted disks
+from within the SunOS operating system.
+.Pp
+Once mounted,
+.Nm
+provides standard file operations and semantics.
+Using
+.Nm
+you can create, delete, read, and write files on a FAT formatted disk.
+You can also create and delete directories and list files in a directory.
+.Pp
+.Nm
+supports FAT12 (floppies) and FAT16 and FAT32 file systems.
+.Pp
+.Nm
+file systems can be force umounted using the
+.Fl -f
+argument to
+.Xr umount 8 .
+.Pp
+The
+.Nm
+file system contained on the block special file identified by
+.Fa spec
+is mounted on the directory identified by
+.Fa dir .
+.Fa spec
+and
+.Fa dir
+are pointers to pathnames.
+.Fa mflag
+specifies the
+.Fa mount
+options.
+The
+.Dv MS_DATA
+bit in
+.Fa mflag
+must be set.
+Mount options can be passed to
+.Nm
+using the optptr and optlen arguments.
+See
+.Xr mount_pcfs 8
+for a list of mount options supported by
+.Nm
+.Pp
+Because FAT formatted media can record file timestamps between January 1st 1980
+and December 31st 2127, it's not possible to fully represent UNIX
+.Vt time_t
+in
+.Nm
+for 32 bit or 64 bit programs.
+In particular, if post-2038 timestamps are present on a FAT formatted medium and
+.Nm
+returns these, 32bit applications may unexpectedly fail with
+.Er EOVERFLOW
+errors.
+To prevent this, the default behaviour of
+.Nm
+has been modified to clamp
+post-2038 timestamps to the latest possible value for a 32bit
+.Vt time_t ,
+which is January 19th 2038, 03:14:06 UTC when setting and retrieving file
+timestamps.
+You can override this behavior using the
+.Ar noclamptime
+mount option, as described in
+.Xr mount_pcfs 8 .
+.Pp
+Timestamps on FAT formatted media are recorded in local time.
+If the recording and receiving systems use different timezones, the
+representation of timestamps shown on the two systems for the same medium might
+vary.
+To correct this,
+.Nm
+provides a timezone mount option to force interpretation
+of timestamps as read from a FAT formatted medium in a given timezone
+.Pq that of the recorder .
+By default, the local timezone of the receiver is used.
+See
+.Xr mount_pcfs 8
+for details.
+.Pp
+The root directory of a FAT formatted medium has no timestamps and
+.Nm
+returns the time when the mount was done as timestamp for the root of the
+filesystem.
+.Pp
+The FAT filesystem doesn't support multiple links.
+As a result, the link count
+for all files and directories in
+.Nm
+is hard-coded as
+.Dq 1 .
+.Ss Mounting File Systems
+Use the following command to mount
+.Nm
+from diskette:
+.Bd -literal -offset indent
+mount -F pcfs device-special directory-name
+.Ed
+.Pp
+You can use:
+.Bd -literal -offset indent
+mount directory-name
+.Ed
+if the following line is in your
+.Pa /etc/vfstab
+file:
+.Bd -literal -offset indent
+device-special - directory-name pcfs - no rw
+.Ed
+.Pp
+Use the following command to mount
+.Nm
+from non-diskette media:
+.Bd -literal -offset indent
+mount -F pcfs device-special:logical-drive directory-name
+.Ed
+.Pp
+You can use:
+.Bd -literal -offset indent
+mount directory-name
+.Ed
+if the following line is in your
+.Pa /etc/vfstab
+file:
+.Bd -literal -offset indent
+device-special:logical_drive - directory-name pcfs - no rw
+.Ed
+.Pp
+.Ar device-special
+specifies the special block device file for the diskette
+.Pq Pa /dev/disketteN
+or the entire hard disk
+.Po
+Pa /dev/dsk/cNtNdNp0
+for a SCSI, SATA, NVME disk, and
+.Pa /dev/dsk/cNdNp0
+for IDE disks
+.Pc
+or the PCMCIA pseudo-floppy memory card
+.Pq Pa /dev/dsk/cNtNdNsN .
+.Pp
+.Ar logical-drive
+specifies either the DOS logical drive letter
+.Po
+.Sy c
+through
+.Sy z
+.Pc
+or a drive number
+.Pq 1 through 24 .
+Drive letter
+.Sy c
+is equivalent to drive number
+.Sy 1
+and represents the Primary DOS partition on the disk; drive letters
+.Sy d
+through
+.Sy z
+are equivalent to drive numbers
+.Sy 2
+through
+.Sy 24 ,
+and represent DOS drives within the Extended FAT partition.
+Note that
+.Ar device-special
+and
+.Ar logical-drive
+must be separated by a colon.
+.Pp
+.Ar directory-name
+specifies the location where the file system is mounted.
+.Pp
+For example, to mount the Primary DOS partition from a SCSI hard disk,
+use:
+.Bd -literal -offset indent
+mount -F pcfs /dev/dsk/cNtNdNp0:c /pcfs/c
+.Ed
+.Pp
+To mount the first logical drive in the Extended DOS partition from an IDE hard
+disk, use:
+.Bd -literal -offset indent
+mount -F pcfs /dev/dsk/cNdNp0:d /pcfs/d
+.Ed
+.Pp
+To mount a DOS diskette in the first floppy drive when volume management is not
+running use:
+.Bd -literal -offset indent
+mount -F pcfs /dev/diskette /pcfs/a
+.Ed
+.Pp
+If Volume Management is running, run
+.Xr volcheck 1
+to automatically mount the floppy and some removable disks.
+.Pp
+To mount a PCMCIA pseudo-floppy memory card, with Volume Management not running
+.Pq or not managing the PCMCIA media ,
+use:
+.Bd -literal -offset indent
+mount -F pcfs /dev/dsk/cNtNdNsN /pcfs
+.Ed
+.Ss "Conventions"
+Files and directories created through
+.Nm
+must comply with either the FAT short file name convention or the long file name
+convention introduced with Windows 95.
+The FAT short file name convention is of the form
+.Pa filename[.ext] ,
+where
+.Em filename
+generally consists of from one to eight upper-case characters, while the
+optional
+.Em ext
+consists of from one to three upper-case characters.
+.Pp
+The long file name convention is much closer to illumos file names.
+A long file name can consist of any characters valid in a short file name,
+lowercase letters, non-leading spaces, the characters
+.Sy +,;=[] ,
+any number of periods, and can be up to 255 characters long.
+Long file names have an associated short file name for systems that do not
+support long file names.
+The short file name is not visible if the system recognizes long file names.
+.Nm
+generates a unique short name automatically when creating a long file name.
+.Pp
+Given a long file name such as
+.Pa This is a really long filename.TXT ,
+the short file name will generally be of the form
+.Pa THISIS~N\&.TXT ,
+where
+.Em N
+is a number.
+The long file name will probably get the short name
+.Pa THISIS~1.TXT ,
+or
+.Pa THISIS~2.TXT
+if
+.Pa THISIS~1.TXT
+already exits
+.Po or
+.Pa THISIS~3.TXT
+if both exist, and so forth
+.Pc .
+If you use
+.Nm
+file systems on systems that do not support long file names, you may want to
+continue following the short file name conventions.
+See
+.Sx EXAMPLES .
+.Pp
+When creating a file name,
+.Nm
+creates a short file name if it fits the FAT short file name format, otherwise
+it creates a long file name.
+This is because long file names take more directory space.
+Because the root directory of a
+.Nm
+file system is fixed size, long file names in the root directory should be
+avoided if possible.
+.Pp
+When displaying file names,
+.Nm
+shows them exactly as they are on the media.
+This means that short names are displayed as uppercase and long file names
+retain their case.
+Earlier versions of
+.Nm
+folded all names to lowercase, which can be forced with the
+.Dv PCFS_MNT_FOLDCASE
+mount option.
+All file name searches within
+.Nm ,
+however, are treated as if they were uppercase, so
+.Pa readme.txt
+and
+.Pa ReAdMe.TxT
+refer to the same file.
+.Pp
+To format a diskette or a PCMCIA pseudo-floppy memory card in FAT format in the
+SunOS system, use either the
+.Xr fdformat 1
+.Fl -d
+or the DOS
+.Sy FORMAT
+command.
+.Ss Boot Partitions
+On x86 systems, hard drives may contain an fdisk partition reserved for the boot
+utilities.
+The most common case is the EFI system partition.
+These partitions are special instances of
+.Nm .
+You can mount an x86 boot partition with the command:
+.Bd -literal -offset indent
+mount -F pcfs device-special:boot directory-name
+.Ed
+or you can use:
+.Bd -literal -offset indent
+mount directory-name
+.Ed
+if the following line is in your
+.Pa /etc/vfstab
+file:
+.Bd -literal -offset indent
+device-special:boot - directory-name pcfs - no rw
+.Ed
+.Pp
+.Ar device-special
+specifies the special block device file for the entire hard disk
+.Pq Pa /dev/dsk/cNtNdNp0
+.Pp
+.Ar directory-name
+specifies the location where the file system is mounted.
+.Pp
+All files on a boot partition are owned by super-user.
+Only the super-user may create, delete, or modify files on a boot partition.
+.Sh ENVIRONMENT
+See
+.Xr environ 7
+for descriptions of the following environment variables
+for the current locale setting:
+.Ev LANG ,
+.Ev LC_ALL ,
+.Ev LC_CTYPE ,
+and
+.Ev LC_COLLATE .
+.Sh FILES
+.Bl -tag -width Pa
+.It Pa /usr/lib/fs/pcfs/mount
+.Nm
+mount command.
+.It Pa /usr/kernel/fs/amd64/pcfs
+64-bit kernel module (x86).
+.El
+.Sh EXAMPLES
+.Sy Example 1
+Sample Displays of File Names
+.Pp
+If you copy a file
+.Pa financial.data
+from a UNIX file system to
+.Nm ,
+it displays as
+.Pa financial.data
+in
+.Nm
+but may show up as
+.Pa FINANC~1.DAT
+in systems that do not support long file names.
+.Pp
+The following are legal long file names.
+They are also illegal short file names:
+.Bl -item -offset indent
+.It
+.Pa test.sh.orig
+.It
+.Pa data+
+.El
+.Pp
+Other systems that do not support long file names may see:
+.Bl -item -offset indent
+.It
+.Pa TESTSH~1.ORI
+.It
+.Pa DATA~1
+.It
+.Pa LOGIN~1
+.El
+The short file name is generated from the initial characters of the long file
+name, so differentiate names in the first few characters.
+For example, these names:
+.Bl -item -offset indent
+.It
+.Pa WorkReport.January.Data
+.It
+.Pa WorkReport.February.Data
+.It
+.Pa WorkReport.March.Data
+.El
+result in these short names, which are not distinguishable:
+.Bl -item -offset indent
+.It
+.Pa WORKRE~1.DAT
+.It
+.Pa WORKRE~2.DAT
+.It
+.Pa WORKRE~2.DAT
+.It
+.Pa WORKRE~2.DAT
+.It
+.Pa WORKRE~13.DAT
+.El
+.Pp
+These names, however:
+.Bl -item -offset indent
+.It
+.Pa January.WorkReport.Data
+.It
+.Pa February.WorkReport.Data
+.It
+.Pa March.WorkReport.Data
+.El
+result in the more descriptive short names:
+.Bl -item -offset indent
+.It
+.Pa JANUAR~1.DAT
+.It
+.Pa FEBRUA~1.DAT
+.It
+.Pa MARCHW~1.DAT
+.El
+.Sh SEE ALSO
+.Xr chgrp 1 ,
+.Xr chown 1 ,
+.Xr dos2unix 1 ,
+.Xr eject 1 ,
+.Xr fdformat 1 ,
+.Xr unix2dos 1 ,
+.Xr volcheck 1 ,
+.Xr ctime 3C ,
+.Xr vfstab 5 ,
+.Xr environ 7 ,
+.Xr mount 8 ,
+.Xr mount_pcfs 8 ,
+.Xr umount 8
+.Sh WARNINGS
+Do not physically eject a FAT floppy while the device is mounted as
+.Nm
+If Volume Management is managing a device, use the
+.Xr eject 1
+command before physically removing media.
+.Pp
+When mounting
+.Nm
+on a hard disk, make sure the first block on that device contains a valid fdisk
+partition table.
+.Pp
+Because
+.Nm
+has no provision for handling owner-IDs or group-IDs on files,
+.Xr chown 1
+or
+.Xr chgrp 1
+may generate various errors.
+This is a limitation of
+.Nm
+but it should not cause problems other than error messages.
+.Sh NOTES
+Only the following characters are allowed in
+.Nm
+short file names and extensions:
+.Bl -item -offset indent
+.It
+0-9
+.It
+A-Z
+.It
+$#&@!%()-{}<>`_^~|'
+.It
+.El
+illumos and FAT use different character sets and have different
+requirements for the text file format.
+Use the
+.Xr dos2unix 1
+and
+.Xr unix2dos 1
+commands to convert files between them.
+.Pp
+.Nm
+offers a convenient transportation vehicle for files between multiple systems.
+Because the FAT disk format was designed for use under DOS, it does not operate
+efficiently under illumos and should not be used as the format for a regular
+local storage.
+Instead, use ZFS for local storage within an illumos system.
+.Pp
+Although long file names can contain spaces
+(just as in UNIX file names) ,
+some utilities may be confused by them.
+.Pp
+When
+.Nm
+encounters long file names with non-ASCII characters, it converts such long file
+names in Unicode scalar values into UTF-8 encoded filenames so that they are
+legible and usable with any of illumos UTF-8 locales.
+In the same context, when new file names with non-ASCII characters are created,
+.Nm
+expects that such file names are in UTF-8.
+This feature increases the interoperability of
+.Nm
+on illumos with other operating
+systems.
+.Sh BUGS
+.Nm
+should handle the disk change condition in the same way that DOS does, so you do
+not need to unmount the file system to change floppies.