Decoded: dircolors (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 dircolors command (coreutils)

Summary

dircolors - color setup for ls

[Source] [Code Walkthrough]

Lines of code: 510
Principal syscall: write() (via puts() and fwrite())
Support syscalls: None
Options: 10 (3 short, 7 long)

Added to Coreutils in April 1996 [First version]
Number of revisions: 151

The dircolors utility is more complex than a simple wrapper because it uses obstacks to compose the intermediate work before translating output to a specific shell type. It's helpful to understand the expectations of the terminal (ISO 6429) in order to follow the mapping to the LS_COLORS environment variable.

Helpers:
  • append_quoted() - Escapes certain characters with backslashes as needed
  • dc_parse_file() - Opens a stream on a target file for parsing
  • dc_parse_stream() - Parses a file stream using the symbol/code table
  • guess_shell_syntax() - Determines the shell syntax type (Bourne or C)
  • parse_line() - Reads a line from the stream and handles spaces and comments
External non-standard helpers:
  • None

Setup

dircolors defines two global dictionaries, slack_codes and ls_codes. The dictionaries reference the same set of commands where the former is the mnemonic and the latter is the output form in LS_COLORS. The same index matches both (ex. slack_codes[3] is "RESET" and ls_codes[3] is "rs".

main() initializes the following:

  • ok - The final return status. Note overloaded usage
  • optc - The first character of the next option to process
  • print_database - Flag for the print database long option
  • syntax - The current shell syntax (Bourne, C, unknown)

Parsing

During parsing, we're collecting options and arguments to answer the following questions:

  • What kind of shell are we using?
  • Should we print the color configuration database?

Parsing failures

Parsing may fail in three ways:

  • Printing the configuration database and specifying an output shell format
  • Specifying a source configuration file while printing the database
  • An unknown option is used

User specified parsing failures result in a short error message followed by the usage instructions. Access related parsing errors die with an error message.

Execution

dircolors executes in two primary branches: Printing the current color configurations and setting the LS_COLORS variable.

Printing configuration

The configuration to output is held as a string array, G_line defined in dircolors.h, which is generated from dircolors.hin when coreutils is built.

Printing simply loops through each component of the string, printing to STDOUT with puts().

Setting configuration

Setting the LS_COLORS variable follows this logic:

  • Determine the shell type if possible and not already provided
  • Initialize and build the obstack for each configuration line item
  • Finalize the obstack, condensing the lines to a single string representation
  • Define the prefix and suffix based on shell type
  • Write the prefix to STDOUT
  • Write the configuration string to STDOUT
  • Write the suffix to STDOUT

Failure cases:

  • Unable to determine shell type
  • Unknown configuration keyword used
  • Improper configuration line format

All failures at this stage output an error message to STDERR and return without displaying usage help

[Back to Project Main Page]