truncate

Overview ¶

Package truncate implements the truncate builtin command.

truncate — shrink or extend the size of a file to a specified size

Usage: truncate [OPTION]... FILE...

Shrink or extend the size of each FILE to the specified size. A file that is larger than the specified size is truncated; a file that is smaller is extended (the extension reads as zero bytes). When the file does not yet exist it is created (mode 0666 & ~umask) unless --no-create is given.

All file operations go through the AllowedPaths sandbox. Targets whose *path* falls outside the sandbox are rejected with a permission error before any open syscall is issued. Path-based containment cannot see inode aliasing, so the sandbox additionally rejects any multiply linked regular file (link count above one) as a write target: a pre-existing hard link inside a read-write root could otherwise name an inode that is also named outside every configured root. See the hard link entry in AGENTS.md. This command is only available in remediation mode.

Accepted flags:

-s SIZE, --size=SIZE
    Set the file size to SIZE bytes. SIZE is a non-negative integer
    with an optional suffix.

    For K/M/G/T the leading letter is case-insensitive; for P/E the
    leading letter is uppercase-only (matching GNU truncate exactly).
    The trailing "B" and "iB" characters are always case-sensitive:

        K = k = KiB = kiB = 1024         KB = kB = 1000
        M = m = MiB = miB = 1024^2       MB = mB = 1000^2
        G = g = GiB = giB = 1024^3       GB = gB = 1000^3
        T = t = TiB = tiB = 1024^4       TB = tB = 1000^4
        P = PiB = 1024^5                 PB = 1000^5
        E = EiB = 1024^6                 EB = 1000^6

    Z/Y/R/Q (zetta/yotta/ronna/quetta) are rejected because their
    multipliers exceed int64. GNU coreutils with the standard 64-bit
    uintmax_t rejects these as well.

-c, --no-create
    Do not create files that do not already exist. Missing files are
    silently skipped (matching GNU truncate).

-h, --help
    Print this usage message to stdout and exit 0.

Out of scope (not implemented; rejected as unknown flags):

-r REF, --reference=FILE   set size from a reference file
-o, --io-blocks            treat SIZE as a block count
relative size modifiers in -s (+, -, <, >, /, %)

Exit codes:

0  All files processed successfully.
1  At least one file failed (invalid size, permission denied, missing
   file without -c, etc.). Processing continues across all operands so
   that a single failure does not abort the run; exit 1 is returned at
   the end if any operand failed.

Memory safety:

truncate performs no I/O on file contents — only metadata. The sandbox
opens the file with O_WRONLY (+ O_CREATE when allowed) and calls
ftruncate(2) on the resulting fd. No buffers are allocated proportional
to user input; the only user-controlled numeric is the size argument,
which is validated for overflow before reaching the kernel.