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