Apache C++ Standard Library Reference Guide

## locale utility

    Utility Program

- Local Index
- Summary
- Synopsis
- Description
- Options
- Operands
- Environment Variables
- Input
- Output
- Exit Status
- Examples
- See also
- Standard Conformance

### Local Index

#### Members

LANG LC_ALL LC_COLLATE | LC_CTYPE LC_MESSAGES LC_MONETARY | LC_NUMERIC LC_TIME RWSTD_LOCALE_ROOT | RWSTD_SRC_ROOT

### Summary

A utility program to read locale databases produced by `localedef`.

### Synopsis

    locale [-a|-m]
    locale [-c][-k] name...

Extensions of this implementation:

    locale [-c][-h][-k][-l][-w][-wN][--help] name...

### Description

The `locale` utility reads a locale database produced by the `localedef` utility and writes out information about the current locale environment or about all public locales to `stdout`. The current locale environment is determined by the setting of environment variables `LANG`, `LC_ALL`, `LC_COLLATE`, `LC_CTYPE`, `LC_NUMERIC`, `LC_MONETARY`, `LC_TIME`, and `LC_MESSAGES`. When invoked without operands, `locale` writes out the setting of locale environment variables. When invoked with arguments, it writes out values assigned to the keywords in locale categories. The behavior of the utility is affected by the environment variables `${RWSTD_LOCALE_ROOT}` and `${RWSTD_SRC_ROOT}`.

### Options

Table 22 lists the options that conform to the requirements of the IEEE Std. 1003.1-2001 (POSIX) standard.

#### Table 22: locale utility option requirements of the IEEE Std. 1003.1-2001 (POSIX) standard

Option | Meaning
`-a` | Write out information about all public locales, including the C and POSIX locales.
`-c` | Write out the names of specified locale categories. The option improves readability when more than one locale category is specified.
`-k` | Write out the values of the specified keywords.
`-m` | Write out the names of available charmaps.

Table 23 lists the options provided as extensions to the IEEE Std. 1003.1-2001 (POSIX) standard.

#### Table 23: locale utility option requirements of the IEEE Std. 1003.1-2001 (POSIX) standard

Option | Meaning
`-w` | Disable all warnings.
`-w` `N` | Disable warning number `N`. The option can be repeated any number of times to disable multiple warnings.
`--help` | Print a usage message to `stdout` and exit with `0` exit status.
`-h` | Use the character set description file associated with the locale database to write out symbolic character names rather than the character values.

### Operands

The following operands are accepted:

    name

The name of a locale category, or the reserved keyword `charmap`. The set of recognized locale categories is `LC_COLLATE`, `LC_CTYPE`, `LC_MONETARY`, `LC_NUMERIC`, `LC_TIME`, and `LC_MESSAGES`.

### Environment Variables

    LANG

Specifies the default value to be used for all unset or empty locale environment variables.

    LC_ALL

When set, overrides the settings of all locale environment variables.

    LC_COLLATE

Specifies the name of the locale to be used for the `LC_COLLATE` locale category. When the name contains the slash character, it is taken as the pathname of the locale database to be used for that category.

    LC_CTYPE

Specifies the name of the locale to be used for the `LC_CTYPE` locale category. When the name contains the slash character, it is taken as the pathname of the locale database to be used for that category.

    LC_MESSAGES

Specifies the name of the locale to be used for the `LC_MESSAGES` locale category. When the name contains the slash character, it is taken as the pathname of the locale database to be used for that category.

    LC_MONETARY

Specifies the name of the locale to be used for the `LC_MONETARY` locale category. When the name contains the slash character, it is taken as the pathname of the locale database to be used for that category.

    LC_NUMERIC

Specifies the name of the locale to be used for the `LC_NUMERIC` locale category. When the name contains the slash character, it is taken as the pathname of the locale database to be used for that category.

    LC_TIME

Specifies the name of the locale to be used for the `LC_TIME` locale category. When the name contains the slash character, it is taken as the pathname of the locale database to be used for that category.

    RWSTD_LOCALE_ROOT

The pathname of the root of the directory tree containing locale databases produced by `localedef`. The value of this environment variable is used when the `-m` option is specified, or unless the locale environment variables contain the slash character.

    RWSTD_SRC_ROOT

The pathname of the root of the directory tree containing character set description files and locale definition files. The character set description files are assumed to reside in `${RWSTD_SRC_ROOT}/charmaps`, the locale definition files in `${RWSTD_SRC_ROOT}/src`. The value of this environment variable is used when the `-h` option is specified.

### Input

`locale` reads one or more locale database files according to the settings of locale environment variables.

### Output

On success, and unless extended options are specified, the format of output produced by `locale` to `stdout` follows the requirements of IEEE Std 1003.1-2001 on the `locale` utility.

When invoked without any operands, `locale` writes to `stdout` the settings of all locale environment variables, starting with `LANG` first. Values of variables overridden by `LANG` are quoted in double-quotes.

When invoked with the `-a` option, `locale` writes to `stdout` the names of all public locales found in the directory specified by the `${RWSTD_LOCALE_ROOT}` variable, or the current working directory if the variable is unset or empty.

When invoked with the `-c` option, `locale` writes to `stdout` the name of each specified locale category; otherwise the names of categories are omitted. Refer to the Environment Variables section of this entry for a list of recognized locale categories.

When invoked with the `-k` option, `locale` writes to `stdout` the names and values of the specified keywords; otherwise only the values of the specified keywords are written.

When invoked with the `-m` option, `locale` writes to `stdout` the names of all available charmaps.

Any warning or error diagnostic messages produced by `localedef` are sent to `stderr`.

### Exit Status

Table 24 illustrates the `locale` utility exits with the corresponding status.

#### Table 24: locale utility exit status

Exit Status | Meaning
`0` | No errors occurred and output was successfully produced.
`> 0` | An error occurred that prevented locale from successfully producing output.

### Examples

The first of the following two commands, `localedef`, will create a locale database named `french@euro` in the directory `/tmp`. The second, `locale`, will write to `stdout` the names and values of the keywords for the `LC_TIME` locale category for the just created locale database. Since `-c` is specified, `locale` also writes out the name of the category. Please note that the following example uses extensions of this implementation to the `locale` utility.

    $ localedef -c -f -w nls/charmaps/ISO-8859-15 \
       -i nls/src fr_FR.euro/tmp/french@euro
    $ LC_TIME=/tmp/french@euro locale -ck LC_TIME
    LC_TIME
    abday="dim";"lun";"mar";"mer";"jeu";"ven";"sam"
    day="dimanche";"lundi";"mardi";"mercredi";"jeudi";"vendredi";
       "samedi"
    abmon="jan";"fév";"mar";"avr";"mai";"jun";"jui";"aoû";"sep";
       "oct";"nov";"déc"
    mon="janvier";"février";"mars";"avril";"mai";"juin";"juillet";
       "août";"septembre";"octobre";"novembre";"décembre"
    am_pm="";""
    d_t_fmt="%a %d %b %Y %T %Z"
    d_fmt="%d.%m.%Y"
    t_fmt="%T"
    t_fmt_ampm=""
    era=era_d_t_fmt=""
    era_d_fmt=""
    era_t_fmt=""
    alt_digits=""
    END LC_TIME

### See also

localedef utility

### Standard Conformance

IEEE Std. 1003.1-2001 -- The Open Group Base Specifications Issue 6