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

Debian                                          February 1, 2021                                        U8LOC(1)