LOCALE(1) General Commands Manual LOCALE(1)

locale — get locale-specific information

locale [-a | -m]

locale [-ck] name ...

The locale utility shall write information about the current locale environment, or all public locales, to the standard output. For the purposes of this clause, a public locale is one provided by the implementation that is accessible to the application. When locale is invoked without any arguments, it shall summarize the current locale environment for each locale category as determined by the settings of the environment variables defined in 2.5. When invoked with operands, it shall write values that have been assigned to the keywords in the locale categories, as follows:

  • Specifying a keyword name shall select the named keyword and the category containing that keyword.
  • Specifying a category name shall select the named category and all keywords in that category.

The locale utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following options shall be supported by the implementation:

Write information about all available public locales. The available locales shall include POSIX, representing the POSIX Locale. The manner in which the implementation determines what other locales are available is implementation defined.

Write the names of selected locale categories; see STANDARD OUTPUT .

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

Write names of available charmaps; see 2.4.1.

The following operand shall be supported by the implementation:

name

The name of a locale category as defined in 2.5, the name of a keyword in a locale category, or the reserved name charmap. The named category or keyword shall 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 defined whether any keyword values are written for the categories LC_CTYPE and LC_COLLATE.

None.

None.

The following environment variables shall affect the execution of locale:

This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_ ) do not specify a locale. See 2.6.

This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.

This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments).

This variable shall determine the language in which messages should be written. The LANG and LC_ ∗ environment variables shall specify the current locale environment to be written out; they shall be used if the −a option is not specified.

Default.

If locale is invoked without any options or operands, the names and values of the LANG and LC_ ∗ environment variables described in this standard shall 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 shall be written using this format: "%s=%s\n", <variable_name>, <value> The names of those LC_ ∗ variables associated with locale categories defined in this standard that are not set in the environment or are overridden by LC_ALL shall be written in the following format: "%s=\"%s\"\n", <variable_name>, <implied value> The <implied value> shall be 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 2.6. The <value> and <implied value> shown above shall be properly quoted for possible later re-entry to the shell. The <value> shall not be quoted using doublequotes (so that it can be distinguished by the user from the <implied value> case, which always requires double-quotes).

The LC_ALL variable shall be written last, using the first format shown above. If it is not set, it shall 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 shall be written, each in the following format: "%s\n", < locale name>
  2. If the −c option is specified, the name(s) of all selected categories shall 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 shall precede the keyword output for that category. If the −c option is not specified, the names of the categories shall not be written; only the keywords, as selected by the name operand, shall be written.
  1. If the −k option is specified, the name(s) and value(s) of selected keywords shall be written. If a value is nonnumeric, it shall 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 shall be written, with the word charmap as <keyword name>. If a value is numeric, it shall 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 2.5.2. Compound keyword values (list entries) shall be separated in the output by semicolons. When included in keyword values, the semicolon, the double-quote, the backslash, and any control character shall be preceded (escaped) with the escape character.
  2. If the −k option is not specified, selected keyword values shall 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 shall be written.

  1. If the −m option is specified, then a list of all available charmaps shall 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.

Used only for diagnostic messages.

None.

None.

The locale utility shall exit with one of the following values:

All the requested information was found and output successfully.

An error occurred.

Default.

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 ="locale_x" LC_NUMERIC ="locale_x" ="locale_x" LC_MESSAGES ="locale_x" LC_ALL = The order of presentation of the categories is not specified by this standard. 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 nonaffirmative processing goes here fi 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 unrecognized value, the actual locales assumed (if any) are implementation defined as described in 2.6. 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, e.g., which character classes are available).

This command was added in Draft 9 to resolve objections to the lack of a way for applications to determine what locales are available, a way to examine the contents of existing public locales, a way to retrieve specific locale items, and a way to recognize affirmative and negative responses in an international environment. In Draft 10 it was cut back considerably in answer to balloting objections about its complexity and requirement of features not useful for application programs. The format for the no-arguments case was expanded to show the implied values of the categories as an aid to the novice user; the output was of little more value than that from env.

Based on the questionable value in a shell script of getting an entire array of characters back, and the problem of returning a collation description that makes sense, short of a complete localedef source, the output from requests for categories LC_CTYPE and LC_COLLATE has been made implementation defined. The −m option has been added to allow applications to query for the existence of charmaps. The output is a list of the charmaps (implementation-supplied and user-supplied, if any) on the system. The −c option was included for readability when more than one category is selected (e.g., via more than one keyword name or via a category name). It is valid both with and without the −k option.

The charmap keyword, which returns the name of the charmap (if any) that was used when the current locale was created, was introduced to allow applications needing the information to retrieve it.

September 1991 posix.fail