original/man5/dir_colors.5

   1 .\" manpage for /etc/dir_colors, config file for dircolors(1)
   2 .\" extracted from color-ls 3.12.0.3 dircolors(1) manpage
   3 .\"
   4 .\" %%%LICENSE_START(LDPv1)
   5 .\" This file may be copied under the conditions described
   6 .\" in the LDP GENERAL PUBLIC LICENSE, Version 1, September 1998
   7 .\" that should have been distributed together with this file.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" Modified Sat Dec 22 22:25:33 2001 by Martin Schulze <joey@infodrom.org>
  11 .\"
  12 .TH DIR_COLORS 5 2001-12-26 "GNU" "Linux User Manual"
  13 .SH NAME
  14 dir_colors \- configuration file for dircolors(1)
  15 .SH DESCRIPTION
  16 The program
  17 .BR ls (1)
  18 uses the environment variable
  19 .B LS_COLORS
  20 to determine the colors in which the filenames are to be displayed.
  21 This environment variable is usually set by a command like
  22
  23 .RS
  24 eval \`dircolors some_path/dir_colors\`
  25 .RE
  26
  27 found in a system default shell initialization file, like
  28 .I /etc/profile
  29 or
  30 .IR /etc/csh.cshrc .
  31 (See also
  32 .BR dircolors (1).)
  33 Usually, the file used here is
  34 .I /etc/DIR_COLORS
  35 and can be overridden by a
  36 .I .dir_colors
  37 file in one's home directory.
  38 .PP
  39 This configuration file consists of several statements, one per line.
  40 Anything right of a hash mark (#) is treated as a comment, if the
  41 hash mark is at the beginning of a line or is preceded by at least one
  42 whitespace.
  43 Blank lines are ignored.
  44 .PP
  45 The
  46 .I global
  47 section of the file consists of any statement before the first
  48 .B TERM
  49 statement.
  50 Any statement in the global section of the file is
  51 considered valid for all terminal types.
  52 Following the global section
  53 is one or more
  54 .I terminal-specific
  55 sections, preceded by one or more
  56 .B TERM
  57 statements which specify the terminal types (as given by the
  58 .B TERM
  59 environment variable) the following declarations apply to.
  60 It is always possible to override a global declaration by a subsequent
  61 terminal-specific one.
  62 .PP
  63 The following statements are recognized; case is insignificant:
  64 .TP
  65 .B TERM \fIterminal-type\fR
  66 Starts a terminal-specific section and specifies which terminal it
  67 applies to.
  68 Multiple
  69 .B TERM
  70 statements can be used to create a section which applies for several
  71 terminal types.
  72 .TP
  73 .B COLOR yes|all|no|none|tty
  74 (Slackware only; ignored by GNU
  75 .BR dircolors (1).)
  76 Specifies that colorization should always be enabled (\fIyes\fR or
  77 \fIall\fR), never enabled (\fIno\fR or \fInone\fR), or enabled only if
  78 the output is a terminal (\fItty\fR).
  79 The default is \fIno\fR.
  80 .TP
  81 .B EIGHTBIT yes|no
  82 (Slackware only; ignored by GNU
  83 .BR dircolors (1).)
  84 Specifies that eight-bit ISO 8859 characters should be enabled by
  85 default.
  86 For compatibility reasons, this can also be specified as 1 for
  87 \fIyes\fR or 0 for \fIno\fR.
  88 The default is \fIno\fR.
  89 .TP
  90 .B OPTIONS \fIoptions\fR
  91 (Slackware only; ignored by GNU
  92 .BR dircolors (1).)
  93 Adds command-line options to the default
  94 .B ls
  95 command line.
  96 The options can be any valid
  97 .B ls
  98 command-line options, and should include the leading minus sign.
  99 Note that
 100 .B dircolors
 101 does not verify the validity of these options.
 102 .TP
 103 .B NORMAL \fIcolor-sequence\fR
 104 Specifies the color used for normal (nonfilename) text.
 105 .TP
 106 .B FILE \fIcolor-sequence\fR
 107 Specifies the color used for a regular file.
 108 .TP
 109 .B DIR \fIcolor-sequence\fR
 110 Specifies the color used for directories.
 111 .TP
 112 .B LINK \fIcolor-sequence\fR
 113 Specifies the color used for a symbolic link.
 114 .TP
 115 .B ORPHAN \fIcolor-sequence\fR
 116 Specifies the color used for an orphaned symbolic link (one which
 117 points to a nonexistent file).
 118 If this is unspecified,
 119 .B ls
 120 will use the
 121 .B LINK
 122 color instead.
 123 .TP
 124 .B MISSING \fIcolor-sequence\fR
 125 Specifies the color used for a missing file (a nonexistent file which
 126 nevertheless has a symbolic link pointing to it).
 127 If this is unspecified,
 128 .B ls
 129 will use the
 130 .B FILE
 131 color instead.
 132 .TP
 133 .B FIFO \fIcolor-sequence\fR
 134 Specifies the color used for a FIFO (named pipe).
 135 .TP
 136 .B SOCK \fIcolor-sequence\fR
 137 Specifies the color used for a socket.
 138 .TP
 139 .B DOOR \fIcolor-sequence\fR
 140 (Supported since fileutils 4.1)
 141 Specifies the color used for a door (Solaris 2.5 and later).
 142 .TP
 143 .B BLK \fIcolor-sequence\fR
 144 Specifies the color used for a block device special file.
 145 .TP
 146 .B CHR \fIcolor-sequence\fR
 147 Specifies the color used for a character device special file.
 148 .TP
 149 .B EXEC \fIcolor-sequence\fR
 150 Specifies the color used for a file with the executable attribute set.
 151 .TP
 152 .B LEFTCODE \fIcolor-sequence\fR
 153 Specifies the
 154 .I "left code"
 155 for non-ISO\ 6429 terminals (see below).
 156 .TP
 157 .B RIGHTCODE \fIcolor-sequence\fR
 158 Specifies the
 159 .I "right code"
 160 for non-ISO\ 6429 terminals (see below).
 161 .TP
 162 .B ENDCODE \fIcolor-sequence\fR
 163 Specifies the
 164 .I "end code"
 165 for non-ISO\ 6429 terminals (see below).
 166 .TP
 167 \fB*\fIextension\fR \fIcolor-sequence\fR
 168 Specifies the color used for any file that ends in \fIextension\fR.
 169 .TP
 170 \fB .\fIextension\fR \fIcolor-sequence\fR
 171 Same as \fB*\fR.\fIextension\fR.
 172 Specifies the color used for any file that
 173 ends in .\fIextension\fR.
 174 Note that the period is included in the
 175 extension, which makes it impossible to specify an extension not
 176 starting with a period, such as
 177 .B ~
 178 for
 179 .B emacs
 180 backup files.
 181 This form should be considered obsolete.
 182 .SS ISO 6429 (ANSI) color sequences
 183 Most color-capable ASCII terminals today use ISO 6429 (ANSI) color sequences,
 184 and many common terminals without color capability, including
 185 .B xterm
 186 and the widely used and cloned DEC VT100, will recognize ISO 6429 color
 187 codes and harmlessly eliminate them from the output or emulate them.
 188 .B ls
 189 uses ISO 6429 codes by default, assuming colorization is enabled.
 190
 191 ISO 6429 color sequences are composed of sequences of numbers
 192 separated by semicolons.
 193 The most common codes are:
 194 .sp
 195 .RS +.2i
 196 .ta 1.0i
 197 .nf
 198  0     to restore default color
 199  1     for brighter colors
 200  4     for underlined text
 201  5     for flashing text
 202 30     for black foreground
 203 31     for red foreground
 204 32     for green foreground
 205 33     for yellow (or brown) foreground
 206 34     for blue foreground
 207 35     for purple foreground
 208 36     for cyan foreground
 209 37     for white (or gray) foreground
 210 40     for black background
 211 41     for red background
 212 42     for green background
 213 43     for yellow (or brown) background
 214 44     for blue background
 215 45     for purple background
 216 46     for cyan background
 217 47     for white (or gray) background
 218 .fi
 219 .RE
 220 .sp
 221 Not all commands will work on all systems or display devices.
 222 .PP
 223 .B ls
 224 uses the following defaults:
 225 .sp
 226 .RS +.2i
 227 .ta 1.0i 2.5i
 228 .nf
 229 \fBNORMAL\fR   0       Normal (nonfilename) text
 230 \fBFILE\fR     0       Regular file
 231 \fBDIR\fR      32      Directory
 232 \fBLINK\fR     36      Symbolic link
 233 \fBORPHAN\fR   undefined       Orphaned symbolic link
 234 \fBMISSING\fR  undefined       Missing file
 235 \fBFIFO\fR     31      Named pipe (FIFO)
 236 \fBSOCK\fR     33      Socket
 237 \fBBLK\fR      44;37   Block device
 238 \fBCHR\fR      44;37   Character device
 239 \fBEXEC\fR     35      Executable file
 240 .fi
 241 .RE
 242 .sp
 243 A few terminal programs do not recognize the default
 244 properly.
 245 If all text gets colorized after you do a directory
 246 listing, change the
 247 .B NORMAL
 248 and
 249 .B FILE
 250 codes to the numerical codes for your normal foreground and background
 251 colors.
 252 .SS Other terminal types (advanced configuration)
 253 If you have a color-capable (or otherwise highlighting) terminal (or
 254 printer!) which uses a different set of codes, you can still generate
 255 a suitable setup.
 256 To do so, you will have to use the
 257 .BR LEFTCODE ,
 258 .BR RIGHTCODE ,
 259 and
 260 .B ENDCODE
 261 definitions.
 262 .PP
 263 When writing out a filename,
 264 .B ls
 265 generates the following output sequence:
 266 .B LEFTCODE
 267 .I typecode
 268 .B RIGHTCODE
 269 .I filename
 270 .BR ENDCODE ,
 271 where the
 272 .I typecode
 273 is the color sequence that depends on the type or name of file.
 274 If the
 275 .B ENDCODE
 276 is undefined, the sequence
 277 .B "LEFTCODE NORMAL RIGHTCODE"
 278 will be used instead.
 279 The purpose of the left- and rightcodes is
 280 merely to reduce the amount of typing necessary (and to hide ugly
 281 escape codes away from the user).
 282 If they are not appropriate for
 283 your terminal, you can eliminate them by specifying the respective
 284 keyword on a line by itself.
 285 .PP
 286 .B NOTE:
 287 If the
 288 .B ENDCODE
 289 is defined in the global section of the setup file, it
 290 .I cannot
 291 be undefined in a terminal-specific section of the file.
 292 This means any
 293 .B NORMAL
 294 definition will have no effect.
 295 A different
 296 .B ENDCODE
 297 can, however, be specified, which would have the same effect.
 298 .SS Escape sequences
 299 To specify control- or blank characters in the color sequences or
 300 filename extensions, either C-style \e-escaped notation or
 301 .BR stty \-style
 302 ^-notation can be used.
 303 The C-style notation
 304 includes the following characters:
 305 .sp
 306 .RS +.2i
 307 .ta 1.0i
 308 .nf
 309 \fB\ea\fR      Bell (ASCII 7)
 310 \fB\eb\fR      Backspace (ASCII 8)
 311 \fB\ee\fR      Escape (ASCII 27)
 312 \fB\ef\fR      Form feed (ASCII 12)
 313 \fB\en\fR      Newline (ASCII 10)
 314 \fB\er\fR      Carriage Return (ASCII 13)
 315 \fB\et\fR      Tab (ASCII 9)
 316 \fB\ev\fR      Vertical Tab (ASCII 11)
 317 \fB\e?\fR      Delete (ASCII 127)
 318 \fB\e\fInnn\fR Any character (octal notation)
 319 \fB\ex\fInnn\fR        Any character (hexadecimal notation)
 320 \fB\e_\fR      Space
 321 \fB\e\e\fR     Backslash (\e)
 322 \fB\e^\fR      Caret (^)
 323 \fB\e#\fR      Hash mark (#)
 324 .fi
 325 .RE
 326 .sp
 327 Please note that escapes are necessary to enter a space, backslash,
 328 caret, or any control character anywhere in the string, as well as a
 329 hash mark as the first character.
 330 .SH FILES
 331 .TP
 332 .I /etc/DIR_COLORS
 333 System-wide configuration file.
 334 .TP
 335 .I ~/.dir_colors
 336 Per-user configuration file.
 337 .PP
 338 This page describes the
 339 .B dir_colors
 340 file format as used in the fileutils-4.1 package;
 341 other versions may differ slightly.
 342 .SH NOTES
 343 The default
 344 .B LEFTCODE
 345 and
 346 .B RIGHTCODE
 347 definitions, which are used by ISO 6429 terminals are:
 348 .sp
 349 .RS +.2i
 350 .ta 1.0i
 351 .nf
 352 \fBLEFTCODE\fR  \ee[
 353 \fBRIGHTCODE\fR m
 354 .fi
 355 .RE
 356 .sp
 357 The default
 358 .B ENDCODE
 359 is undefined.
 360 .SH SEE ALSO
 361 .BR dircolors (1),
 362 .BR ls (1),
 363 .BR stty (1),
 364 .BR xterm (1)