tail

Documentation

Overview

Package tail implements the tail builtin command.

tail — output the last part of files

Usage: tail [OPTION]... [FILE]...

Print the last 10 lines of each FILE to standard output. With more than one FILE, precede each with a header giving the file name. With no FILE, or when FILE is -, read standard input.

Accepted flags:

-n N, --lines=N
    Output the last N lines (default 10). A leading '+' (e.g. +5) means
    output starting from line N (1-based offset from the beginning).

-c N, --bytes=N
    Output the last N bytes instead of lines. A leading '+' means
    output starting from byte N (1-based offset from the beginning).
    If both -n and -c are specified, the last flag on the command line
    takes effect.

-q, --quiet, --silent
    Never print file name headers. --silent is an alias for --quiet.

-v, --verbose
    Always print file name headers, even when only one file is given.

-z, --zero-terminated
    Use NUL as the line delimiter instead of newline.

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

Rejected flags: -f, -F, --follow, --pid, --retry (not supported).

Exit codes:

0  All files processed successfully.
1  At least one error occurred (missing file, invalid argument, etc.).

Memory safety and correctness:

Line mode uses a ring buffer of size min(N, MaxRingLines) slots. Each slot
holds one line; lines exceeding MaxLineBytes cause a scanner error. The
ring buffer's total memory footprint is additionally capped at MaxRingBytes
(5 MiB). If the input has more lines than the ring can hold and N exceeds
MaxRingLines, tail returns an error rather than silently truncating output.

Byte mode uses a circular buffer of size min(N, MaxBytesBuffer). If the
input exceeds MaxBytesBuffer bytes and N exceeds MaxBytesBuffer, tail
returns an error rather than silently returning fewer bytes than requested.

Offset (+N) modes stream without buffering. All loops check ctx.Err() at
each iteration to honour the shell's execution timeout.

Infinite-stream protection:

Last-N-lines and last-N-bytes modes must consume the entire input before
emitting output. For non-regular-file inputs (pipes, stdin, character
devices) without a context deadline, execution would hang indefinitely.
To bound this, tail returns an error once total bytes read from such a
source exceed MaxTotalReadBytes (256 MiB). Regular files are not subject
to this limit because the OS guarantees they are finite.

Offset (+N) modes stream output incrementally and do not buffer to EOF,
so no read-limit guard is applied; large pipes work correctly.

Index

• Constants
• Variables

Constants

const MaxBytesBuffer = 5 << 20 // 5 MiB

MaxBytesBuffer is the maximum size of the circular byte buffer used in last-N-bytes mode.

const MaxCount = 1<<31 - 1 // 2 147 483 647

MaxCount is the maximum accepted line or byte count. Values above this are clamped to prevent huge theoretical allocations.

const MaxLineBytes = 1 << 20 // 1 MiB

MaxLineBytes is the per-line buffer cap for the line scanner.

const MaxRingBytes = 5 << 20 // 5 MiB

MaxRingBytes is the maximum total bytes the ring buffer may hold at any one time. Without this cap, MaxRingLines (100 000) × MaxLineBytes (1 MiB) yields a worst-case memory envelope of ~97.6 GiB. This constant reduces the bound to 5 MiB.

const MaxRingLines = 100_000

MaxRingLines is the maximum number of lines held in the ring buffer.

const MaxTotalReadBytes = 256 << 20 // 256 MiB

MaxTotalReadBytes is the maximum total bytes tail will consume from a single input source. Both last-N-lines and last-N-bytes modes must read the entire input before emitting output, so an infinite source without a context deadline would hang indefinitely. This limit bounds execution to a finite amount of work regardless of whether a timeout is configured.

Variables

var Cmd = builtins.Command{
	Name:        "tail",
	Description: "output the last part of files",
	MakeFlags:   registerFlags,
}

Cmd is the tail builtin command descriptor.