.\" 
.\" Copyright (c) 2015-2023 Apple Inc.
.\" Licensed under the MIT License.
.\"
.\"     @(#)apfs.util.8
.Dd May 2, 2023
.Dt APFS.UTIL 8
.Os
.Sh NAME
.Nm apfs.util
.Nd APFS file system utility
.Sh SYNOPSIS
.Nm
.Fl A Ar get path
.Nm
.Fl A Ar set=yes/no path
.Nm
.Fl C Ar -type type path
.Nm
.Fl D Ar get device
.Nm
.Fl D Ar set=yes/no device
.Nm
.Fl E Ar path
.Nm
.Fl G Ar path
.Nm
.Fl h
.Nm
.Fl k Ar device
.Nm
.Fl m Ar <verb> path
.Nm
.Fl M Ar dir
.Nm
.Fl O Ar path fs_name
.Nm
.Fl p Ar device removable writable
.Nm
.Fl P Ar verb1 verb2 path
.Nm
.Fl r Ar path
.Nm
.Fl R Ar SNAPSHOT device
.Nm
.Fl s Ar device
.Nm
.Fl S Ar dir
.Nm
.Fl t
.Nm
.Fl y Ar path
.Nm
.Fl Y Ar dir
.Nm
.Fl z Ar path
.Nm
.Fl Z Ar path
.Sh DESCRIPTION
The
.Nm
command supports getting and setting various file system options.

.Ar path
argument is a path to any file within the mounted file system.
If it is used to specify a volume, any file within the same volume will get the same result.
.Ar device
argument is the /dev/diskXsY identifier corresponding to the volume.
.Ar dir
could be any directory in the mounted file system.
.Pp
Options:
.Bl -tag -width indent
.It Fl A Ar get path
get atime update setting for volume specified by
.Ar path .
.It Fl A Ar set=yes/no path
enable or disable update setting for volume specified by
.Ar path .
.It Fl C type Ar type path
clear the purgeability of files of the specified type on the volume referred to by
.Ar path .
.br
.Ar type
could be one of: photo, music, mail, document, data, podcast, video, movie, message, book.
.It Fl D Ar get device
Get defragmentation setting for volume or container specied by
.Ar device .
.It Fl D Ar set=yes/no device
enable / disable defragmentation for volume or container specified by
.Ar device .
.It Fl E Ar path
drop the extents for
.Ar path
from the first snapshot
.It Fl G Ar path
get stats on the purgeable files on the volume specified by
.Ar path .
.It Fl k
Return the UUID of the apfs volume on
.Ar device .
.It Fl m Ar verb path
mark the file at
.Ar path
as purgeable with the various options specified.
.br
.Ar verb
could be one or more of: -low -med -high -photo -music -mail -document -data -podcast -video -movie -message -book -fault -clear
.It Fl M Ar dir
flag the named directory as "maintain-dir-stats".
.It Fl O Ar path fs_name
override the fstypename for apfs to be
.Ar fs_name
or "hfs" if the optional
.Ar fs_name
was not given.
.It Fl p Ar device
Return the apfs volume name of
.Ar device .
.It Fl P Ar criteria path
purge files meeting the
.Ar criteria
specified on the volume referred to by
.Ar path .
.br
.Ar criteria
could be -low -med -high
.br
and/or with specified parameters: -minsize VAL -maxage VAL -maxage AGE_IN_SECONDS -total TOTAL_PURGE_AMOUNT
.br
and/or specified by: -type
.Ar type ,
that could be one of -photo -music -mail -document -data -podcast -video -movie -message -book
.br
(and optionally, -typetotal TYPE_PURGE_AMOUNT)
.It Fl r Ar dir
set the sync-root flag on the specified
.Ar dir
directory.
.It Fl R Ar SNAPSHOT device
set the volume specified by
.Ar device
to revert to the snapshot named by SNAPSHOT on next mount.
.It Fl s Ar device
Set container UUID and its volume(s) UUID(s) to new random values.
.Ar device
must be an identifier of a container.
.It Fl S Ar dir
get the directory stats from
.Ar dir .
.Ar path .
.It Fl t
stitches and creates synthetic objects on root volume group
.It Fl y Ar path
get the sync-root flag from the first parent that has one for the item identified by
.Ar path .
.It Fl Y Ar dir
get the sync-root flag from the specified directory in
.Ar dir .
.It Fl z Ar path
make the file at
.Ar path
exempt from copy-on-write semantics for snapshots
.It Fl Z Ar path
get the purgeable file flags for the specific file at
.Ar path .

.Sh SEE ALSO
.Xr diskarbitrationd 8
.Sh HISTORY
The
.Nm
utility first appeared in OS X 10.12.