


DIRCOLORS(1L)					    DIRCOLORS(1L)


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.



								1





DIRCOLORS(1L)					    DIRCOLORS(1L)


	      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.



								2





DIRCOLORS(1L)					    DIRCOLORS(1L)


	      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).




								3





DIRCOLORS(1L)					    DIRCOLORS(1L)


       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:




								4





DIRCOLORS(1L)					    DIRCOLORS(1L)


	 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-
       specific section of the file.  This means any NORMAL defi-
       nition  will have no effect.  A different ENDCODE can how-
       ever 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)



								5





DIRCOLORS(1L)					    DIRCOLORS(1L)


	 \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)















								6


40;1HK
