NAME

locale - get locale-specific information

 SYNOPSIS

locale [ -a| -m]

locale [-ck] name...

 DESCRIPTION

The locale utility writes information about the current locale environment, or all public locales, to the standard output. For the purposes of this section, a public locale is one provided by the implementation that is accessible to the application.

When locale is invoked without any arguments, it summarises the current locale environment for each locale category as determined by the settings of the environment variables defined in the XBD specification, Locale  .

When invoked with operands, it writes values that have been assigned to the keywords in the locale categories, as follows:

• Specifying a keyword name selects the named keyword and the category containing that keyword.

• Specifying a category name selects the named category and all keywords in that category.

 OPTIONS

The locale utility supports the XBD specification, Utility Syntax Guidelines  .

The following options are supported:

-a

Write information about all available public locales. The available locales include POSIX, representing the POSIX locale. The manner in which the implementation determines what other locales are available is implementation-dependent.

-c

Write the names of selected locale categories; see the STDOUT section. The -c option increases readability when more than one category is selected (for example, via more than one keyword name or via a category name). It is valid both with and without the -k option.

-k

Write the names and values of selected keywords. The implementation may omit values for some keywords; see the OPERANDS section.

-m

Write names of available charmaps; see the XBD specification, Portable Character Set  .

 OPERANDS

The following operand is supported:

name

The name of a locale category as defined in the XBD specification, Locale  , the name of a keyword in a locale category, or the reserved name charmap. The named category or keyword will be selected for output. If a single name represents both a locale category name and a keyword name in the current locale, the results are unspecified. Otherwise, both category and keyword names can be specified as name operands, in any sequence. It is implementation-dependent whether any keyword values are written for the categories LC_CTYPE and LC_COLLATE.

 STDIN

Not used.

 INPUT FILES

None.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of locale:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalisation variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files).

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogues for the processing of LC_MESSAGES .

The LANG , LC_* and NLSPATH environment variables must specify the current locale environment to be written out; they will be used if the -a option is not specified.

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

If locale is invoked without any options or operands, the names and values of the LANG and LC_* environment variables described in this specification will be written to the standard output, one variable per line, with LANG first, and each line using the following format. Only those variables set in the environment and not overridden by LC_ALL will be written using this format:

"%s=%s\n", <variable_name>, <value>

The names of those LC_* variables associated with locale categories defined in this specification that are not set in the environment or are overridden by LC_ALL will be written in the following format:

"%s=\"%s\"\n", <variable_name>, <implied value>

The <implied value> is the name of the locale that has been selected for that category by the implementation, based on the values in LANG and LC_ALL , as described in the XBD specification, Environment Variables  .

The <value> and <implied value> shown above will be properly quoted for possible later reentry to the shell. The <value> will not be quoted using double-quotes (so that it can be distinguished by the user from the <implied value> case, which always requires double-quotes).

The LC_ALL variable will be written last, using the first format shown above. If it is not set, it will be written as:

"LC_ALL=\n"

If any arguments are specified:

1. If the -a option is specified, the names of all the public locales will be written, each in the following format:

   "%s\n", <locale name>

2. If the -c option is specified, the names of all selected categories will be written, each in the following format:

   "%s\n", <category name>

   If keywords are also selected for writing (see following items), the category name output will precede the keyword output for that category.

   If the -c option is not specified, the names of the categories will not be written; only the keywords, as selected by the name operand, will be written.

3. If the -k option is specified, the names and values of selected keywords will be written. If a value is non-numeric, it will be written in the following format:

   "%s=\"%s\"\n", <keyword name>, <keyword value>

   If the keyword was charmap, the name of the charmap (if any) that was specified via the localedef -f option when the locale was created will be written, with the word charmap as <keyword name>.

   If a value is numeric, it will be written in one of the following formats:

   "%s=%d\n", <keyword name>, <keyword value>

   "%s=%c%o\n", <keyword name>,
   <escape character>,
   <keyword value>
   

   "%s=%cx%x\n", <keyword name>,
   <escape character>,
   <keyword value>
   

   where the <escape character> is that identified by the escape_char keyword in the current locale; see the XBD specification, Locale Definitions  .

   Compound keyword values (list entries) will be separated in the output by semicolons. When included in keyword values, the semicolon, the double-quote, the backslash and any control character will be preceded (escaped) with the escape character.

4. If the -k option is not specified, selected keyword values will be written, each in the following format:

   "%s\n", <keyword value>

   If the keyword was charmap, the name of the charmap (if any) that was specified via the localedef -f option when the locale was created will be written.

5. If the -m option is specified, then a list of all available charmaps will be written, each in the format:

   "%s\n", <charmap>
   

   where <charmap> is in a format suitable for use as the option-argument to the localedef -f option.

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

None.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:

0

All the requested information was found and output successfully.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

If the LANG environment variable is not set or set to an empty value, or one of the LC_* environment variables is set to an unrecognised value, the actual locales assumed (if any) are implementation-dependent as described in the XBD specification, Environment Variables  .

Implementations are not required to write out the actual values for keywords in the categories LC_CTYPE and LC_COLLATE; however, they must write out the categories (allowing an application to determine, for example, which character classes are available).

 EXAMPLES

In the following examples, the assumption is that locale environment variables are set as follows:

LANG=locale_x
LC_COLLATE=locale_y

The command:

locale

would result in the following output:

LANG=locale_x
LC_CTYPE="locale_x"
LC_COLLATE=locale_y
LC_TIME="locale_x"
LC_NUMERIC="locale_x"
LC_MONETARY="locale_x"
LC_MESSAGES="locale_x"
LC_ALL=

The order of presentation of the categories is not specified by this specification.

The command:

LC_ALL=POSIX locale -ck decimal_point

would produce:

LC_NUMERIC
decimal_point="."

The following command shows an application of locale to determine whether a user-supplied response is affirmative:

if printf "%s\n" "$response" | grep -Eq "$(locale yesexpr)"
then
    affirmative processing goes here
else
    non-affirmative processing goes here
fi

 FUTURE DIRECTIONS

The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about parts of this interface definition to the IEEE PASC Shell and Utilities Working Group which is identifying the corrections. A future revision of this specification will align with IEEE Std. 1003.2b when finalised.

 SEE ALSO

localedef, the XBD specification, Locale Definitions  .