1.\" 2.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved 3.\" Copyright 1989 AT&T 4.\" Copyright 2021 Oxide Computer Company 5.\" 6.\" The contents of this file are subject to the terms of the 7.\" Common Development and Distribution License (the "License"). 8.\" You may not use this file except in compliance with the License. 9.\" 10.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 11.\" or http://www.opensolaris.org/os/licensing. 12.\" See the License for the specific language governing permissions 13.\" and limitations under the License. 14.\" 15.\" When distributing Covered Code, include this CDDL HEADER in each 16.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 17.\" If applicable, add the following below this CDDL HEADER, with the 18.\" fields enclosed by brackets "[]" replaced with your own identifying 19.\" information: Portions Copyright [yyyy] [name of copyright owner] 20.\" 21.Dd November 29, 2021 22.Dt UFS 4FS 23.Os 24.Sh NAME 25.Nm ufs 26.Nd UFS file system 27.Sh SYNOPSIS 28.In sys/param.h 29.In sys/types.h 30.In sys/fs/ufs_fs.h 31.In sys/fs/ufs_inode.h 32.Sh DESCRIPTION 33.Nm 34is one of the primary default disk-based file systems for illumos. 35The UFS file system is hierarchical, starting with its root directory 36.Pq Pa / 37and continuing downward through a number of directories. 38The root of a UFS file system is 39.Sy inode 2 . 40A UFS file system's root contents replace the contents of the directory upon 41which it is mounted. 42.Pp 43Subsequent sections of this manpage provide details of the UFS file systems. 44.Ss State Flags Pq Fa fs_state , Fa fs_clean 45UFS uses state flags to identify the state of the file system. 46.Fa fs_state 47is 48.Dv FSOKAY - 49.Fa fs_time . 50.Fa fs_time 51is the timestamp that indicates when the last system write occurred. 52.Fa fs_state 53is updated whenever 54.Fa fs_clean 55changes. 56Some 57.Fa fs_clean 58values are: 59.Bl -tag -width Ds 60.It Dv FSCLEAN 61Indicates an undamaged, cleanly unmounted file system. 62.It Dv FSACTIVE 63Indicates a mounted file system that has modified data in memory. 64A mounted file system with this state flag indicates that user data or metadata 65would be lost if power to the system is interrupted. 66.It Dv FSSTABLE 67Indicates an idle mounted file system. 68A mounted file system with this state flag indicates that neither user data nor 69metadata would be lost if power to the system is interrupted. 70.It Dv FSBAD 71Indicates that this file system contains inconsistent file system data. 72.It Dv FSLOG 73Indicates that the file system has logging enabled. 74A file system with this flag set is either mounted or unmounted. 75If a file system has logging enabled, the only flags that it can have are 76.Dv FSLOG 77or 78.Dv FSBAD . 79A non-logging file system can have 80.Dv FSACTIVE , 81.Dv FSSTABLE , 82or 83.Dv FSCLEAN . 84.Pp 85It is not necessary to run the 86.Sy fsck 87command on unmounted file systems with a state of 88.Dv FSCLEAN , 89.Dv FSSTABLE , 90or 91.Dv FSLOG . 92.Xr mount 2 93returns 94.Dv ENOSPC 95if an attempt is made to mount a UFS file system with a state of 96.Dv FSACTIVE 97for read/write access. 98.Pp 99As an additional safeguard, 100.Fa fs_clean 101should be trusted only if 102.Fa fs_state 103contains a value equal to 104.Dv FSOKAY - 105.Fa fs_time , 106where 107.Dv FSOKAY 108is a constant integer defined in the 109.Pa /usr/include/sys/fs/ufs_fs.h 110file. 111Otherwise, 112.Fa fs_clean 113is treated as though it contains the value of 114.Dv FSACTIVE . 115.El 116.Ss Extended Fundamental Types (EFT) 117Extended Fundamental Types 118.Pq EFT 119provide 32-bit user ID 120.Pq UID , 121group ID 122.Pq GID , 123and device numbers. 124.Pp 125If a UID or GID contains an extended value, the short variable 126.Po 127.Fa ic_suid , 128.Fa ic_sgid 129.Pc 130contains the value 65535 and the corresponding UID or GID is in 131.Fa ic_uid 132or 133.Fa ic_gid . 134Because numbers for block and character devices are stored in the first direct 135block pointer of the inode 136.Pq Fa ic_db[0] 137and the disk block addresses are already 32 bit values, no special encoding 138exists for device numbers 139.Pq unlike UID or GID fields . 140.Ss Multiterabyte File System 141A multiterabyte file system enables creation of a UFS file system up to 142approximately 16 terabytes of usable space, minus approximately one percent 143overhead. 144A sparse file can have a logical size of one terabyte. 145However, the actual amount of data that can be stored in a file is approximately 146one percent less than one terabyte because of file system overhead. 147.Pp 148On-disk format changes for a multiterabyte UFS file system include: 149.Bl -bullet -offset indent 150.It 151The magic number in the superblock changes from 152.Dv FS_MAGIC 153to 154.Dv MTB_UFS_MAGIC . 155For more information, see the 156.Pa /usr/include/sys/fs/ufs_fs.h 157file. 158.It 159The 160.Fa fs_logbno 161unit is a sector for UFS that is less than 1 terabyte in 162size and fragments for a multiterabyte UFS file system. 163.El 164.Ss UFS Logging 165UFS logging bundles the multiple metadata changes that comprise a complete UFS 166operation into a transaction. 167Sets of transactions are recorded in an on-disk log and are applied to the 168actual UFS file system's metadata. 169.Pp 170UFS logging provides two advantages: 171.Bl -enum 172.It 173A file system that is consistent with the transaction log eliminates the 174need to run 175.Sy fsck 176after a system crash or an unclean shutdown. 177.It 178UFS logging often provides a significant performance improvement. 179This is because a file system with logging enabled converts multiple updates to 180the same data into single updates, thereby reducing the number of overhead disk 181operations. 182.El 183.Pp 184The UFS log is allocated from free blocks on the file system and is sized at 185approximately 1 Mbyte per 1 Gbyte of file system, up to 256 Mbytes. 186The log size may be larger (up to a maximum of 512 Mbytes), depending upon the 187number of cylinder groups present in the file system. 188The log is continually flushed as it fills up. 189The log is also flushed when the file system is unmounted or as a result of a 190.Xr lockfs 8 191command. 192.Ss Mounting UFS File Systems 193You can mount a UFS file system in various ways using syntax similar to the 194following: 195.Bl -enum 196.It 197Use 198.Xr mount 8 199from the command line: 200.Bd -literal -offset indent 201# mount -F ufs /dev/dsk/c0t0d0s7 /export/home 202.Ed 203.It 204Include an entry in the 205.Pa /etc/vfstab 206file to mount the file system at boot time: 207.Bd -literal -offset indent 208/dev/dsk/c0t0d0s7 /dev/rdsk/c0t0d0s7 /export/home ufs 2 yes - 209.Ed 210.El 211.Pp 212For more information on mounting UFS file systems, see 213.Xr mount_ufs 8 . 214.Sh INTERFACE STABILITY 215.Sy Uncomitted 216.Sh SEE ALSO 217.Xr mount 2 , 218.Xr attributes 7 , 219.Xr df 8 , 220.Xr fsck 8 , 221.Xr fsck_ufs 8 , 222.Xr fstyp 8 , 223.Xr lockfs 8 , 224.Xr mkfs_ufs 8 , 225.Xr newfs 8 , 226.Xr tunefs 8 , 227.Xr ufsdump 8 , 228.Xr ufsrestore 8 229.Sh NOTES 230For information about internal UFS structures, see 231.Xr newfs 8 232and 233.Xr mkfs_ufs 8 . 234For information about dumping and restoring file systems, see 235.Xr ufsdump 8 , 236.Xr ufsrestore 8 , 237and 238.Pa /usr/include/protocols/dumprestore.h . 239If you experience difficulty in allocating space on the ufs filesystem, it may 240be due to fragmentation. 241Fragmentation can occur when you do not have sufficient free blocks to satisfy 242an allocation request even though 243.Xr df 8 244indicates that enough free space is available. 245(This may occur because df only uses the available fragment count to calculate 246available space, but the file system requires contiguous sets of fragments for 247most allocations). 248If you suspect that you have exhausted contiguous fragments on your file system, 249you can use the 250.Xr fstyp 8 251utility with the 252.Fl v 253option. 254In the fstyp output, look at the 255.Em nbfree 256.Pq number of blocks free 257and 258.Fa nffree 259.Pq (number of fragments free) 260fields. 261On unmounted filesystems, you can use 262.Xr fsck 8 263and observe the last line of output, which reports, among other items, the 264number of fragments and the degree of fragmentation. 265To correct a fragmentation problem, run 266.Xr ufsdump 8 267and 268.Xr ufsrestore 8 269on the ufs filesystem. 270