Apache C++ Standard Library Reference Guide

## localedef utility

    Utility Program

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

### Local Index

#### Members

RWSTD_SRC_ROOT |

### Summary

A utility program to define a localization environment.

### Synopsis

    localedef [-c][-f charmap][-i sourcefile][-u code_set_name]         name

Extensions of this implementation:

    localedef [-w][-wN][-f charmap][-i sourcefile][--help][--ucs]         name
    localedef -g [-m locale_list][-r charmap_dir][-s source_dir]         [-d output_dir]

### Description

The `localedef` utility reads one or more locale definition files and character set description files and translates them into binary files suitable for interpretation by this implementation of the C++ Standard Library. The binary files produced by `localedef` are referred to in this document as locale databases. In particular, the localization library makes use of this information to implement its behavior. The behavior of the utility is affected by the environment variable `${RWSTD_SRC_ROOT}`.

### Options

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

#### Table 25: localedef option requirements of the IEEE Std. 1003.1-2001 (POSIX) standard

Option | Meaning
`-c` | Create output regardless of warnings.
`-f` `charmap` | Use `charmap` as the pathname of the character set description file.
`-i` `sourcefile` | Use `sourcefile` as the pathname of the locale description file. If this option is not specified, `localdef` reads the locale definition from its standard input.
`-u` `code_set_name` | Use `code_set_name` as the target mapping for character symbols and collating element symbols whose encoding values are defined in terms of the ISO/IEC 10646-1:2000 standard position constant values.

Table 26 illustrates options that are provided as extensions to the IEEE Std 1003.1-2001 (POSIX) standard.

#### Table 26: localedef option extensions to the IEEE Std 1003.1-2001 (POSIX) standard

Option | Meaning
`-w` | Disable all warnings.
`-w` `N` | Disable warning number `N`, where `N` is a non-negative integer. The option can be repeated any number of times to disable multiple warnings.
`-g` | Enter `batch mode`.
-m `locale_list` | Use `locale_list` as the name of a file containing a list associating locale names with the names of encodings. This option is only allowed in batch mode.
`-r` `charmap_dir` | Use `charmap_dir` as the name of the directory under which `localedef` should look for character set description files. This option is only allowed in batch mode.
`-r` `source_dir` | Use `source_dir` as the name of the directory under which `localedef` should look for locale definition files. This option is only allowed in batch mode.
`-d output_dir` | Use `output_dir` as the name of the directory under which `localedef` should place binary files produced in batch mode.
`--ucs` | Use the Universal Character Set (either UCS-4 or UCS-2) to encode characters of type `wchar_t`. This option may require character set description files in an extended format.
`--help` | Print a usage message to `stdout` and exit with `0` exit status.

### Operands

The following operands are accepted:

    name

The name of a locale database to produce. If name contains at least one slash character it is considered to be a pathname, and will be created under the directory tree specified. Otherwise, name is considered to be a filename and will be created in the current working directory.

### Environment Variables

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

### Input

Unless the `-i` option is used, `localedef` reads the locale definition from `stdin`. Otherwise, `localedef` reads the locale definition from the filename specified with the `-i` option. The utility also attempts to read files named by any copy directives that appear in the locale definition. `localedef` reads character set descriptions from the files specified with the `-f` option.

The required format of the character set description file follows that described in section 6.4, Character Set Description File, of IEEE Std 1003.1-2001.

The required format of the locale definition file follows that described in section 7.3, Locale Definition, of IEEE Std 1003.1-2001.

Any files that conform to the required format can be used with `localedef` to produce binary locale database files suitable for use with the Apache C++ Standard Library.

A limited number of character set description files and locale definition files in the conforming format can be purchased from The Open Group. See `http://www.opengroup.org/pubs/catalog/lo.htm`.

Character set description files and locale definition files in an extended format can be obtained without charge from the JTC1/SC22/WG15 -- POSIX pages at `ftp://dkuug.dk/i18n/WG15-collection/`. These files are distributed with the Apache C++ Standard Library sources.

Additionally, the `localedef` utility also accepts files in an extended format used by GNU C library, glibc 2
`(http://www.gnu.org/software/libc/libc.html)`. The locale definition files that accompany glibc 2.2.5 are distributed with the Apache C++ Standard Library sources.

Finally, `localedef` utility accepts files shipped with HP-UX 11.00 and later. The character set description files are installed in
`/usr/lib/nls/loc/charmaps`, the locale definition files are in
`/usr/lib/nls/loc/src`. These files are not distributed with the Apache C++ Standard Library sources.

### Output

On success, `localedef` will create one or more files. If the `name` argument does not contain the slash character, files are created in the current working directory. Otherwise, the output files will be created in the directory specified by `name`. The following directory tree describes the organization of the output files:

    encoding
    name/
    name/LC_COLLATE
    name/LC_CTYPE
    name/LC_MONETARY
    name/LC_NUMERIC
    name/LC_TIME
    name/LC_MESSAGES

The name of the `encoding` file reflects the used character set definition as specified by the `-f` option. The name of the directory name corresponds to the name argument passed to `localedef`. Under the directory, `localedef` creates up to six files named `LC_COLLATE`, `LC_CTYPE`, etc., one for each section that appears in the locale definition.

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

### Exit Status

The `localedef` utility exits with the status codes listed in Table 27:

#### Table 27: localedef exit status

Exit Status | Meaning
`0` | No errors occurred and locale databases were successfully created.
`1` | Warnings occurred and locale databases were successfully created.
`2` | The locale specification exceeded implementation limits or the coded character set or sets used are not supported, and no locale databases were created.
`> 3` | Warnings or errors occurred and no locale databases were created.

### Examples

Please note that the examples in this section use extensions of this implementation to the `localedef` utility.

The following command tries to create a locale database called `german` for the German locale `de_DE` using the ISO 8859-1 character set, and the locale definition file `de_DE`:

    $ localedef -f nls/charmaps/ISO-8859-1 \
        -i nls/src/de_DE german

Warnings normally prevent the successful creation of the output binary file. Since not all of the provided files are entirely clean of warnings, the following command forces `localedef` to produce output even in the presence of warnings. This command creates a locale database called `french@euro` for the French locale using the ISO 8859-15 character set, and the locale definition file `fr_FR.euro`:

    $ localedef -c -f nls/charmaps/ISO-8859-15 \
        -i nls/src/fr_FR.euro french@euro

This command may still produce a number of warnings, but assuming there are no errors, `localedef` will create a valid binary locale database. The command below makes use of the `-w` option to indiscriminately silence all warning messages. It creates a locale database called `ja.euc` in the `/tmp` directory from the Japanese locale definition file `ja_JP` using the `EUC-JP` encoding:

    $ localedef -c -w -f nls/charmaps/EUC-JP \
       -i nls/src/ja_JP /tmp/ja.euc

### See Also

locale utility, class locale

### Standards Conformance

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