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>.