LOCALEDEF(1P) POSIX Programmer's Manual LOCALEDEF(1P)PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux
implementation of this interface may differ (consult the corresponding
Linux manual page for details of Linux behavior), or the interface may
not be implemented on Linux.
NAMElocaledef — define locale environment
SYNOPSISlocaledef [−c] [−f charmap] [−i sourcefile] [−u code_set_name] name
DESCRIPTION
The localedef utility shall convert source definitions for locale cate‐
gories into a format usable by the functions and utilities whose opera‐
tional behavior is determined by the setting of the locale environment
variables defined in the Base Definitions volume of POSIX.1‐2008, Chap‐
ter 7, Locale. It is implementation-defined whether users have the
capability to create new locales, in addition to those supplied by the
implementation. If the symbolic constant POSIX2_LOCALEDEF is defined,
the system supports the creation of new locales. On XSI-conformant
systems, the symbolic constant POSIX2_LOCALEDEF shall be defined.
The utility shall read source definitions for one or more locale cate‐
gories 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 sup‐
port the creation of public, or generally accessible locales, as well
as private, or restricted-access locales. Implementations may restrict
the capability to create or modify public locales to users with appro‐
priate privileges.
Each category source definition shall be identified by the correspond‐
ing environment variable name and terminated by an END 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.
LC_MONETARY
Defines the format and symbols used in formatting of monetary
information.
LC_NUMERIC
Defines the decimal delimiter, grouping, and grouping symbol
for non-monetary numeric editing.
LC_TIME Defines the format and content of date and time information.
LC_MESSAGES
Defines the format and values of affirmative and negative
responses.
OPTIONS
The localedef utility shall conform to the Base Definitions volume of
POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
The following options shall be supported:
−c Create permanent output even if warning messages have been
issued.
−f charmap
Specify the pathname of a file containing a mapping of char‐
acter symbols and collating element symbols to actual charac‐
ter encodings. The format of the charmap is described in the
Base Definitions volume of POSIX.1‐2008, Section 6.4, Charac‐
ter Set Description File. The application shall ensure that
this option is specified if symbolic names (other than col‐
lating symbols defined in a collating-symbol keyword) are
used. If the −f option is not present, an implementation-
defined character mapping shall be used.
−i 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 the Base Definitions volume of POSIX.1‐2008, Section 7.3,
Locale Definition.
−u code_set_name
Specify the name of a codeset used as the target mapping of
character symbols and collating element symbols whose encod‐
ing values are defined in terms of the ISO/IEC 10646‐1:2000
standard position constant values.
OPERANDS
The following operand shall be supported:
name Identifies the locale; see the Base Definitions volume of
POSIX.1‐2008, Chapter 7, Locale for a description of the use
of this name. If the name contains one or more <slash> char‐
acters, name shall be interpreted as a pathname where the
created locale definitions shall be stored. If name does not
contain any <slash> characters, the interpretation of the
name is implementation-defined and the locale shall be pub‐
lic. The ability to create public locales in this way may be
restricted to users with appropriate privileges. (As a conse‐
quence of specifying one name, although several categories
can be processed in one execution, only categories belonging
to the same locale can be processed.)
STDIN
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 the Base Definitions volume of POSIX.1‐2008, Section 7.3,
Locale Definition. When lines are continued using the escape character
mechanism, there is no limit to the length of the accumulated continued
line.
INPUT FILES
The character set mapping file specified as the charmap option-argument
is described in the Base Definitions volume of POSIX.1‐2008, Section
6.4, Character Set Description File. If a locale category source defi‐
nition contains a copy statement, as defined in the Base Definitions
volume of POSIX.1‐2008, Chapter 7, Locale, 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.
ENVIRONMENT VARIABLES
The following environment variables shall affect the execution of
localedef:
LANG Provide a default value for the internationalization vari‐
ables that are unset or null. (See the Base Definitions vol‐
ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
ables for the precedence of internationalization variables
used to determine the values of locale categories.)
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
is used for this category.)
LC_CTYPE Determine the locale for the interpretation of sequences of
bytes of text data as characters (for example, single-byte as
opposed to multi-byte 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 pur‐
pose, 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.
ASYNCHRONOUS EVENTS
Default.
STDOUT
The utility shall report all categories successfully processed, in an
unspecified format.
STDERR
The standard error shall be used only for diagnostic messages.
OUTPUT FILES
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.
EXTENDED DESCRIPTION
When the −u option is used, the code_set_name option-argument shall be
interpreted as an implementation-defined name of a codeset to which the
ISO/IEC 10646‐1:2000 standard position constant values shall be con‐
verted via an implementation-defined method. Both the
ISO/IEC 10646‐1:2000 standard position constant values and other for‐
mats (decimal, hexadecimal, or octal) shall be valid as encoding values
within the charmap file. The codeset represented by the implementation-
defined name can be any codeset that is supported by the implementa‐
tion.
When conflicts occur between the charmap specification of
<code_set_name>, <mb_cur_max>, or <mb_cur_min> and the implementation-
defined interpretation of these respective items for the codeset repre‐
sented by the −u option-argument code_set_name, the result is unspeci‐
fied.
When conflicts occur between the charmap encoding values specified for
symbolic names of characters of the portable character set and the
implementation-defined assignment of character encoding values, the
result is unspecified.
If a non-printable character in the charmap has a width specified that
is not −1, the result will be undefined.
EXIT STATUS
The following exit values shall be returned:
0 No errors occurred and the locales were successfully created.
1 Warnings occurred and the locales were successfully created.
2 The locale specification exceeded implementation limits or the
coded character set or sets used were not supported by the imple‐
mentation, and no locale was created.
3 The capability to create new locales is not supported by the
implementation.
>3 Warnings or errors occurred and no output was created.
CONSEQUENCES OF ERRORS
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 condition).
* If the number of operands to the order keyword exceeds the
{COLL_WEIGHTS_MAX} limit.
* If optional keywords not supported by the implementation are
present in the source.
Other implementation-defined conditions may also cause warnings.
The following sections are informative.
APPLICATION USAGE
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 codeset). To aid portabil‐
ity, all charmap definitions must use the same symbolic names for the
portable character set. As explained in the Base Definitions volume of
POSIX.1‐2008, Section 6.4, Character Set Description File, it is imple‐
mentation-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-defined charmap is named.
EXAMPLES
None.
RATIONALE
The output produced by the localedef utility is implementation-defined.
The name operand is used to identify the specific locale. (As a conse‐
quence, although several categories can be processed in one execution,
only categories belonging to the same locale can be processed.)
FUTURE DIRECTIONS
None.
SEE ALSO
locale
The Base Definitions volume of POSIX.1‐2008, Section 6.4, Character Set
Description File, Chapter 7, Locale, Chapter 8, Environment Variables,
Section 12.2, Utility Syntax Guidelines
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
cal and Electronics Engineers, Inc and The Open Group. (This is
POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online
at http://www.unix.org/online.html .
Any typographical or formatting errors that appear in this page are
most likely to have been introduced during the conversion of the source
files to man page format. To report such errors, see https://www.ker‐
nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2013 LOCALEDEF(1P)