1LUIT(1)                     General Commands Manual                    LUIT(1)
2
3
4

NAME

6       luit - Locale and ISO 2022 support for Unicode terminals
7

SYNOPSIS

9       luit [ options ] [ -- ] [ program [ args ] ]
10

DESCRIPTION

12       Luit is a filter that can be run between an arbitrary application and a
13       UTF-8 terminal emulator.  It will convert application output  from  the
14       locale's  encoding  into  UTF-8,  and convert terminal input from UTF-8
15       into the locale's encoding.
16
17       Luit reads its input from the child process, i.e., an application  run‐
18       ning in the terminal.  Luit writes its output to the terminal.  The two
19       (input and output) can have different encodings.
20
21       An application may also request switching to a different output  encod‐
22       ing  using ISO 2022 and ISO 6429 escape sequences.  Use of this feature
23       is discouraged: multilingual applications should  be  modified  to  di‐
24       rectly generate UTF-8 instead.
25
26       Luit  is  usually  invoked transparently by the terminal emulator.  For
27       information about running luit from the command line, see EXAMPLES  be‐
28       low.
29

OPTIONS

31       -V     Print luit's version and quit.
32
33       -alias filename
34              the locale alias file
35              (default: unknown).
36
37       -argv0 name
38              Set the child's name (as passed in argv[0]).
39
40       -c     Function  as  a simple converter from standard input to standard
41              output.
42
43       -encoding encoding
44              Set up luit to use encoding rather than the current locale's en‐
45              coding.
46
47       -g0 charset
48              Set  the  output  charset initially selected in G0.  The default
49              depends on the locale, but is usually ASCII.
50
51       -g1 charset
52              Set the output charset initially selected in  G1.   The  default
53              depends on the locale.
54
55       -g2 charset
56              Set  the  output  charset initially selected in G2.  The default
57              depends on the locale.
58
59       -g3 charset
60              Set the output charset initially selected in  G3.   The  default
61              depends on the locale.
62
63       -gl gn Set  the  initial  assignment of GL in the output.  The argument
64              should be one of g0, g1, g2 or g3.  The default depends  on  the
65              locale, but is usually g0.
66
67       -gr gk Set the initial assignment of GR in the output.  The default de‐
68              pends on the locale, and is usually g2 except for  EUC  locales,
69              where it is g1.
70
71       -h     Display  a  usage and options message on the standard output and
72              quit.
73
74       -ilog filename
75              Log into filename all the bytes received from the child.
76
77       -k7    Generate seven-bit characters for keyboard input.
78
79       -kg0 charset
80              Set the input charset initially selected in G0.  The default de‐
81              pends on the locale, but is usually ASCII.
82
83       -kg1 charset
84              Set the input charset initially selected in G1.  The default de‐
85              pends on the locale.
86
87       -kg2 charset
88              Set the input charset initially selected in G2.  The default de‐
89              pends on the locale.
90
91       -kg3 charset
92              Set the input charset initially selected in G3.  The default de‐
93              pends on the locale.
94
95       -kgl gn
96              Set the initial assignment of GL in  the  input.   The  argument
97              should  be  one of g0, g1, g2 or g3.  The default depends on the
98              locale, but is usually g0.
99
100       -kgr gk
101              Set the initial assignment of GR in the input.  The default  de‐
102              pends  on  the locale, and is usually g2 except for EUC locales,
103              where it is g1.
104
105       -kls   Generate locking shifts (SO/SI) for keyboard input.
106
107       +kss   Disable generation of single-shifts for keyboard input.
108
109       +kssgr Use GL codes after a single shift for keyboard  input.   By  de‐
110              fault, GR codes are generated after a single shift when generat‐
111              ing eight-bit keyboard input.
112
113       -list  List the supported charsets and encodings, then quit.  Luit uses
114              its internal tables for this, which are based on the fontenc li‐
115              brary.
116
117       -list-builtin
118              List the built-in encodings used as a fallback  when  data  from
119              iconv or fontenc is missing.
120
121              This  option relies on luit being configured to use iconv, since
122              the fontenc library does not supply a list  of  built-in  encod‐
123              ings.
124
125       -list-fontenc
126              List  the encodings provided by “.enc” files originally distrib‐
127              uted with the fontenc library.
128
129       -list-iconv
130              List the encodings and locales supported by the  iconv  library.
131              Luit adapts its internal tables of fontenc names to iconv encod‐
132              ings.
133
134              To make scripting simpler, luit ignores spaces, underscores  and
135              ASCII  minus-signs  (dash) embedded in the names.  Luit also ig‐
136              nores case when matching charset and encoding names.
137
138              This option lists only the encodings which are  associated  with
139              the locales supported on the current operating system.  The por‐
140              table iconv application provides a list of its supported  encod‐
141              ings with the -l option.  Other implementations may provide sim‐
142              ilar functionality.  There is no portable library call by  which
143              an application can obtain the same information.
144
145       -olog filename
146              Log into filename all the bytes sent to the terminal emulator.
147
148       +ols   Disable interpretation of locking shifts in application output.
149
150       +osl   Disable  interpretation  of character set selection sequences in
151              application output.
152
153       +oss   Disable interpretation of single shifts in application output.
154
155       +ot    Disable interpretation of all sequences and pass  all  sequences
156              in  application output to the terminal unchanged.  This may lead
157              to interesting results.
158
159       -p     In startup, establish a handshake between parent and child  pro‐
160              cesses.   This  is  needed for some older systems, e.g., to suc‐
161              cessfully copy the terminal settings to the pseudo-terminal.
162
163       -prefer list
164              Set the lookup-order preference for character  set  information.
165              The  parameter  is  a comma-separated list of keywords.  The de‐
166              fault order (listing all keywords) is
167
168                     fontenc,builtin,iconv,posix
169
170              The default order uses fontenc first because this allows luit to
171              start more rapidly (about 0.1 seconds) than using iconv for com‐
172              plex encodings such as eucJP.  However, you may  find  that  the
173              iconv  implementation  is  more  accurate  or complete.  In that
174              case, you can use the -show-iconv option to obtain a  text  file
175              which can be used as an encoding with the fontenc configuration.
176
177              This  option relies on luit being configured to use iconv, since
178              the fontenc library does not provide this choice.
179
180       -show-builtin encoding
181              Show a built-in encoding, e.g., from a  “.enc”  file  using  the
182              “.enc” format.
183
184              This  option relies on luit being configured to use iconv, since
185              the fontenc library does not supply a list  of  built-in  encod‐
186              ings.
187
188       -show-fontenc encoding
189              Show a given encoding, e.g., from a “.enc” file using the “.enc”
190              format.  If luit is configured to use the  fontenc  library,  it
191              obtains  the  information  using  that  library.  Otherwise luit
192              reads the file directly.
193
194              Some of fontenc's encodings are built  into  the  library.   The
195              fontenc  library  uses  those in preference to an external file.
196              Use the -show-builtin option to provide similar information when
197              luit is configured to use iconv.
198
199       -show-iconv encoding
200              Show a given encoding, using the “.enc” format.  If luit is con‐
201              figured to use iconv, it obtains the information using that  in‐
202              terface.  If iconv cannot supply the information, luit may use a
203              built-in table.
204
205       -t     Initialize luit using the locale and command-line  options,  but
206              do  not  open a pty connection.  This option is used for testing
207              luit's configuration.  It will exit with success  if  no  errors
208              were  detected.   Repeat the -t option to cause warning messages
209              to be treated as errors.
210
211       -v     Be verbose.  Repeating the option, e.g., “-v -v” makes  it  more
212              verbose.  Luit does not use getopt, so “-vv” does not work.
213
214       -x     Exit  as  soon  as  the child dies.  This may cause luit to lose
215              data at the end of the child's output.
216
217       --     End of options.
218

