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 2013-08-09 "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
 106 Synonym:
 107 .BR NORM .
 108 .TP
 109 .B FILE \fIcolor-sequence\fR
 110 Specifies the color used for a regular file.
 111 .TP
 112 .B DIR \fIcolor-sequence\fR
 113 Specifies the color used for directories.
 114 .TP
 115 .B LINK \fIcolor-sequence\fR
 116 Specifies the color used for a symbolic link.
 117
 118 Synonyms:
 119 .BR LNK ,
 120 .BR SYMLINK .
 121 .TP
 122 .B ORPHAN \fIcolor-sequence\fR
 123 Specifies the color used for an orphaned symbolic link (one which
 124 points to a nonexistent file).
 125 If this is unspecified,
 126 .B ls
 127 will use the
 128 .B LINK
 129 color instead.
 130 .TP
 131 .B MISSING \fIcolor-sequence\fR
 132 Specifies the color used for a missing file (a nonexistent file which
 133 nevertheless has a symbolic link pointing to it).
 134 If this is unspecified,
 135 .B ls
 136 will use the
 137 .B FILE
 138 color instead.
 139 .TP
 140 .B FIFO \fIcolor-sequence\fR
 141 Specifies the color used for a FIFO (named pipe).
 142
 143 Synonym:
 144 .BR PIPE .
 145 .TP
 146 .B SOCK \fIcolor-sequence\fR
 147 Specifies the color used for a socket.
 148 .TP
 149 .B DOOR \fIcolor-sequence\fR
 150 (Supported since fileutils 4.1)
 151 Specifies the color used for a door (Solaris 2.5 and later).
 152 .TP
 153 .B BLK \fIcolor-sequence\fR
 154 Specifies the color used for a block device special file.
 155
 156 Synonym:
 157 .BR BLOCK .
 158 .TP
 159 .B CHR \fIcolor-sequence\fR
 160 Specifies the color used for a character device special file.
 161
 162 Synonym:
 163 .BR CHAR .
 164 .TP
 165 .B EXEC \fIcolor-sequence\fR
 166 Specifies the color used for a file with the executable attribute set.
 167 .TP
 168 .B SUID \fIcolor-sequence\fR
 169 Specifies the color used for a file with the set-user-ID attribute set.
 170
 171 Synonym:
 172 .BR SETUID .
 173 .TP
 174 .B SGID \fIcolor-sequence\fR
 175 Specifies the color used for a file with the set-group-ID attribute set.
 176
 177 Synonym:
 178 .BR SETGID .
 179 .TP
 180 .B STICKY \fIcolor-sequence\fR
 181 Specifies the color used for a directory with the sticky attribute set.
 182 .TP
 183 .B STICKY_OTHER_WRITABLE \fIcolor-sequence\fR
 184 Specifies the color used for a other-writable directory with the executable attribute set.
 185
 186 Synonym:
 187 .BR OWT .
 188 .TP
 189 .B OTHER_WRITABLE \fIcolor-sequence\fR
 190 Specifies the color used for a other-writable directory without the executable attribute set.
 191
 192 Synonym:
 193 .BR OWR .
 194 .TP
 195 .B LEFTCODE \fIcolor-sequence\fR
 196 Specifies the
 197 .I "left code"
 198 for non-ISO\ 6429 terminals (see below).
 199
 200 Synonym:
 201 .BR LEFT .
 202 .TP
 203 .B RIGHTCODE \fIcolor-sequence\fR
 204 Specifies the
 205 .I "right code"
 206 for non-ISO\ 6429 terminals (see below).
 207
 208 Synonym:
 209 .BR RIGHT .
 210 .TP
 211 .B ENDCODE \fIcolor-sequence\fR
 212 Specifies the
 213 .I "end code"
 214 for non-ISO\ 6429 terminals (see below).
 215
 216 Synonym:
 217 .BR END .
 218 .TP
 219 \fB*\fIextension\fR \fIcolor-sequence\fR
 220 Specifies the color used for any file that ends in \fIextension\fR.
 221 .TP
 222 \fB .\fIextension\fR \fIcolor-sequence\fR
 223 Same as \fB*\fR.\fIextension\fR.
 224 Specifies the color used for any file that
 225 ends in .\fIextension\fR.
 226 Note that the period is included in the
 227 extension, which makes it impossible to specify an extension not
 228 starting with a period, such as
 229 .B ~
 230 for
 231 .B emacs
 232 backup files.
 233 This form should be considered obsolete.
 234 .SS ISO 6429 (ANSI) color sequences
 235 Most color-capable ASCII terminals today use ISO 6429 (ANSI) color sequences,
 236 and many common terminals without color capability, including
 237 .B xterm
 238 and the widely used and cloned DEC VT100, will recognize ISO 6429 color
 239 codes and harmlessly eliminate them from the output or emulate them.
 240 .B ls
 241 uses ISO 6429 codes by default, assuming colorization is enabled.
 242
 243 ISO 6429 color sequences are composed of sequences of numbers
 244 separated by semicolons.
 245 The most common codes are:
 246 .sp
 247 .RS
 248 .TS
 249 l l.
 250  0      to restore default color
 251  1      for brighter colors
 252  4      for underlined text
 253  5      for flashing text
 254 30      for black foreground
 255 31      for red foreground
 256 32      for green foreground
 257 33      for yellow (or brown) foreground
 258 34      for blue foreground
 259 35      for purple foreground
 260 36      for cyan foreground
 261 37      for white (or gray) foreground
 262 40      for black background
 263 41      for red background
 264 42      for green background
 265 43      for yellow (or brown) background
 266 44      for blue background
 267 45      for purple background
 268 46      for cyan background
 269 47      for white (or gray) background
 270 .TE
 271 .RE
 272 .sp
 273 Not all commands will work on all systems or display devices.
 274 .PP
 275 .B ls
 276 uses the following defaults:
 277 .sp
 278 .TS
 279 lb l l.
 280 NORMAL  0               Normal (nonfilename) text
 281 FILE    0               Regular file
 282 DIR     32              Directory
 283 LINK    36              Symbolic link
 284 ORPHAN  undefined       Orphaned symbolic link
 285 MISSING undefined       Missing file
 286 FIFO    31              Named pipe (FIFO)
 287 SOCK    33              Socket
 288 BLK     44;37           Block device
 289 CHR     44;37           Character device
 290 EXEC    35              Executable file
 291 .TE
 292 .sp
 293 A few terminal programs do not recognize the default
 294 properly.
 295 If all text gets colorized after you do a directory
 296 listing, change the
 297 .B NORMAL
 298 and
 299 .B FILE
 300 codes to the numerical codes for your normal foreground and background
 301 colors.
 302 .SS Other terminal types (advanced configuration)
 303 If you have a color-capable (or otherwise highlighting) terminal (or
 304 printer!) which uses a different set of codes, you can still generate
 305 a suitable setup.
 306 To do so, you will have to use the
 307 .BR LEFTCODE ,
 308 .BR RIGHTCODE ,
 309 and
 310 .B ENDCODE
 311 definitions.
 312 .PP
 313 When writing out a filename,
 314 .B ls
 315 generates the following output sequence:
 316 .B LEFTCODE
 317 .I typecode
 318 .B RIGHTCODE
 319 .I filename
 320 .BR ENDCODE ,
 321 where the
 322 .I typecode
 323 is the color sequence that depends on the type or name of file.
 324 If the
 325 .B ENDCODE
 326 is undefined, the sequence
 327 .B "LEFTCODE NORMAL RIGHTCODE"
 328 will be used instead.
 329 The purpose of the left- and rightcodes is
 330 merely to reduce the amount of typing necessary (and to hide ugly
 331 escape codes away from the user).
 332 If they are not appropriate for
 333 your terminal, you can eliminate them by specifying the respective
 334 keyword on a line by itself.
 335 .PP
 336 .B NOTE:
 337 If the
 338 .B ENDCODE
 339 is defined in the global section of the setup file, it
 340 .I cannot
 341 be undefined in a terminal-specific section of the file.
 342 This means any
 343 .B NORMAL
 344 definition will have no effect.
 345 A different
 346 .B ENDCODE
 347 can, however, be specified, which would have the same effect.
 348 .SS Escape sequences
 349 To specify control- or blank characters in the color sequences or
 350 filename extensions, either C-style \e-escaped notation or
 351 .BR stty \-style
 352 ^-notation can be used.
 353 The C-style notation
 354 includes the following characters:
 355 .sp
 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^     Caret (^)
 373 \e#     Hash mark (#)
 374 .TE
 375 .RE
 376 .sp
 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 ~/.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 .sp
 399 .RS
 400 .TS
 401 lb l.
 402 LEFTCODE        \ee[
 403 RIGHTCODE       m
 404 .TE
 405 .RE
 406 .sp
 407 The default
 408 .B ENDCODE
 409 is undefined.
 410 .SH SEE ALSO
 411 .BR dircolors (1),
 412 .BR ls (1),
 413 .BR stty (1),
 414 .BR xterm (1)