| blob | 5c9a2be4e2d904715e629be17dc46efb42a3713b |
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 2020-08-13 "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 .PP
23 .RS
24 eval \`dircolors some_path/dir_colors\`
25 .RE
26 .PP
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 .IP
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 .IP
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 .IP
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 .IP
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 .IP
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 .IP
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 .IP
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 an other-writable directory with the executable attribute set.
185 .IP
186 Synonym:
187 .BR OWT .
188 .TP
189 .B OTHER_WRITABLE \fIcolor-sequence\fR
190 Specifies the color used for an other-writable directory without the executable attribute set.
191 .IP
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 .IP
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 .IP
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 .IP
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 \(ti
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 .PP
243 ISO 6429 color sequences are composed of sequences of numbers
244 separated by semicolons.
245 The most common codes are:
246 .RS
247 .TS
248 l l.
249 0 to restore default color
250 1 for brighter colors
251 4 for underlined text
252 5 for flashing text
253 30 for black foreground
254 31 for red foreground
255 32 for green foreground
256 33 for yellow (or brown) foreground
257 34 for blue foreground
258 35 for purple foreground
259 36 for cyan foreground
260 37 for white (or gray) foreground
261 40 for black background
262 41 for red background
263 42 for green background
264 43 for yellow (or brown) background
265 44 for blue background
266 45 for purple background
267 46 for cyan background
268 47 for white (or gray) background
269 .TE
270 .RE
271 .PP
272 Not all commands will work on all systems or display devices.
273 .PP
274 .B ls
275 uses the following defaults:
276 .TS
277 lb l l.
278 NORMAL 0 Normal (nonfilename) text
279 FILE 0 Regular file
280 DIR 32 Directory
281 LINK 36 Symbolic link
282 ORPHAN undefined Orphaned symbolic link
283 MISSING undefined Missing file
284 FIFO 31 Named pipe (FIFO)
285 SOCK 33 Socket
286 BLK 44;37 Block device
287 CHR 44;37 Character device
288 EXEC 35 Executable file
289 .TE
290 .PP
291 A few terminal programs do not recognize the default
292 properly.
293 If all text gets colorized after you do a directory
294 listing, change the
295 .B NORMAL
296 and
297 .B FILE
298 codes to the numerical codes for your normal foreground and background
299 colors.
300 .SS Other terminal types (advanced configuration)
301 If you have a color-capable (or otherwise highlighting) terminal (or
302 printer!) which uses a different set of codes, you can still generate
303 a suitable setup.
304 To do so, you will have to use the
305 .BR LEFTCODE ,
306 .BR RIGHTCODE ,
307 and
308 .B ENDCODE
309 definitions.
310 .PP
311 When writing out a filename,
312 .B ls
313 generates the following output sequence:
314 .B LEFTCODE
315 .I typecode
316 .B RIGHTCODE
317 .I filename
318 .BR ENDCODE ,
319 where the
320 .I typecode
321 is the color sequence that depends on the type or name of file.
322 If the
323 .B ENDCODE
324 is undefined, the sequence
325 .B "LEFTCODE NORMAL RIGHTCODE"
326 will be used instead.
327 The purpose of the left- and rightcodes is
328 merely to reduce the amount of typing necessary (and to hide ugly
329 escape codes away from the user).
330 If they are not appropriate for
331 your terminal, you can eliminate them by specifying the respective
332 keyword on a line by itself.
333 .PP
334 .B NOTE:
335 If the
336 .B ENDCODE
337 is defined in the global section of the setup file, it
338 .I cannot
339 be undefined in a terminal-specific section of the file.
340 This means any
341 .B NORMAL
342 definition will have no effect.
343 A different
344 .B ENDCODE
345 can, however, be specified, which would have the same effect.
346 .SS Escape sequences
347 To specify control- or blank characters in the color sequences or
348 filename extensions, either C-style \e-escaped notation or
349 .BR stty \-style
350 \(ha-notation can be used.
351 The C-style notation
352 includes the following characters:
353 .RS
354 .TS
355 lb l.
356 \ea Bell (ASCII 7)
357 \eb Backspace (ASCII 8)
358 \ee Escape (ASCII 27)
359 \ef Form feed (ASCII 12)
360 \en Newline (ASCII 10)
361 \er Carriage Return (ASCII 13)
362 \et Tab (ASCII 9)
363 \ev Vertical Tab (ASCII 11)
364 \e? Delete (ASCII 127)
365 \e\fInnn Any character (octal notation)
366 \ex\fInnn Any character (hexadecimal notation)
367 \e_ Space
368 \e\e Backslash (\e)
369 \e\(ha Caret (\(ha)
370 \e# Hash mark (#)
371 .TE
372 .RE
373 .PP
374 Note that escapes are necessary to enter a space, backslash,
375 caret, or any control character anywhere in the string, as well as a
376 hash mark as the first character.
377 .SH FILES
378 .TP
379 .I /etc/DIR_COLORS
380 System-wide configuration file.
381 .TP
382 .I \(ti/.dir_colors
383 Per-user configuration file.
384 .PP
385 This page describes the
386 .B dir_colors
387 file format as used in the fileutils-4.1 package;
388 other versions may differ slightly.
389 .SH NOTES
390 The default
391 .B LEFTCODE
392 and
393 .B RIGHTCODE
394 definitions, which are used by ISO 6429 terminals are:
395 .RS
396 .TS
397 lb l.
398 LEFTCODE \ee[
399 RIGHTCODE m
400 .TE
401 .RE
402 .PP
403 The default
404 .B ENDCODE
405 is undefined.
406 .SH SEE ALSO
407 .BR dircolors (1),
408 .BR ls (1),
409 .BR stty (1),
410 .BR xterm (1)