TRIM(8)                 FreeBSD System Manager's Manual                TRIM(8)

NAME

     trim - erase device blocks that have no needed contents

SYNOPSIS

     trim [-Nfqv] [-[lo] offset[K|k|M|m|G|g|T|t|P|p|E|e]] [-r rfile] device
          ...

DESCRIPTION

     The trim utility erases specified region of the device.  It is mostly
     relevant for a storage that implements trim (like flash based, or thinly
     provisioned storage).  All erased data is lost.

     The trim utility should not be used upon mounted file system or active
     devices being a part of imported ZFS pool or other software RAID, and the
     kernel does not permit such usage generally.  If used upon not mounted
     file system or inactive device, the trim utility erases blocks non-
     selectively, whether a block is occupied or not.  Refer to the
     fsck_ffs(8) command having a flag -E to trim free blocks inside populated
     UFS, and to the zpool-trim(8) command to trim existing ZFS pool.

     The following options are available:

     -N      Do not actually erase anything but show what it would do (dry
             run).  Implies -v.  This is the default.  Overrides -f.

     -f      Perform the operation.  Overrides -N.

     -l offset[K|k|M|m|G|g|T|t|P|p|E|e]

     -o offset[K|k|M|m|G|g|T|t|P|p|E|e]
             Specify the length -l of the region to trim or its offset -o from
             the beginning of the device.  The whole device is erased by
             default unless one or both of these options are presented.

             The argument may be suffixed with one of K, M, G, T, P or E
             (either upper or lower case) to indicate a multiple of Kilobytes,
             Megabytes, Gigabytes, Terabytes, Petabytes or Exabytes,
             respectively.

     -q      Do not output anything except of possible error messages (quiet
             mode).  Overrides -v.

     -r rfile
             Uses the length of given rfile as length of the region to erase.
             The whole device is erased by default.

     -v      Show offset and length of actual region being erased, in bytes.

     Later options override previous ones.

     Note that actual success of the operation depends of underlying device
     driver such as ada(4), da(4) and others.  Refer to corresponding manual
     pages for detail on possible caveats in low level support for ATA TRIM or
     SCSI UNMAP commands.

EXIT STATUS

     The trim utility exits 0 on success, and >0 if an error occurs.  If the
     final erase operation fails for an argument, the trim utility returns
     exit code 1.  It can also return one of the exit codes defined in
     sysexits(3), as follows:

     EX_USAGE        The specified offset or length of the region is
                     incorrect.

     EX_OSERR        There is no enough memory to proceed.

     EX_NOINPUT      The specified rfile cannot be opened (perhaps, it does
                     not exist).

     EX_IOERR        The specified rfile cannot be examined for its size due
                     to some system input/output error.

     EX_DATAERR      The specified rfile is not regular file, directory nor
                     special device, so its size cannot be examined.

     EX_UNAVAILABLE  The specified rfile is special device file not supporting
                     DIOCGMEDIASIZE ioctl(2) (probably not a disk), so its
                     size cannot be examined.

SEE ALSO

     ioctl(2), sysexits(3), ada(4), da(4), nda(4), fsck_ffs(8), zpool-trim(8)

HISTORY

     The trim utility first appeared in FreeBSD 12.1.

AUTHORS

     The trim utility was written by Eugene Grosbein <eugen@FreeBSD.org>.

FreeBSD 15.1-STABLE-HBSD       December 9, 2025                        TRIM(8)