dircolors

Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services

NAME

       dircolors - Set color parameters for ls(1)


SYNOPSIS

       eval `dircolors [-abckstzPS] [filename]`

       dircolors -v


DESCRIPTION

       dircolors  is  a program to generate a setup for the color
       version of GNU ls.  The setup  consists  of  an  LS_COLORS
       environment  variable  and  a  set of aliases.  For sh and
       ash, which lack aliases, shell functions are  substituted.
       The  dircolors  command  will  generally  be  run from the
       user's .profile, .cshrc or equivalent file, or the system-
       wide equivalents.

   OPTIONS
       -a, -s Assume the user is using a Bourne-style shell which
              does not support aliasing.  This is default if  the
              base  name  of the environment variable SHELL is sh
              or ash.  Instead a shell function is used.  If  the
              -P  option is also used, this function will need to
              spawn a  subshell;  this  is  slow  and  should  be
              avoided if possible.

       -b, -k Assume  the user is using a Bourne-style shell that
              supports Korn-style aliasing.  This is the  default
              if  the base name of the environment variable SHELL
              is bash or ksh.   You  may  want  to  specify  this
              option  explicitly  if  your  sh  is  really a more
              advanced  shell,  which  does  support   Korn-style
              aliasing.

       -z     Assume  the user is using a Bourne-style shell that
              supports Korn-style aliasing, but  differs  between
              string and list environment variables.  This is the
              default is the base name of the  environment  vari-
              able SHELL is zsh.

       -c, -t Assume  the user is using a C-style shell.  This is
              the default if the base  name  of  the  environment
              variable SHELL is csh or tcsh.

       -P     Do not seek the path to find the location of the ls
              binary.  By default, dircolors will find the  loca-
              tion  of  the  ls binary at the time it is run, and
              include it in the shell function  or  alias,  which
              for  most  shells  results  in  a significant speed
              improvement.

       -S     Set colorization to no if  the  terminal  does  not
              occur  in  any  TERM  statement, even if there is a
              COLOR statement in the global section of the  file.
              This is for compatibility with Slackware GNU ls for
              which the order of the statements did not matter.

       -v     Display a version string and exit.

   CONFIGURATION FILE
       If a filename is specified on the command line, it will be
       used  to  generate the setup, if not, the file .dir_colors
       in the users home directory will be used.   If  that  file
       does   not   exist   either,   the   system-wide  file  of
       /usr/etc/DIR_COLORS will be used.

       The configuration file consists of several statements, one
       per  line.  Anything right of a hash mark (hash mark is at
       the beginning of a line or is preceded  by  at  least  one
       whitespace.  Blank lines are ignored.

       The  global  section of the file consists of any statement
       before the first TERM statement.   Any  statement  in  the
       global  section  of  the  file is considered valid for all
       terminal types  Following the global  section  is  one  or
       more terminal-specific sections, which are preceded by one
       or more TERM statements which specify the  terminal  types
       (as  given by the TERM environment variable) the following
       declarations apply for.  It is always possible to override
       a  global  declaration  by  a subsequent terminal-specific
       one.

       The following statements are recognized, case is insignif-
       icant:


       TERM terminal-type
              Starts  a  terminal-specific  section and specifies
              which terminal it applies to.  Multiple TERM state-
              ments can be used to create a section which applies
              for several terminal types.

       COLOR yes|all|no|none|tty
              Specifies  that  colorization  should   be   always
              enabled (yes or all), never enabled (no or none) or
              enabled only if the output  is  a  terminal  (tty).
              The default is no.

       EIGHTBIT yes|no
              Specifies that eight-bit ISO 8859 characters should
              be enabled by default.  Can for compatibility  rea-
              sons  also  be  specified as 1 for yes or 0 for no.
              The default is no.

       OPTIONS options
              Adds command line options to the default ls command
              line.  The options can be any valid ls command line
              options, and should include the leading minus sign.
              Please  note  that  dircolors  does  not verify the
              validity of these options.

       NORMAL color-sequence
              Specifies the color used for normal  (non-filename)
              text.

       FILE color-sequence
              Specifies the color used for a regular file.

       DIR color-sequence
              Specifies the color used for directories.

       LINK color-sequence
              Specifies the color used for a symbolic link.

       ORPHAN color-sequence
              Specifies  the color used for an orphanned symbolic
              link (one which points to a nonexistent file).   If
              this  is  unspecified,  ls  will use the LINK color
              instead.

       MISSING color-sequence
              Specifies the color used  for  a  missing  file  (a
              nonexistent  file which nevertheless has a symbolic
              link pointing to it).  If this is  unspecified,  ls
              will use the FILE color instead.

       FIFO color-sequence
              Specifies the color used for a FIFO (named pipe).

       SOCK color-sequence
              Specifies the color used for a socket.

       BLK color-sequence
              Specifies the color used for a block device special
              file.

       CHR color-sequence
              Specifies the color used  for  a  character  device
              special file.

       EXEC color-sequence
              Specifies  the  color used for a file with the exe-
              cutable attribute set.

       LEFTCODE color-sequence
              Specifies the left code for non-ISO 6429  terminals
              (see below).

       RIGHTCODE color-sequence
              Specifies the right code for non-ISO 6429 terminals
              (see below).

       ENDCODE color-sequence
              Specifies the end code for  non-ISO 6429  terminals
              (see below).

       *extension color-sequence
              Specifies  the color used for any file that ends in
              extension.

        .extension color-sequence
              Same as *.extension.  Specifies the color used  for
              any  file  that  ends in .extension.  Note that the
              period is included in the extension, which makes it
              impossible  to  specify  an  extension not starting
              with a period, such as ~ for  emacs  backup  files.
              This form should be considered obsolete.


ISO 6429 (ANSI) COLOR SEQUENCES

       Most  color-capable  ASCII  terminals  today  use ISO 6429
       (ANSI) color sequences, and many common terminals  without
       color  capability, including xterm and the widely used and
       cloned DEC VT100, will recognize ISO 6429 color codes  and
       harmlessly eliminate them from the output or emulate them.
       ls uses ISO 6429 codes by default,  assuming  colorization
       is enabled.

       ISO 6429 color sequences are composed of sequences of num-
       bers separated by semicolons.  The most common codes are:

          0        to restore default color
          1        for brighter colors
          4        for underlined text
          5        for flashing text
         30        for black foreground
         31        for red foreground
         32        for green foreground
         33        for yellow (or brown) foreground
         34        for blue foreground
         35        for purple foreground
         36        for cyan foreground
         37        for white (or gray) foreground
         40        for black background
         41        for red background
         42        for green background
         43        for yellow (or brown) background
         44        for blue background
         45        for purple background
         46        for cyan background
         47        for white (or gray) background

       Not all commands will  work  on  all  systems  or  display
       devices.

       ls uses the following defaults:

         NORMAL    0              Normal (non-filename) text
         FILE      0              Regular file
         DIR       32             Directory
         LINK      36             Symbolic link
         ORPHAN    undefined      Orphanned symbolic link
         MISSING   undefined      Missing file
         FIFO      31             Named pipe (FIFO)
         SOCK      33             Socket
         BLK       44;37          Block device
         CHR       44;37          Character device
         EXEC      35             Executable file

       A few terminal programs do not recognize the default prop-
       erly.  If all text gets colorized after you do a directory
       listing, change the NORMAL and FILE codes to the numerical
       codes for your normal foreground and background colors.


OTHER TERMINAL TYPES (ADVANCED CONFIGURATION)

       If you have a color-capable  (or  otherwise  highlighting)
       terminal  (or  printer!)  which  uses  a  different set of
       codes, you can still generate a suitable setup.  To do  so
       you  will have to use the LEFTCODE, RIGHTCODE, and ENDCODE
       definitions.

       When writing out a filename, ls  generates  the  following
       output sequence: LEFTCODE typecode RIGHTCODE filename END-
       CODE, where  the  typecode  is  the  color  sequence  that
       depends  on  the  type or name of file.  If the ENDCODE is
       undefined, the sequence LEFTCODE NORMAL RIGHTCODE will  be
       used  instead.  The purpose of the left- and rightcodes is
       merely to reduce the amount of typing  necessary  (and  to
       hide  ugly  escape codes away from the user).  If they are
       not appropriate for your terminal, you can eliminate  them
       by  specifying the respective keyword on a line by itself.

       NOTE: If the ENDCODE is defined in the global  section  of
       the  setup file, it cannot be undefined in a terminal-spe-
       cific section of the file.  This means any NORMAL  defini-
       tion will have no effect.  A different ENDCODE can however
       be specified, which would have the same effect.


ESCAPE SEQUENCES

       To specify control-  or  blank  characters  in  the  color
       sequences or filename extensions, either C-style \-escaped
       notation, or stty-style ^-notation can be  used.   The  C-
       style notation includes the following characters:

         \a        Bell (ASCII 7)
         \b        Backspace (ASCII 8)
         \e        Escape (ASCII 27)
         \f        Form feed (ASCII 12)
         \n        Newline (ASCII 10)
         \r        Carriage Return (ASCII 13)
         \t        Tab (ASCII 9)
         \v        Vertical Tab (ASCII 11)
         \?        Delete (ASCII 127)
         \nnn      Any character (octal notation)
         \xnnn     Any character (hexadecimal notation)
         \_        Space
         \\        Backslash (\)
         \^        Caret (^)
         \#        Hash mark (#)

       Please  note  that escapes are necessary to enter a space,
       backslash, caret or any control character anywhere in  the
       string, as well as a hash mark as the first character.


NOTES

       The  default LEFTCODE and RIGHTCODE definitions, which are
       used by ISO 6429 terminals are:

         LEFTCODE  \e[
         RIGHTCODE m

       The default ENDCODE is undefined.


AUTHOR

       H. Peter Anvin  <Peter.Anvin@linux.org>  with  input  from
       Patrick Volkerding, creator of the Slackware Linux distri-
       bution.


BUGS

       Currently is  somewhat  poorly  integrated  into  the  GNU
       fileutils  package.  For example, it does not support long
       options and is probably  pickier  about  POSIX  violations
       (i.e. less portable) than the rest of the programs.

       The  support  for non-ISO 6429 terminals is a kluge at the
       very best.


FILES

       /usr/etc/DIR_COLORS   System-wide setup file
       ~/.dir_colors         User setup file


SEE ALSO

       ls(1), stty(1), xterm(1)
Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.