ENVIRONMENT

220       Luit uses these environment variables:
221
222       FONT_ENCODINGS_DIRECTORY
223              overrides the location of the “encodings.dir” file, which  lists
224              encodings in external “.enc” files.
225
226       LC_ALL
227
228       LC_CTYPE
229
230       LANG   During  initialization,  luit  calls  setlocale  to check if the
231              user's locale is supported by the operating system.   If  setlo‐
232              cale returns a failure, luit looks instead at these variables in
233              succession to obtain any clues from the user's  environment  for
234              locale preference.
235
236       NCURSES_NO_UTF8_ACS
237              Luit sets this to tell ncurses to not rely upon VT100 SI/SO con‐
238              trols for line-drawing.
239
240       SHELL  This is normally set by shells other than the Bourne shell, as a
241              convention.   Luit  will  use this value (rather than the user's
242              entry in /etc/passwd) to decide  which  shell  to  execute.   If
243              SHELL is not set, luit executes /bin/sh.
244

EXAMPLES

246       The  most  typical  use of luit is to adapt an instance of XTerm to the
247       locale's encoding.  Current versions of XTerm invoke luit automatically
248       when  it  is  needed.  If you are using an older release of XTerm, or a
249       different terminal emulator, you may invoke luit manually:
250
251              $ xterm -u8 -e luit
252
253       If you are running in a UTF-8 locale but need to access  a  remote  ma‐
254       chine  that  doesn't support UTF-8, luit can adapt the remote output to
255       your terminal:
256
257              $ LC_ALL=fr_FR luit ssh legacy-machine
258
259       Luit is also useful with applications that hard-wire an  encoding  that
260       is  different  from  the one normally used on the system or want to use
261       legacy escape sequences for multilingual output.  In  particular,  ver‐
262       sions  of Emacs that do not speak UTF-8 well can use luit for multilin‐
263       gual output:
264
265              $ luit -encoding 'ISO 8859-1' emacs -nw
266
267       And then, in Emacs,
268
269              M-x set-terminal-coding-system RET iso-2022-8bit-ss2 RET
270

