Check File Names Before You Ship Them with pathchk

You will use pathchk to reject file names that are invalid on the current system or unsafe to carry to POSIX systems. That is useful before creating an archive, generating a manifest, or passing names to a script that will run on another host. Allow about ten minutes. You need a shell and GNU coreutils; this guide only checks names and does not create, rename or delete files.

The examples use GNU coreutils 9.4, installed here as package version 9.4-3ubuntu6.3. The local manual describes pathchk as a diagnostic command, so treat its result as a gate for the next operation, not as a repair tool.

1. Check an ordinary name

Pass one or more names as operands. A successful check is silent and returns status 0:

$ pathchk 'reports/September.txt'
$ printf '%s\n' "$?"
0

The slash separates components. pathchk checks the name; it does not require the path to exist and it does not inspect the file contents. A name such as reports/September.txt can therefore be checked before the directory or file is created.

Checkpoint: if a script needs the result, test the command directly rather than parsing output:

if pathchk -- "$candidate"; then
    printf 'Name is acceptable: %s\n' "$candidate"
else
    printf 'Rejecting file name: %s\n' "$candidate" >&2
    exit 1
fi

The -- marks the end of options. Keep it when the name comes from a variable or another source, because a value beginning with a hyphen must be treated as a name, not as a new option.

2. Check names against POSIX limits

Use -p, or its long form --portability together with -P, when the name will cross system boundaries:

$ pathchk -p -- 'build/output.bin'
$ printf '%s\n' "$?"
0
$ pathchk -p -- 'a-name_that-is-portable'
$ printf '%s\n' "$?"
0

The local manual defines -p as checking for most POSIX systems. It is a portability check, not a conversion. A successful result does not rename the item, change its encoding, or make a future destination writable.

Use --portability when you want both POSIX checks and the stricter name checks described next:

$ pathchk --portability -- 'build/output.bin'
$ printf '%s\n' "$?"
0

Do not confuse a portable name with an existing path. If you need both guarantees, run a separate existence or access check after pathchk, for example test -r -- "$candidate" for a file you intend to read. That second command has a different question and can fail even when the name is valid.

3. Reject empty names and leading hyphens

Add -P when an empty name or a component beginning with - would be unsafe for your next tool:

$ pathchk -P -- '-draft.txt'
pathchk: leading '-' in a component of file name '-draft.txt'
$ printf '%s\n' "$?"
1
$ pathchk -P -- ''
pathchk: empty file name
$ printf '%s\n' "$?"
1

-P checks for empty names and leading hyphens. The operand after -- is still a name, so the diagnostic is about the data being checked rather than an attempt to invoke an option. This is especially useful before handing names to utilities whose option parsing differs between implementations.

The combined form is equivalent:

$ pathchk --portability -- '-draft.txt'
pathchk: leading '-' in a component of file name '-draft.txt'

Do not treat the diagnostic text as a stable machine interface. In scripts, use the exit status and log the rejected value separately. Messages can vary with locale and coreutils versions.

4. Validate a batch before changing anything

pathchk accepts multiple names, so validate the complete batch before starting an archive or rename operation:

$ pathchk --portability -- \
    'photos/2026-09-25.jpg' \
    'photos/meeting-notes.txt' \
    'photos/final-report.pdf'
$ printf '%s\n' "$?"
0

If any operand fails, the command reports the problem and returns non-zero. Stop the later operation, correct or exclude the bad input, then rerun the whole batch. This avoids the distraction trap of fixing one visible name while an unexamined name later fails halfway through a copy or export.

There is no elevated-privilege step here. Do not use sudo merely to validate a name. Running as root does not make a name portable and does not remove limits imposed by the destination filesystem or receiving program.

5. Investigate a length failure

A failure can identify the relevant limit and the component that exceeded it:

$ pathchk -p -- 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
pathchk: limit 14 exceeded by length 31 of file name component 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'

The exact limit depends on the check being performed and the system rules in force. Do not copy the number from this example into a general policy. Use the diagnostic to find the offending component, shorten the name deliberately, and rerun the same command. If a generated name is involved, fix the naming rule at its source so the next batch does not recreate the failure.

Keep a rejected input available while debugging. pathchk does not modify it, and there is nothing to undo. If a later command has already renamed or copied files, recovery belongs to that command's backup or version-control process, not to pathchk.

6. Confirm the version and options on a new host

Before relying on a detail in automation, confirm which implementation is installed:

$ pathchk --version
pathchk (GNU coreutils) 9.4

Use pathchk --help for the option summary on the host where the script will run. The documented options here are -p, -P, --portability, --help and --version. An implementation from another operating system may have different diagnostics or options, so do not silently assume GNU-specific behaviour when portability is the reason for the check.