lib/terminal-colors.d.5

   1 .\" terminal-colors.d.5 --
   2 .\" Copyright 2014 Ondrej Oprala <ooprala@redhat.com>
   3 .\" Copyright (C) 2014 Karel Zak <kzak@redhat.com>
   4 .\" Copyright 2014 Red Hat, Inc.
   5 .\" May be distributed under the GNU General Public License
   6 .TH "TERMINAL_COLORS.D" "5" "January 2014" "util-linux" "terminal-colors.d"
   7 .SH NAME
   8 terminal-colors.d \- Configure output colorization for various utilities
   9 .SH SYNOPSIS
  10 /etc/terminal-colors\&.d/[[\fIname\fR][@\fIterm\fR]\&.][\fItype\fR]
  11 .SH DESCRIPTION
  12 Files in this directory determine the default behavior for utilities
  13 when coloring output.
  14
  15 The
  16 .I name
  17 is a utility name.  The name is optional and when none is specified then the
  18 file is used for all unspecified utilities.
  19
  20 The
  21 .I term
  22 is a terminal identifier (the TERM environment variable).
  23 The terminal identifier is optional and when none is specified then the file
  24 is used for all unspecified terminals.
  25
  26 The
  27 .I type
  28 is a file type.  Supported file types are:
  29 .TP
  30 .B disable
  31 Turns off output colorization for all compatible utilities.
  32 .TP
  33 .B enable
  34 Turns on output colorization; any matching
  35 .B disable
  36 files are ignored.
  37 .TP
  38 .B scheme
  39 Specifies colors used for output.  The file format may be specific to the utility,
  40 the default format is described below.
  41 .PP
  42 If there are more files that match for a utility, then the file with the more
  43 specific filename wins.  For example, the filename "@xterm.scheme" has less
  44 priority than "dmesg@xterm.scheme".  The lowest priority are those files without a
  45 utility name and terminal identifier (e.g., "disable").
  46
  47 The user-specific
  48 .I $XDG_CONFIG_HOME/terminal-colors.d
  49 or
  50 .I $HOME/.config/terminal-colors.d
  51 overrides the global setting.
  52
  53 .SH DEFAULT SCHEME FILES FORMAT
  54 The following statement is recognized:
  55
  56 .RS
  57 .br
  58 .B "name color-sequence"
  59 .br
  60 .RE
  61
  62 The
  63 .B name
  64 is a logical name of color sequence (for example "error").  The names are
  65 specific to the utilities.  For more details always see the COLORS section
  66 in the man page for the utility.
  67
  68 The
  69 .B color-sequence
  70 is a color name, ASCII color sequences or escape sequences.
  71
  72 .SS Color names
  73 black, blink, blue, bold, brown, cyan, darkgray, gray, green, halfbright,
  74 lightblue, lightcyan, lightgray, lightgreen, lightmagenta, lightred, magenta,
  75 red, reset, reverse, and yellow.
  76
  77 .SS ANSI color sequences
  78 The color sequences are composed of sequences of numbers
  79 separated by semicolons.  The most common codes are:
  80 .sp
  81 .RS
  82 .TS
  83 l l.
  84  0      to restore default color
  85  1      for brighter colors
  86  4      for underlined text
  87  5      for flashing text
  88 30      for black foreground
  89 31      for red foreground
  90 32      for green foreground
  91 33      for yellow (or brown) foreground
  92 34      for blue foreground
  93 35      for purple foreground
  94 36      for cyan foreground
  95 37      for white (or gray) foreground
  96 40      for black background
  97 41      for red background
  98 42      for green background
  99 43      for yellow (or brown) background
 100 44      for blue background
 101 45      for purple background
 102 46      for cyan background
 103 47      for white (or gray) background
 104 .TE
 105 .RE
 106 .SS Escape sequences
 107 To specify control or blank characters in the color sequences,
 108 C-style \e-escaped notation can be used:
 109 .sp
 110 .RS
 111 .TS
 112 lb l.
 113 \ea     Bell (ASCII 7)
 114 \eb     Backspace (ASCII 8)
 115 \ee     Escape (ASCII 27)
 116 \ef     Form feed (ASCII 12)
 117 \en     Newline (ASCII 10)
 118 \er     Carriage Return (ASCII 13)
 119 \et     Tab (ASCII 9)
 120 \ev     Vertical Tab (ASCII 11)
 121 \e?     Delete (ASCII 127)
 122 \e_     Space
 123 \e\e    Backslash (\e)
 124 \e^     Caret (^)
 125 \e#     Hash mark (#)
 126 .TE
 127 .RE
 128 .sp
 129 Please note that escapes are necessary to enter a space, backslash,
 130 caret, or any control character anywhere in the string, as well as a
 131 hash mark as the first character.
 132
 133 For example, to use a red background for alert messages in the output of
 134 .BR dmesg (1),
 135 use:
 136
 137 .RS
 138 .br
 139 .B "echo 'alert 37;41' >> /etc/terminal-colors.d/dmesg.scheme"
 140 .br
 141 .RE
 142
 143 .SS Comments
 144 Lines where the first non-blank character is a # (hash) are ignored.
 145 Any other use of the hash character is not interpreted as introducing
 146 a comment.
 147
 148 .SH FILES
 149 .I $XDG_CONFIG_HOME/terminal-colors.d
 150 .br
 151 .I $HOME/.config/terminal-colors.d
 152 .br
 153 .I /etc/terminal-colors.d
 154
 155 .SH ENVIRONMENT
 156 .IP TERMINAL_COLORS_DEBUG=all
 157 enables debug output.
 158
 159 .SH EXAMPLE
 160 Disable colors for all compatible utilities:
 161 .RS
 162 .br
 163 .B "touch /etc/terminal-colors.d/disable"
 164 .br
 165 .RE
 166
 167 Disable colors for all compatible utils on a vt100 terminal:
 168 .RS
 169 .br
 170 .B "touch /etc/terminal-colors.d/@vt100.disable"
 171 .br
 172 .RE
 173
 174 Disable colors for all compatible utils except dmesg(1):
 175 .RS
 176 .br
 177 .B "touch /etc/terminal-colors.d/disable"
 178 .sp
 179 .B "touch /etc/terminal-colors.d/dmesg.enable"
 180 .br
 181 .RE
 182
 183 .SH COMPATIBILITY
 184 The terminal-colors.d functionality is currently supported by all util-linux
 185 utilities which provides colorized output.  For more details always see the
 186 COLORS section in the man page for the utility.
 187
 188 .SH AVAILABILITY
 189 terminal-colors.d is part of the util-linux package and is available from
 190 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 191 Linux Kernel Archive
 192 .UE .