Is there APFS system (e.g. API) documentation anywhere? I want to snapshot an external drive

Question

It looks like there must be system calls to create and manage APFS snapshots on external drives. Carbon Copy Cloner uses them in their backup routines https://bombich.com/kb/ccc5/leveraging-snapshots-on-apfs-volumes

But, there doesn't seem to be a command line interface aside from tmutil. tmutil can view snapshots by volume, but can only make snapshots on the system volume.

There must be an API call, or procedure, to create an APFS snapshot, that CCC uses?

I have some familiarity with APFS and lack of command line tools, as I use AFSCTool a lot (https://github.com/jeabraham/afsctool/). Since Apple doesn't provide a file system compression command, someone needed to write a C program to call the APIs to compress. (Apple supports on-the-fly decompression, but doesn't give users a way to compress the files in the first place, so someone else had to write a command line tool for us.)

Answer 1

Yes, there is indeed such documentation. It comes with macOS preinstalled.

I would suggest running the following command in the Terminal:

man fs_snapshot_create

The manual page contains documentation on not only how to create a snapshot, but also how to list, delete, rename, mount and revert them.

Note that most of these functions, with the exception of fs_snapshot_list(), requires your program to have a specific entitlement (com.apple.private.vfs.snapshot).

As this is about making a tool for your own personal machine, then you can just give the tool that entitlement when compiling the code. Use AMFIExemption to allow your program (and others on your Mac) to have that entitlement without it being "endorsed" by Apple.

If you want to create a tool for wide distribution, you would want to apply with Apple to get the entitlement. My understanding is that these are granted to backup applications.

Answer 2

For reference, the output of recommended commands in the comment. Though nothing related to snapshot creation, only restore by apfs.util -R:

man apfs.util

APFS.UTIL(8)                 System Manager's Manual                APFS.UTIL(8)

NAME
     apfs.util – APFS file system utility

SYNOPSIS
     apfs.util -A get path
     apfs.util -A set=yes/no path
     apfs.util -C -type TYPE path
     apfs.util -D get device
     apfs.util -D set=yes/no device
     apfs.util -E path
     apfs.util -G path
     apfs.util -h
     apfs.util -k device
     apfs.util -m  path
     apfs.util -M dir
     apfs.util -O path fs_name
     apfs.util -p device removable writable
     apfs.util -P verb1 verb2 path
     apfs.util -r path
     apfs.util -R SNAPSHOT device
     apfs.util -s device
     apfs.util -S dir
     apfs.util -t
     apfs.util -y path
     apfs.util -Y dir
     apfs.util -z path
     apfs.util -Z path

DESCRIPTION
     The apfs.util Command supports getting and setting various file system
     options.

     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.  device argument is the /dev/diskXsY identifier corresponding
     to the volume.  dir could be any directory in the mounted file system.

     Options:

     -A get path
             get atime update setting for volume specified by path.

     -A set=yes/no path
             enable or disable update setting for volume specified by path.

     -C -type TYPE path
             clear the purgeability of files of the specified type on the volume
             referred to by path.
             TYPE could be one of: photos, music, mail, document, data, podcast,
             video, movie, messages, books.

     -D get device
             Get defragmentation setting for volume or container specied by
             device.

     -D set=yes/no device
             enable / disable defragmentation for volume or container specified
             by device.

     -E path
             drop the extents for path from the first snapshot

     -G path
             get stats on the purgeble files on the volume specified by path.

     -k      Return the UUID of the apfs volume on device.

     -m verb path
             mark the file at path as purgeable with the various options
             specified.
             verb could be many of: -low -med -high -photo -music -mail
             -document -data -podcast -video -movie -message -book -fault -clear

     -M dir  flag the named directory as "maintain-dir-stats".

     -O path fs_name
             override the fstypename for apfs to be fs_name or "hfs" if the
             optional fs_name was not given.

     -p device
             Return the apfs volume name of device.

     -P criteria path
             purge files meeting the criteria specified on the volume referred
             to by path.
             criteria could be -low -med -high
             and/or with specified parameters: -minsize VAL -maxage VAL -maxage
             AGE_IN_SECONDS -total TOTAL_PURGE_AMOUNT
             and/or specifiend by: -type TYPE, that could be one of -photos
             -music -mail -document -data -podcast -video -movie -messages
             -books

     -r dir  set the sync-root flag on the specified dir directory.

     -R SNAPSHOT device
             set the volume specified by device to revert to the snapshot named
             by SNAPSHOT on next mount.

     -s device
             Set container UUID and its volume(s) UUID(s) to new random values.
             device must be an identifier of a container.

     -S dir  get the directory stats from dir.  path.

     -t      stitches and creates synthetic objects on root volume group

     -y path
             get the sync-root flag from the first parent that has one for the
             item identified by path.

     -Y dir  get the sync-root flag from the specified directory in dir.

     -z path
             make the file at exempt from copy-on-write semantics for snapshots

     -Z path
             get the purgeable file flags for the specific file at path.


SEE ALSO
     diskarbitrationd(8)

HISTORY
     The apfs.util utility first appeared in OS X 10.12.

Mac OS X                         August 17, 2020                        Mac OS X

/System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util

APFS Utility tool
Usage: apfs.util  [] path|dir|device [], as follows:

apfs.util  [] /dev/diskXsY
   -a path        : Get the absolute volume uuid for the volume at path.
   -D get         : Get defragmentation setting for volume or container.
   -D set=yes/no  : enable / disable defragmentation for volume or container.
   -k             : get volume UUID.
   -p             : probe for volume name.
   -R SNAPSHOT    : set the volume to revert to the snapshot named by SNAPSHOT on next mount.
   -s             : set container UUID and its volume(s) UUID(s) to new random values.

apfs.util  [] path|dir []
   -A get                    : get atime update setting for volume.
   -A set=yes/no             : enable / disable atime update for volume.
   -C -type TYPE volume_path : clear the purgeability of files of the specified type on the volume referred to by path.
   -E path                   : drop the extents for 'path' from the first snapshot.
   -G path                   : get stats on the purgeble files on the volume specified by path.
   -m  path            : mark the file at path as purgeable with the various options specified.
                               verb could be one of: -low -med -high -photo -music -mail -document -data
                                                     -podcast -video -movie -message -book -fault -pdir -clear.
   -M dir                    : flag the named directory as "maintain-dir-stats".
   -O path [fs name]         : override the fstypename for apfs to be "hfs" (or the optional name given).
   -P  path        : purge files meeting the criteria specified on the volume referred to by path.
   -K path                   : purge(kill) the single file at the specified path
   -r dir                    : set the sync-root flag on the specified directory.
   -S dir                    : get the directory stats from dir.
   -Y dir                    : get the sync-root flag from the specified directory.
   -y path                   : get the sync-root flag from the first parent that has one for the item identified by 'path'.
   -z path                   : make the file at path exempt from copy-on-write semantics for snapshots.
   -Z path                   : get the purgeable file flags for the specific file at 'path'.

apfs.util 
   -t  : stitches and creates synthetic objects on root volume group.
   -h  : show this help menu.