.\"
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 1989 AT&T
.\" 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 UFS 4FS
.Os
.Sh NAME
.Nm ufs
.Nd UFS file system
.Sh SYNOPSIS
.In sys/param.h
.In sys/types.h
.In sys/fs/ufs_fs.h
.In sys/fs/ufs_inode.h
.Sh DESCRIPTION
.Nm
is one of the primary default disk-based file systems for illumos.
The UFS file system is hierarchical, starting with its root directory
.Pq Pa /
and continuing downward through a number of directories.
The root of a UFS file system is
.Sy inode 2 .
A UFS file system's root contents replace the contents of the directory upon
which it is mounted.
.Pp
Subsequent sections of this manpage provide details of the UFS file systems.
.Ss State Flags Pq Fa fs_state , Fa fs_clean
UFS uses state flags to identify the state of the file system.
.Fa fs_state
is
.Dv FSOKAY -
.Fa fs_time .
.Fa fs_time
is the timestamp that indicates when the last system write occurred.
.Fa fs_state
is updated whenever
.Fa fs_clean
changes.
Some
.Fa fs_clean
values are:
.Bl -tag -width Ds
.It Dv FSCLEAN
Indicates an undamaged, cleanly unmounted file system.
.It Dv FSACTIVE
Indicates a mounted file system that has modified data in memory.
A mounted file system with this state flag indicates that user data or metadata
would be lost if power to the system is interrupted.
.It Dv FSSTABLE
Indicates an idle mounted file system.
A mounted file system with this state flag indicates that neither user data nor
metadata would be lost if power to the system is interrupted.
.It Dv FSBAD
Indicates that this file system contains inconsistent file system data.
.It Dv FSLOG
Indicates that the file system has logging enabled.
A file system with this flag set is either mounted or unmounted.
If a file system has logging enabled, the only flags that it can have are
.Dv FSLOG
or
.Dv FSBAD .
A non-logging file system can have
.Dv FSACTIVE ,
.Dv FSSTABLE ,
or
.Dv FSCLEAN .
.Pp
It is not necessary to run the
.Sy fsck
command on unmounted file systems with a state of
.Dv FSCLEAN ,
.Dv FSSTABLE ,
or
.Dv FSLOG .
.Xr mount 2
returns
.Dv ENOSPC
if an attempt is made to mount a UFS file system with a state of
.Dv FSACTIVE
for read/write access.
.Pp
As an additional safeguard,
.Fa fs_clean
should be trusted only if
.Fa fs_state
contains a value equal to
.Dv FSOKAY -
.Fa fs_time ,
where
.Dv FSOKAY
is a constant integer defined in the
.Pa /usr/include/sys/fs/ufs_fs.h
file.
Otherwise,
.Fa fs_clean
is treated as though it contains the value of
.Dv FSACTIVE .
.El
.Ss Extended Fundamental Types (EFT)
Extended Fundamental Types
.Pq EFT
provide 32-bit user ID
.Pq UID ,
group ID
.Pq GID ,
and device numbers.
.Pp
If a UID or GID contains an extended value, the short variable
.Po
.Fa ic_suid ,
.Fa ic_sgid
.Pc
contains the value 65535 and the corresponding UID or GID is in
.Fa ic_uid
or
.Fa ic_gid .
Because numbers for block and character devices are stored in the first direct
block pointer of the inode
.Pq Fa ic_db[0]
and the disk block addresses are already 32 bit values, no special encoding
exists for device numbers
.Pq unlike UID or GID fields .
.Ss Multiterabyte File System
A multiterabyte file system enables creation of a UFS file system up to
approximately 16 terabytes of usable space, minus approximately one percent
overhead.
A sparse file can have a logical size of one terabyte.
However, the actual amount of data that can be stored in a file is approximately
one percent less than one terabyte because of file system overhead.
.Pp
On-disk format changes for a multiterabyte UFS file system include:
.Bl -bullet -offset indent
.It
The magic number in the superblock changes from
.Dv FS_MAGIC
to
.Dv MTB_UFS_MAGIC .
For more information, see the
.Pa /usr/include/sys/fs/ufs_fs.h
file.
.It
The
.Fa fs_logbno
unit is a sector for UFS that is less than 1 terabyte in
size and fragments for a multiterabyte UFS file system.
.El
.Ss UFS Logging
UFS logging bundles the multiple metadata changes that comprise a complete UFS
operation into a transaction.
Sets of transactions are recorded in an on-disk log and are applied to the
actual UFS file system's metadata.
.Pp
UFS logging provides two advantages:
.Bl -enum
.It
A file system that is consistent with the transaction log eliminates the
need to run
.Sy fsck
after a system crash or an unclean shutdown.
.It
UFS logging often provides a significant performance improvement.
This is because a file system with logging enabled converts multiple updates to
the same data into single updates, thereby reducing the number of overhead disk
operations.
.El
.Pp
The UFS log is allocated from free blocks on the file system and is sized at
approximately 1 Mbyte per 1 Gbyte of file system, up to 256 Mbytes.
The log size may be larger (up to a maximum of 512 Mbytes), depending upon the
number of cylinder groups present in the file system.
The log is continually flushed as it fills up.
The log is also flushed when the file system is unmounted or as a result of a
.Xr lockfs 8
command.
.Ss Mounting UFS File Systems
You can mount a UFS file system in various ways using syntax similar to the
following:
.Bl -enum
.It
Use
.Xr mount 8
from the command line:
.Bd -literal -offset indent
# mount -F ufs /dev/dsk/c0t0d0s7 /export/home
.Ed
.It
Include an entry in the
.Pa /etc/vfstab
file to mount the file system at boot time:
.Bd -literal -offset indent
/dev/dsk/c0t0d0s7 /dev/rdsk/c0t0d0s7 /export/home  ufs   2   yes  -
.Ed
.El
.Pp
For more information on mounting UFS file systems, see
.Xr mount_ufs 8 .
.Sh INTERFACE STABILITY
.Sy Uncomitted
.Sh SEE ALSO
.Xr mount 2 ,
.Xr attributes 7 ,
.Xr df 8 ,
.Xr fsck 8 ,
.Xr fsck_ufs 8 ,
.Xr fstyp 8 ,
.Xr lockfs 8 ,
.Xr mkfs_ufs 8 ,
.Xr newfs 8 ,
.Xr tunefs 8 ,
.Xr ufsdump 8 ,
.Xr ufsrestore 8
.Sh NOTES
For information about internal UFS structures, see
.Xr newfs 8
and
.Xr mkfs_ufs 8 .
For information about dumping and restoring file systems, see
.Xr ufsdump 8 ,
.Xr ufsrestore 8 ,
and
.Pa /usr/include/protocols/dumprestore.h .
If you experience difficulty in allocating space on the ufs filesystem, it may
be due to fragmentation.
Fragmentation can occur when you do not have sufficient free blocks to satisfy
an allocation request even though
.Xr df 8
indicates that enough free space is available.
(This may occur because df only uses the available fragment count to calculate
available space, but the file system requires contiguous sets of fragments for
most allocations).
If you suspect that you have exhausted contiguous fragments on your file system,
you can use the
.Xr fstyp 8
utility with the
.Fl v
option.
In the fstyp output, look at the
.Em nbfree
.Pq number of blocks free
and
.Fa nffree
.Pq (number of fragments free)
fields.
On unmounted filesystems, you can use
.Xr fsck 8
and observe the last line of output, which reports, among other items, the
number of fragments and the degree of fragmentation.
To correct a fragmentation problem, run
.Xr ufsdump 8
and
.Xr ufsrestore 8
on the ufs filesystem.