original/man5/dir_colors.5

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