LUIT(1) X Window System LUIT(1)

# [NAME](#NAME)

luit - Locale and ISO 2022 support for Unicode terminals

# [SYNOPSIS](#SYNOPSIS)

**luit** \[ *options* ] \[ **--** ] \[ *program* \[ *args* ] ]

# [DESCRIPTION](#DESCRIPTION)

**Luit** is a filter that can be run between an arbitrary application and a UTF-8 terminal emulator. It will convert application output from the locale's encoding into UTF-8, and convert terminal input from UTF-8 into the locale's encoding.

**Luit** reads its input from the child process, i.e., an application running in the terminal. **Luit** writes its output to the terminal. The two (input and output) can have different encodings.

An application may also request switching to a different output encoding using ISO 2022 and ISO 6429 escape sequences. Use of this feature is discouraged: multilingual applications should be modified to directly generate UTF-8 instead.

**Luit** is usually invoked transparently by the terminal emulator. For information about running **luit** from the command line, see EXAMPLES below.

# [OPTIONS](#OPTIONS)

[**-V**](#V)

Print **luit**'s version and quit.

[**-alias filename**](#alias)

the locale alias file  
(default: /usr/share/X11/locale/locale.alias).

[**-argv0 name**](#argv0)

Set the child's name (as passed in argv\[0]).

[**-c**](#c)

Function as a simple converter from standard input to standard output.

[**-encoding encoding**](#encoding)

Set up **luit** to use *encoding* rather than the current locale's encoding.

[**-g0 charset**](#g0)

Set the output charset initially selected in G0. The default depends on the locale, but is usually **ASCII**.

[**-g1 charset**](#g1)

Set the output charset initially selected in G1. The default depends on the locale.

[**-g2 charset**](#g2)

Set the output charset initially selected in G2. The default depends on the locale.

[**-g3 charset**](#g3)

Set the output charset initially selected in G3. The default depends on the locale.

[**-gl gn**](#gl)

Set the initial assignment of GL in the output. The argument should be one of **g0**, **g1**, **g2** or **g3**. The default depends on the locale, but is usually **g0**.

[**-gr gk**](#gr)

Set the initial assignment of GR in the output. The default depends on the locale, and is usually **g2** except for EUC locales, where it is **g1**.

[**-h**](#h)

Display a usage and options message on the standard output and quit.

[**-ilog filename**](#ilog)

Log into *filename* all the bytes received from the child.

[**-k7**](#k7)

Generate seven-bit characters for keyboard input.

[**-kg0 charset**](#kg0)

Set the input charset initially selected in G0. The default depends on the locale, but is usually **ASCII**.

[**-kg1 charset**](#kg1)

Set the input charset initially selected in G1. The default depends on the locale.

[**-kg2 charset**](#kg2)

Set the input charset initially selected in G2. The default depends on the locale.

[**-kg3 charset**](#kg3)

Set the input charset initially selected in G3. The default depends on the locale.

[**-kgl gn**](#kgl)

Set the initial assignment of GL in the input. The argument should be one of **g0**, **g1**, **g2** or **g3**. The default depends on the locale, but is usually **g0**.

[**-kgr gk**](#kgr)

Set the initial assignment of GR in the input. The default depends on the locale, and is usually **g2** except for EUC locales, where it is **g1**.

[**-kls**](#kls)

Generate locking shifts (SO/SI) for keyboard input.

**+kss**

Disable generation of single-shifts for keyboard input.

**+kssgr**

Use GL codes after a single shift for keyboard input. By default, GR codes are generated after a single shift when generating eight-bit keyboard input.

[**-list**](#list)

List the supported charsets and encodings, then quit. **Luit** uses its internal tables for this, which are based on the *fontenc* library.

**-list-builtin**

List the built-in encodings used as a fallback when data from *iconv* or *fontenc* is missing.

This option relies on **luit** being configured to use *iconv*, since the *fontenc* library does not supply a list of built-in encodings.

**-list-fontenc**

List the encodings provided by “.enc” files originally distributed with the *fontenc* library.

**-list-iconv**

List the encodings and locales supported by the *iconv* library. **Luit** adapts its internal tables of *fontenc* names to *iconv* encodings.

To make scripting simpler, **luit** ignores spaces, underscores and ASCII minus-signs (dash) embedded in the names. **Luit** also ignores case when matching charset and encoding names.

This option lists only the encodings which are associated with the locales supported on the current operating system. The portable *iconv* application provides a list of its supported encodings with the **-l** option. Other implementations may provide similar functionality. There is no portable library call by which an application can obtain the same information.

[**-olog filename**](#olog)

Log into *filename* all the bytes sent to the terminal emulator.

**+ols**

Disable interpretation of locking shifts in application output.

**+osl**

Disable interpretation of character set selection sequences in application output.

**+oss**

Disable interpretation of single shifts in application output.

**+ot**

Disable interpretation of all sequences and pass all sequences in application output to the terminal unchanged. This may lead to interesting results.

[**-p**](#p)

In startup, establish a handshake between parent and child processes. This is needed for some older systems, e.g., to successfully copy the terminal settings to the pseudo-terminal.

[**-prefer list**](#prefer)

Set the lookup-order preference for character set information. The parameter is a comma-separated list of keywords. The default order (listing all keywords) is

fontenc,builtin,iconv,posix

The default order uses **fontenc** first because this allows **luit** to start more rapidly (about 0.1 seconds) than using **iconv** for complex encodings such as eucJP. However, you may find that the iconv implementation is more accurate or complete. In that case, you can use the **-show-iconv** option to obtain a text file which can be used as an encoding with the **fontenc** configuration.

This option relies on **luit** being configured to use *iconv*, since the *fontenc* library does not provide this choice.

[**-show-builtin encoding**](#show)

Show a built-in encoding, e.g., from a “.enc” file using the “.enc” format.

This option relies on **luit** being configured to use *iconv*, since the *fontenc* library does not supply a list of built-in encodings.

[**-show-fontenc encoding**](#show~2)

Show a given encoding, e.g., from a “.enc” file using the “.enc” format. If **luit** is configured to use the *fontenc* library, it obtains the information using that library. Otherwise **luit** reads the file directly.

Some of *fontenc*'s encodings are built into the library. The *fontenc* library uses those in preference to an external file. Use the **-show-builtin** option to provide similar information when **luit** is configured to use *iconv*.

[**-show-iconv encoding**](#show~3)

Show a given encoding, using the “.enc” format. If **luit** is configured to use *iconv*, it obtains the information using that interface. If *iconv* cannot supply the information, **luit** may use a built-in table.

[**-t**](#t)

Initialize **luit** using the locale and command-line options, but do not open a pty connection. This option is used for testing **luit**'s configuration. It will exit with success if no errors were detected. Repeat the **-t** option to cause warning messages to be treated as errors.

[**-v**](#v)

Be verbose. Repeating the option, e.g., “**-v -v**” makes it more verbose. **Luit** does not use *getopt*, so “**-vv**” does not work.

[**-x**](#x)

Exit as soon as the child dies. This may cause **luit** to lose data at the end of the child's output.

**--**

End of options.

# [ENVIRONMENT](#ENVIRONMENT)

**Luit** uses these environment variables:

[FONT\_ENCODINGS\_DIRECTORY](#FONT_ENCODINGS_DIRECTORY)

overrides the location of the “encodings.dir” file, which lists encodings in external “.enc” files.

[LC\_ALL](#LC_ALL)

[LC\_CTYPE](#LC_CTYPE)

[LANG](#LANG)

During initialization, **luit** calls **setlocale** to check if the user's locale is supported by the operating system. If **setlocale** returns a failure, **luit** looks instead at these variables in succession to obtain any clues from the user's environment for locale preference.

[NCURSES\_NO\_UTF8\_ACS](#NCURSES_NO_UTF8_ACS)

**Luit** sets this to tell ncurses to not rely upon VT100 SI/SO controls for line-drawing.

[SHELL](#SHELL)

This is normally set by shells other than the Bourne shell, as a convention. **Luit** will use this value (rather than the user's entry in /etc/passwd) to decide which shell to execute. If SHELL is not set, **luit** executes /bin/sh.

# [FILES](#FILES)

**/usr/share/X11/locale/locale.alias**

The file mapping locales to locale encodings.

# [BUGS](#BUGS)

## [Limitations](#Limitations)

None of this complexity should be necessary. Stateless UTF-8 throughout the system is the way to go.

Charsets with a non-trivial intermediary byte are not yet supported.

Selecting alternate sets of control characters is not supported and will never be.

## [Security](#Security)

On systems with SVR4 (“Unix-98”) ptys (Linux version 2.2 and later, SVR4), **luit** should be run as the invoking user.

On systems without SVR4 (“Unix-98”) ptys (notably BSD variants), running **luit** as an ordinary user will leave the tty world-writable; this is a security hole, and **luit** will generate a warning (but still accept to run). A possible solution is to make **luit** suid root; **luit** should drop privileges sufficiently early to make this safe. However, the startup code has not been exhaustively audited, and the author takes no responsibility for any resulting security issues.

**Luit** will refuse to run if it is installed setuid and cannot safely drop privileges.

# [EXAMPLES](#EXAMPLES)

The most typical use of **luit** is to adapt an instance of **XTerm** to the locale's encoding. Current versions of **XTerm** invoke **luit** automatically when it is needed. If you are using an older release of **XTerm**, or a different terminal emulator, you may invoke **luit** manually:

$ xterm -u8 -e luit

If you are running in a UTF-8 locale but need to access a remote machine that doesn't support UTF-8, **luit** can adapt the remote output to your terminal:

$ LC\_ALL=fr\_FR luit ssh legacy-machine

**Luit** is also useful with applications that hard-wire an encoding that is different from the one normally used on the system or want to use legacy escape sequences for multilingual output. In particular, versions of **Emacs** that do not speak UTF-8 well can use **luit** for multilingual output:

$ luit -encoding 'ISO 8859-1' emacs -nw

And then, in **Emacs**,

M-x set-terminal-coding-system RET iso-2022-8bit-ss2 RET

# [AUTHORS](#AUTHORS)

Luit was written by Juliusz Chroboczek <jch@pps.jussieu.fr> for the XFree86 project.

Thomas E. Dickey has maintained **luit** for use by **xterm** since 2006.

# [SEE ALSO](#SEE_ALSO)

These are portable:

- [xterm(1)](/man/os/luit/xterm.1),
- [ncurses(3X)](/man/os/luit/ncurses.3X).

These are Linux-specific:

- [unicode(1)](/man/os/luit/unicode.1),
- [utf-8(1)](/man/os/luit/utf-8.1),
- [charsets(1)](/man/os/luit/charsets.1).

These are particularly useful:

- ```
  Character Code Structure and Extension Techniques (ISO 2022, ECMA-35)
  ```
- ```
  Control Functions for Coded Character Sets (ISO 6429, ECMA-48)
  ```
- ```
  https://czyborra.com/charsets/
  ```

2026-09-07 2.0

---

Document: luit(1) from luit 20260907-r0 (Chainguard OS)
Source: https://github.com/ThomasDickey/luit-snapshots