localedef - define local environment

The localedef command converts source definitions for locales into a format that can be used by the functions and commands whose operational behavior is determined by the setting of the locale variables.

Every POSIX system user has the facility to create new locales locally. However, only a user with the appropriate privileges (usually system administrators) can install these locales on the system so that they can be used by functions, applications, and commands. This is done either by copying the files created locally to /usr/lib/locale/name and /usr/lib/charmap/charmap .

localedef reads source definitions for one or more of the categories in the locales, which belong to the same locale, from the file specified with the -i option (if specified), or from the standard input.

The name operand indicates the target environment. The command supports the creation of locales which are "public" (i.e. can be accessed generally), as well as locales which are private (i.e. with restricted access rights). On POSIX systems, only users with the appropriate privileges can create or alter general access locales.

Every category source definition is indicated by the name of the accompanying environment variable and is terminated with an END category-name instruction. The following categories are supported:

LC_CTYPE	Defines character classification and case conversion.
LC_COLLATE	Defines collation rules.
LC_MONETARY	Defines the format and symbols used for the formatting of monetary information.
LC_NUMERIC	Defines the decimal point, the thousands separator and radix character and the grouping symbol for the editing of non-monetary numeric information.
LC_TIME	Defines the format and contents of date and time specifications.
LC_MESSAGES	Defines the format and values of yes/no responses (affirmations and negations).

Syntax

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

Options

-c

Creates an output file, even if warning message is output.

-f charmap

Specifies the pathname of a file which contains an assignment of the symbolic character symbols and collating element symbols to the actual character coding (character map). This option must be specified if symbolic names are used that were not defined using the collating-symbol key word.

-f not specified:
The character assignment defined in the /usr/lib/charmap/posix file (ISO 8859-1) is used.

-i sourcefile

The pathname of a file which contains the source definitions.

-i not specified:
The source definitions of the default input are read.

name

Specifies the locale.

• If name contains one or more slashes, name is interpreted as a pathname, in which the definitions created for the locales are saved.

• If name does not contain a slash, the locale is private, and is generated in the current directory.

Because only one name can be specified, the only categories that can be processed in a call are those that belong to the same locale.

Locale

The following environment variables affect the execution of localedef:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization 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 internationalization variables.

LC_COLLATE

(This variable has no affect on localedef; the POSIX locale will be used for this category.)

LC_CTYPE

Determines the locale for the interpretation of sequences of bytes of text data as characters (e.g. single-byte as opposed to multibyte characters in arguments and input files). This variable has no affect on the processing of localedef input data; the POSIX locale is used for this purpose, regardless of the value of this variable.

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 catalogs for the processing of LC_MESSAGES.

File

Standard input

If the -i option is not specified, the standard input must be a text file containing one or more source definitions for categories for locales. If lines are continued using the escape mechanism, there is no length restriction for the entire input line

Input files

The file containing the description of a character set (charmap argument in -f). If a source definition of a category for an locale contains the copy instruction and this instruction specifies a valid locale, localedef behaves as if the source definition contained a valid source definition of the category for the locale specified.

Output files

The format of the created output corresponds to the format of the internationalization database on POSIX systems:

name if slashes are contained) or ./name (without slashes) is the pathname of a directory containing the following newly generated files:

LC_COLLATE	File with collating information
LC_CTYPE	File with information on the character type (ctype)
LC_MONETARY	File with monetary information
LC_NUMERIC	File with numeric information
LC_TIME	File with date and time information
LC_MESSAGES	Directory with message information
LC_MESSAGES/Xopen_info	File with yes/no information
loc_info	File with information on the name and path of the character map

A copy of the character map is also created in/usr/lib/charmap, if the -f option is used.

Exit status

The following exit values are transferred:
0	No errors occurred and the locales were successfully created.
1	Warnings were output, but the locales were created successfully nonetheless.
2	The locale specification exceeded implementation limits or the coded character set or sets used were not supported by the implementation. No locale was created.
4	Warnings occurred and no output was created.

Error

If an error is detected in the input file, no output file is created.

If warnings occur, an output file is created provided that the -c option was specified. The following conditions will cause warning messages to be output:

• A symbolic name not contained in the charmap file was used for the description of the LC_CTYPE or LC_COLLATE categories (for other categories this causes an error condition).

• The number of operands for the order keyword exceeds the {COLL_WEIGHTS_MAX} limit.

• The source contains optional keywords which are not supported by the implementation.

Hint

The character map definition is optional, and is not contained in the locale definition. This allows both completely self-defined source files and generic sources (applicable to more than one coded character set). To aid portability all character map definitions must have the same symbolic name for portable character sets. It depends on the relevant implementation whether users or applications can use additional character set description files. Therefore, the -f option might only operate correctly if a charmap supported by the implementation is specified.

See also

locale