LOCALEDEF(1) General Commands Manual LOCALEDEF(1)

localedef — define locale environment

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

The localedef utility shall convert source definitions for locale categories into a format usable by the functions and utilities whose operational behavior is determined by the setting of the locale environment variables defined in 2.5. It is implementation defined whether users shall have the capability to create new locales, in addition to those supplied by the implementation. If the symbolic constant is defined, then the system supports the creation of new locales. In a system not supporting this capability, the localedef utility shall terminate with an exit code of 3. The utility shall read source definitions for one or more locale categories belonging to the same locale from the file named in the −i option (if specified) or from standard input. The name operand identifies the target locale. The utility shall support the creation of public, or generally accessible locales, as well as private, or restrictedaccess locales. Implementations may restrict the capability to create or modify public locales to users with the appropriate privileges. Each category source definition shall be identified by the corresponding environment variable name and terminated by an category-name statement. The following categories shall be supported. In addition, the input may contain source for implementation-defined categories.

LC_CTYPE Defines character classification and case conversion. LC_COLLATE Defines collation rules. Defines the format and symbols used in formatting of monetary information. Defines the decimal delimiter, grouping, and grouping symbol for nonmonetary numeric editing. Defines the format and content of date and time information. LC_MESSAGES Defines the format and values of affirmative and negative responses.

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

Create permanent output even if warning messages have been issued.

charmap Specify the pathname of a file containing a mapping of character symbols and collating element symbols to actual character encodings. The format of the charmap is described under 2.4.1. This option shall be specified if symbolic names (other than collating symbols defined in a collating-symbol keyword) are used. If the −f option is not present, an implementation-defined default character mapping file shall be used.

inputfile

The pathname of a file containing the source definitions. If this option is not present, source definitions shall be read from standard input. The format of the inputfile is described in 2.5.2.

The following operand shall be supported by the implementation:

name

Identifies the locale. See 2.5 for a description of the use of this name. If the name contains one or more slash characters, name shall be interpreted as a pathname where the created locale definition(s) shall be stored. If name does not contain any slash characters, the interpretation of the name is implementation defined and the locale shall be public. This capability may be restricted to users with appropriate privileges.

Unless the −i option is specified, the standard input shall be a text file containing one or more locale category source definitions, as described in 2.5.2. When lines are continued using the escape character mechanism, there is no limit to the length of the accumulated continued line.

The character set mapping file specified as the charmap option-argument is described under 2.4.1. If a locale category source definition contains a copy statement, as defined in 2.5.2, and the copy statement names a valid, existing locale, then localedef shall behave as if the source definition had contained a valid category source definition for the named locale.

The following environment variables shall affect the execution of localedef:

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_. and LC_ ∗ variables as described in 2.6.

(This variable shall have no affect on localedef; the POSIX Locale shall be used for this category.)

This variable shall determine the locale for the interpretation of sequences of bytes of argument data as characters (e.g., single- versus multibyte characters). This variable shall have no affect on the processing of localedef input data; the POSIX Locale shall be used for this purpose, regardless of the value of this variable.

This variable shall determine the language in which messages should be written.

Default.

The utility shall report all categories successfully processed, in an unspecified format.

Used only for diagnostic messages.

The format of the created output is unspecified. If the name operand does not contain a slash, the existence of an output file for the locale is unspecified.

None.

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

No errors occurred and the locale(s) were successfully created.

Warnings occurred and the locale(s) were successfully created.

The locale specification exceeded implementation limits or the coded character set or sets used were not supported by the implementation, and no locale was created.

The capability to create new locales is not supported by the implementation.

Warnings or errors occurred and no output was created.

If an error is detected, no permanent output shall be created. If warnings occur, permanent output shall be created if the −c option was specified. The following conditions shall cause warning messages to be issued:

  • If a symbolic name not found in the charmap file is used for the descriptions of the LC_CTYPE or LC_COLLATE categories (for other categories, this shall be an error conditions).
  • If the number of operands to the order keyword exceeds the limit.
  • If optional keywords not supported by the implementation are present in the source.

Other implementation-defined conditions may also cause warnings.

Usage, Examples

The output produced by the localedef utility is implementation defined. The name operand is used to identify the specific locale. (As a consequence, although several categories can be processed in one execution, only categories belonging to the same locale can be processed.) The charmap definition is optional, and is contained outside the locale definition. This allows both completely ‘‘self-defined’’ source files, and ‘‘generic’’ sources (applicable to more than one code set). To aid portability, all charmap definitions shall use the same symbolic names for the portable character set. As explained in 2.4.1, it is implementation defined whether or not users or applications can provide additional character set description files. Therefore, the −f option might be operable only when an implementation-provided charmap is named.

This description is based on work performed in the UniForum Technical Committee Subcommittee on Internationalization. The localedef utility is provided as a standard, portable interface for implementations that allow users to create new locales, in addition to implementationsupplied ones. The ability to create new locales and categories, already available on many commercially available implementations of POSIX compliant systems, provides the means by which application providers can develop portable applications which use standard interfaces to adjust the behavior of the application to language and culture differences.

September 1991 posix.fail