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