FILES

272       unknown
273              The file mapping locales to locale encodings.
274

SECURITY

276       On systems with SVR4 (“Unix-98”) ptys (Linux  version  2.2  and  later,
277       SVR4), luit should be run as the invoking user.
278
279       On  systems  without SVR4 (“Unix-98”) ptys (notably BSD variants), run‐
280       ning luit as an ordinary user will leave the tty  world-writable;  this
281       is  a security hole, and luit will generate a warning (but still accept
282       to run).  A possible solution is to make luit suid  root;  luit  should
283       drop  privileges  sufficiently  early  to make this safe.  However, the
284       startup code has not been exhaustively audited, and the author takes no
285       responsibility for any resulting security issues.
286
287       Luit  will  refuse  to  run if it is installed setuid and cannot safely
288       drop privileges.
289

BUGS

291       None of this complexity should be necessary.  Stateless UTF-8  through‐
292       out the system is the way to go.
293
294       Charsets with a non-trivial intermediary byte are not yet supported.
295
296       Selecting  alternate  sets  of  control characters is not supported and
297       will never be.
298

SEE ALSO

300       These are portable:
301
302xterm(1),
303
304       •   ncurses(3X).
305
306       These are Linux-specific:
307
308       •   unicode(1),
309
310       •   utf-8(1),
311
312       •   charsets(1).
313
314       These are particularly useful:
315
316Character Code Structure and Extension Techniques (ISO 2022, ECMA-35)
317
318Control Functions for Coded Character Sets (ISO 6429, ECMA-48)
319
320http://czyborra.com/charsets/
321

AUTHOR

323       Luit was written by Juliusz  Chroboczek  <jch@pps.jussieu.fr>  for  the
324       XFree86 project.
325
326       Thomas E. Dickey has maintained luit for use by xterm since 2006.
327
328
329
330                                X Window System                        LUIT(1)
Impressum