Decoded: pathchk (coreutils)

[Back to Project Main Page]

Note: This page explores the design of command-line utilities. It is not a user guide.
[GNU Manual] [POSIX requirement] [Linux man] [FreeBSD man]

Logical flow of pathchk command (coreutils)

Summary

pathchk - check file name validity and portability

[Source] [Code Walkthrough]

Lines of code: 423
Principal syscall: pathconf() (BSD/OSX syscall, standard library otherwise)
Support syscalls: lstat()
Options: 5 (2 short, 3 long)

No clear lineage. Possibly added between 43BSD and 44BSD
Added to Shellutils in November 1992 [First version]
Number of revisions: 129 [Code Evolution]

Helpers:
  • component_len() - Finds the length of the current component pointed to by f
  • component_start() - Finds the start of the next path component
  • no_leading_hyphen() - Checks if any path component contains a leading hyphen
  • portable_chars_only() - Checks if a file path contains only the 66 portable characters
  • validate_file_name() - Performs all of the path verification checks
External non-standard helpers:
  • error() - Outputs error message to standard error with possible process termination

Setup

The core concept underlying pathchk is POSIX portability. Thus, setup needs to verify limit conditions are known. It begins by checking or defining macros including:

  • _POSIX_PATH_MAX - Total path limit (worst case is 256)
  • _POSIX_NAME_MAX - Component name limit (worst case is 14)

main() begins by initializing four locals:

  • check_basic_portability - Flag the basic checks only (-p option)
  • check_extra_portability - flag for extra checks (-P option)
  • ok - Holds the worst-case return value of all validations
  • optc - The first character of the next option to parse

Parsing

Parsing pathchk determines which checks to perform: basic, extended, or everything. One or more target paths are subsequently passed as arguments

Parsing failures

These failure cases are explicitly checked:

  • No target provided
  • An unknown option is used

This failure result in a short error message followed by the usage instructions.

Execution

We verify each target file against the checks requested. The general strategy is to do the quick checks early, such as file name existance and hyphen usage. If all checks pass, then move on to more complex checks such as those that require breaking down path components.

For each target:

  • Check that there are no leading hyphens in file names
  • Check that the file name exists
  • Verify that only portable characters are used
  • Check that the final directory is searchable
  • Check that the total path length is valid
  • Quickly check if all components are shorter than the minimum possible length
  • Check the length of each individual component

Execution may stop processing a target if any of the checks fail. Note that this is the full list of possible checks. The actual checks on each pass depend on which options are selected.

Failure cases:

  • Leading hyphens in a file name component
  • Empty file name
  • File or path name exceeds the limit (warning)
  • pathconf() fails

[Back to Project Main Page]