| 1 |
.TH SETFONT 8 "24 October 2024" "kbd" |
| 2 |
.SH NAME |
| 3 |
setfont \- load EGA/VGA console screen font |
| 4 |
.SH SYNOPSIS |
| 5 |
.B setfont |
| 6 |
.RB [ -O |
| 7 |
.IR font+umap.orig ] |
| 8 |
.RB [ -o |
| 9 |
.IR font.orig ] |
| 10 |
.RB [ -om |
| 11 |
.IR cmap.orig ] |
| 12 |
.RB [ -ou |
| 13 |
.IR umap.orig ] |
| 14 |
.RB [ -\c |
| 15 |
.IR N ] |
| 16 |
.RI [ "font.new ...\&" ] |
| 17 |
.RB [ -m |
| 18 |
.IR cmap ] |
| 19 |
.RB [ -u |
| 20 |
.IR umap ] |
| 21 |
.RB [ -C |
| 22 |
.IR console ] |
| 23 |
.RB [ -h\c |
| 24 |
.IR H ] |
| 25 |
.RB [ -f ] |
| 26 |
.RB [ -v ] |
| 27 |
.RB [ -V ] |
| 28 |
.SH DESCRIPTION |
| 29 |
The |
| 30 |
.B setfont |
| 31 |
command reads a font from the file |
| 32 |
.I font.new |
| 33 |
and loads it into the EGA/VGA character generator, |
| 34 |
and optionally outputs the previous font. |
| 35 |
It can also load various mapping tables |
| 36 |
and output the previous versions. |
| 37 |
.LP |
| 38 |
If no args are given (or only the option |
| 39 |
.RI \- N |
| 40 |
for some number |
| 41 |
.IR N ), |
| 42 |
then a default |
| 43 |
.RI (8x N ) |
| 44 |
font is loaded (see below). |
| 45 |
One may give several small fonts, all containing |
| 46 |
a Unicode table, and |
| 47 |
.B setfont |
| 48 |
will combine them and load the union. |
| 49 |
Typical use: |
| 50 |
.TP |
| 51 |
.B setfont |
| 52 |
Load a default font. |
| 53 |
.TP |
| 54 |
.B "setfont drdos8x16" |
| 55 |
Load a given font (here the 448-glyph drdos font). |
| 56 |
.TP |
| 57 |
.B "setfont cybercafe -u cybercafe" |
| 58 |
Load a given font that does not have a Unicode map |
| 59 |
and provide one explicitly. |
| 60 |
.TP |
| 61 |
.B "setfont LatArCyrHeb-19 -m 8859-2" |
| 62 |
Load a given font (here a 512-glyph font combining several |
| 63 |
character sets) and indicate that one's local character set |
| 64 |
is ISO 8859-2. |
| 65 |
.LP |
| 66 |
Note: if a font has more than 256 glyphs, only 8 out of 16 colors |
| 67 |
can be used simultaneously. It can make console perception worse |
| 68 |
(loss of intensity and even some colors). |
| 69 |
|
| 70 |
.SH "FONT FORMATS" |
| 71 |
The standard Linux font format is the PSF font. |
| 72 |
It has a header describing font properties like character size, |
| 73 |
followed by the glyph bitmaps, optionally followed by a Unicode mapping |
| 74 |
table giving the Unicode value for each glyph. |
| 75 |
Several other (obsolete) font formats are recognized. |
| 76 |
If the input file has code page format (probably with suffix .cp), |
| 77 |
containing three fonts with sizes e.g. 8x8, 8x14 and 8x16, then one of |
| 78 |
the options \-8 or \-14 or \-16 must be used to select one. |
| 79 |
Raw font files are binary files of size |
| 80 |
.RI 256* N |
| 81 |
bytes, containing bit images for each of 256 characters, |
| 82 |
one byte per scan line, and |
| 83 |
.I N |
| 84 |
bytes per character (0 < |
| 85 |
.I N |
| 86 |
<= 32). |
| 87 |
Most fonts have a width of 8 bits, but with the framebuffer device (fb) |
| 88 |
other widths can be used. |
| 89 |
|
| 90 |
.SH "FONT HEIGHT" |
| 91 |
The program |
| 92 |
.B setfont |
| 93 |
has no built-in knowledge of VGA video modes, but just asks |
| 94 |
the kernel to load the character ROM of the video card with |
| 95 |
certain bitmaps. However, since Linux 1.3.1 the kernel knows |
| 96 |
enough about EGA/VGA video modes to select a different line |
| 97 |
distance. The default character height will be the number |
| 98 |
.I N |
| 99 |
inferred from the font or specified by option. However, the |
| 100 |
user can specify a different character height |
| 101 |
.I H |
| 102 |
using the |
| 103 |
.I "\-h" |
| 104 |
option. |
| 105 |
|
| 106 |
.SH "CONSOLE MAPS" |
| 107 |
Several mappings are involved in the path from user program |
| 108 |
output to console display. If the console is in utf8 mode (see |
| 109 |
.BR unicode_start (1)) |
| 110 |
then the kernel expects that user program output is coded as UTF-8 (see |
| 111 |
.BR utf-8 (7)), |
| 112 |
and converts that to Unicode (ucs2). |
| 113 |
Otherwise, a translation table is used from the 8-bit program output |
| 114 |
to 16-bit Unicode values. Such a translation table is called a |
| 115 |
.IR "Unicode console map" . |
| 116 |
There are four of them: three built into the kernel, the fourth |
| 117 |
settable using the |
| 118 |
.I "\-m" |
| 119 |
option of |
| 120 |
.BR setfont . |
| 121 |
An escape sequence chooses between these four tables; after loading a |
| 122 |
.IR cmap , |
| 123 |
.B setfont |
| 124 |
will output the escape sequence Esc ( K that makes it the active translation. |
| 125 |
.LP |
| 126 |
Suitable arguments for the |
| 127 |
.I "\-m" |
| 128 |
option are for example |
| 129 |
.IR 8859-1 , |
| 130 |
.IR 8859-2 ", ...," |
| 131 |
.IR 8859-15 , |
| 132 |
.IR cp437 ", ...," |
| 133 |
.IR cp1250 . |
| 134 |
.LP |
| 135 |
Given the Unicode value of the symbol to be displayed, the kernel |
| 136 |
finds the right glyph in the font using the Unicode mapping info |
| 137 |
of the font and displays it. |
| 138 |
.LP |
| 139 |
Old fonts do not have Unicode mapping info, and in order to handle |
| 140 |
them there are direct-to-font maps (also loaded using |
| 141 |
.IR "\-m" ) |
| 142 |
that give a correspondence between user bytes and font positions. |
| 143 |
The most common correspondence is the one given in the file |
| 144 |
.I trivial |
| 145 |
(where user byte values are used directly as font positions). |
| 146 |
Other correspondences are sometimes preferable since the |
| 147 |
PC video hardware expects line drawing characters in certain |
| 148 |
font positions. |
| 149 |
.LP |
| 150 |
Giving a |
| 151 |
.I "\-m none" |
| 152 |
argument inhibits the loading and activation of a mapping table. |
| 153 |
The previous console map can be saved to a file using the |
| 154 |
.I "\-om file" |
| 155 |
option. |
| 156 |
These options of setfont render |
| 157 |
.BR mapscrn (8) |
| 158 |
obsolete. (However, it may be useful to read that man page.) |
| 159 |
|
| 160 |
.SH "UNICODE FONT MAPS" |
| 161 |
The correspondence between the glyphs in the font and |
| 162 |
Unicode values is described by a Unicode mapping table. |
| 163 |
Many fonts have a Unicode mapping table included in |
| 164 |
the font file, and an explicit table can be indicated using |
| 165 |
the |
| 166 |
.I "\-u" |
| 167 |
option. The program |
| 168 |
.B setfont |
| 169 |
will load such a Unicode mapping table, unless a |
| 170 |
.I "\-u none" |
| 171 |
argument is given. The previous Unicode mapping table |
| 172 |
will be saved as part of the saved font file when the \-O |
| 173 |
option is used. It can be saved to a separate file using the |
| 174 |
.I "\-ou file" |
| 175 |
option. |
| 176 |
These options of setfont render |
| 177 |
.BR loadunimap (8) |
| 178 |
obsolete. |
| 179 |
.LP |
| 180 |
The Unicode mapping table should assign some glyph to |
| 181 |
the `missing character' value U+fffd, otherwise missing |
| 182 |
characters are not translated, giving a usually very confusing |
| 183 |
result. |
| 184 |
|
| 185 |
Usually no mapping table is needed, and a Unicode mapping table |
| 186 |
is already contained in the font (sometimes this is indicated |
| 187 |
by the .psfu extension), so that most users need not worry |
| 188 |
about the precise meaning and functioning of these mapping tables. |
| 189 |
|
| 190 |
One may add a Unicode mapping table to a psf font using |
| 191 |
.BR psfaddtable (1). |
| 192 |
|
| 193 |
.SH OPTIONS |
| 194 |
.TP |
| 195 |
\fB\-\fR\fI\,N\/\fR, \fB\-\-default8x\fR=\fI\,N\/\fR |
| 196 |
Load default font |
| 197 |
.RI (default8x N ). |
| 198 |
.TP |
| 199 |
\fB\-h\fR\fI\,N\/\fR, \fB\-\-font-height\fR=\fI\,N\/\fR |
| 200 |
Override font height. The short option must not have a space between the prefix |
| 201 |
and the number. |
| 202 |
.TP |
| 203 |
\fB\-d\fR, \fB\-\-double\fR |
| 204 |
Doubles the size of the font, by replicating all of its pixels |
| 205 |
vertically and horizontally. This is suitable for high pixel density |
| 206 |
(e.g. "4k") displays on which the standard fonts are too small to be |
| 207 |
easily legible. Due to kernel limitations, this is suitable only for |
| 208 |
16x16 or smaller fonts. |
| 209 |
.TP |
| 210 |
\fB\-o\fR, \fB\-\-output-font\fR=\fI\,FILE\/\fR |
| 211 |
Save previous font in |
| 212 |
.IR FILE . |
| 213 |
.TP |
| 214 |
\fB\-om\fR, \fB\-\-output-consolemap\fR=\fI\,FILE\/\fR |
| 215 |
Store console map in |
| 216 |
.IR FILE . |
| 217 |
.TP |
| 218 |
\fB\-ou\fR, \fB\-\-output-unicodemap\fR=\fI\,FILE\/\fR |
| 219 |
Save previous Unicode map in |
| 220 |
.IR FILE . |
| 221 |
.TP |
| 222 |
\fB\-O\fR, \fB\-\-output-fullfont\fR=\fI\,FILE\/\fR |
| 223 |
Save previous font and Unicode map in |
| 224 |
.IR FILE . |
| 225 |
.TP |
| 226 |
\fB\-m\fR, \fB\-\-consolemap\fR=\fI\,FILE\/\fR |
| 227 |
Load console map or Unicode console map from |
| 228 |
.IR FILE . |
| 229 |
.TP |
| 230 |
\fB\-u\fR, \fB\-\-unicodemap\fR=\fI\,FILE\/\fR |
| 231 |
Load Unicode table describing the font from |
| 232 |
.IR FILE . |
| 233 |
.TP |
| 234 |
\fB\-C\fR, \fB\-\-console\fR=\fI\,DEVICE\/\fR |
| 235 |
Set the font for the indicated console. (May require root permissions.) |
| 236 |
.TP |
| 237 |
\fB\-f\fR, \fB\-\-force\fR |
| 238 |
Force-load unicode map: Setfont`issues the system call to load the unicode |
| 239 |
map even if the specified map is empty. This may be useful in unusual cases. |
| 240 |
.TP |
| 241 |
\fB\-R\fR, \fB\-\-reset\fR |
| 242 |
Reset the screen font, size, and Unicode mapping to the bootup defaults. |
| 243 |
.TP |
| 244 |
\fB\-v\fR, \fB\-\-verbose\fR |
| 245 |
Be verbose. |
| 246 |
.TP |
| 247 |
\fB\-V\fR, \fB\-\-version\fR |
| 248 |
Print version and exit. |
| 249 |
.TP |
| 250 |
\fB\-h\fR, \fB\-\-help\fR |
| 251 |
Print a message describing the options and exit. |
| 252 |
|
| 253 |
.SH NOTE |
| 254 |
PC video hardware allows one to use the "intensity" bit |
| 255 |
either to indicate brightness, or to address 512 (instead of 256) |
| 256 |
glyphs in the font. So, if the font has more than 256 glyphs, |
| 257 |
the console will be reduced to 8 (instead of 16) colors. |
| 258 |
|
| 259 |
.SH FILES |
| 260 |
.TP |
| 261 |
.I /usr/share/consolefonts |
| 262 |
The default font directory. |
| 263 |
.LP |
| 264 |
.TP |
| 265 |
.I /usr/share/unimaps |
| 266 |
The default directory for Unicode maps. |
| 267 |
.LP |
| 268 |
.TP |
| 269 |
.I /usr/share/consoletrans |
| 270 |
The default directory for screen mappings. |
| 271 |
.LP |
| 272 |
The default font is a file |
| 273 |
.I default |
| 274 |
(or |
| 275 |
.IR default8x N |
| 276 |
if the \-N option was given for some number N) |
| 277 |
perhaps with suitable extension (like .psf). |
| 278 |
.SH "SEE ALSO" |
| 279 |
.BR psfaddtable (1), |
| 280 |
.BR unicode_start (1), |
| 281 |
.BR loadunimap (8), |
| 282 |
.BR utf-8 (7), |
| 283 |
.BR mapscrn (8) |
| 284 |
.\" .SH "AUTHORS" |
| 285 |
.\" Eugene G. Crosser ([email protected]) |
| 286 |
.\" .br |
| 287 |
.\" Andries E. Brouwer ([email protected]) |