man5/dir_colors.5

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