U8LOC(1)

NAME
u8loc - run a program in a UTF-8-capable environment

SYNOPSIS
u8loc [-p] -r program [args...]
u8loc [-p] -q LC_ALL
u8loc [-p] -q LANGUAGE
u8loc -q preferred
u8loc -q list
u8loc - -features

DESCRIPTION
The u8loc utility prepares the environment variables so that a child process being run will hopefully generate clean UTF-8 output. It is designed to be run by a program that expects to be able to reliably parse the output of another program without worrying about character set conversions.

The u8loc utility invokes the locale(1) tool to list the names of the locales for which the current system has valid definitions, and then filters and reorders those names based on either a predefined list of language preferences or, if the -p option is specified, on the language names found in the current environment's locale-related variables (LC_ALL, LANG, LC_MESSAGES, LC_CTYPE, etc.).

The u8loc utility accepts the following command-line options:

-p  Examine the current environment's locale-related variables and use the names of languages found there as a preference list for choosing a suitable locale.

-q  Do not execute a program; output the detected environment settings instead, depending on the supplied argument:

    LC_ALL
        Output the selected UTF-8-capable locale name that would be placed into the LC_ALL environment variable.

    LANGUAGE
        Output the empty string that would be placed into the LANGUAGE environment variable.

    list
        List the available parameters for the -q option.

    preferred
        Output the list of languages gathered from examining the locale-related environment variables.

-r  Set the LC_ALL and LANGUAGE variables in the environment and execute the specified program.

ENVIRONMENT
If the -p option is specified, the locale-related environment variables are examined in order. If any of them contains the name of a locale that specifies UTF-8 as encoding (by either a “UTF-8 or “utf8 suffix””), the language name is added to the list of preferences. The variables examined are:

* LC_ALL

* LANG

* LC_MESSAGES

* LC_COLLATE

* LC_NAME

* LC_IDENTIFICATION

* LC_CTYPE

* LC_NUMERIC

* LC_TIME

* LC_MONETARY

* LC_PAPER

* LC_ADDRESS

* LC_TELEPHONE

* LC_MEASUREMENT

EXIT STATUS
If an error occurs during the detection of a suitable UTF-8-capable locale, the u8loc utility will exit with a non-zero error code. If the -r option is specified, the specified program will be executed and replace the u8loc process.

EXAMPLES
Output the name of a UTF-8-capable locale:

    u8loc -q LC_ALL

Run a program in a UTF-8-friendly environment:

    u8loc -r -- cal -3

STANDARDS
No standards documentation was harmed in the process of creating u8loc.

BUGS
Please report any bugs in u8loc to the author.

AUTHOR
The u8loc utility was written by Peter Pentchev <roam@ringlet.net>.