path: root/man1p/localedef.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "LOCALEDEF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" localedef 
.SH NAME
localedef \- define locale environment
.SH SYNOPSIS
.LP
\fBlocaledef\fP \fB[\fP\fB-c\fP\fB][\fP\fB-f\fP \fIcharmap\fP\fB][\fP\fB-i\fP
\fIsourcefile\fP\fB][\fP\fB-u\fP \fIcode_set_name\fP\fB]\fP \fIname\fP
.SH DESCRIPTION
.LP
The \fIlocaledef\fP 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 the Base
Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 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. 
.LP
The utility shall read source definitions for one or more locale categories
belonging to the same locale from the file named in
the \fB-i\fP option (if specified) or from standard input.
.LP
The \fIname\fP operand identifies the target locale. The utility shall
support the creation of \fIpublic\fP, or generally
accessible locales, as well as \fIprivate\fP, or restricted-access
locales. Implementations may restrict the capability to create
or modify public locales to users with the appropriate privileges.
.LP
Each category source definition shall be identified by the corresponding
environment variable name and terminated by an
\fBEND\fP \fIcategory-name\fP statement. The following categories
shall be supported. In addition, the input may contain source
for implementation-defined categories.
.TP 7
\fILC_CTYPE\fP
Defines character classification and case conversion.
.TP 7
\fILC_COLLATE\fP
.sp
Defines collation rules.
.TP 7
\fILC_MONETARY\fP
.sp
Defines the format and symbols used in formatting of monetary information.
.TP 7
\fILC_NUMERIC\fP
.sp
Defines the decimal delimiter, grouping, and grouping symbol for non-monetary
numeric editing.
.TP 7
\fILC_TIME\fP
Defines the format and content of date and time information.
.TP 7
\fILC_MESSAGES\fP
.sp
Defines the format and values of affirmative and negative responses.
.sp
.SH OPTIONS
.LP
The \fIlocaledef\fP utility shall conform to the Base Definitions
volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported:
.TP 7
\fB-c\fP
Create permanent output even if warning messages have been issued.
.TP 7
\fB-f\ \fP \fIcharmap\fP
Specify the pathname of a file containing a mapping of character symbols
and collating element symbols to actual character
encodings. The format of the \fIcharmap\fP is described in the Base
Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.4, Character
Set Description File. The application shall ensure that this
option is specified if symbolic names (other than collating symbols
defined in a \fBcollating-symbol\fP keyword) are used. If the
\fB-f\fP option is not present, an implementation-defined character
mapping shall be used.
.TP 7
\fB-i\ \fP \fIinputfile\fP
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 \fIinputfile\fP is described in
the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
Section 7.3, Locale Definition.
.TP 7
\fB-u\ \fP \fIcode_set_name\fP
.sp
Specify the name of a codeset used as the target mapping of character
symbols and collating element symbols whose encoding values
are defined in terms of the ISO/IEC\ 10646-1:2000 standard position
constant values.
.sp
.SH OPERANDS
.LP
The following operand shall be supported:
.TP 7
\fIname\fP
Identifies the locale; see the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
Chapter 7, Locale for a description of the use of this name. If the
name contains one or more
slash characters, \fIname\fP shall be interpreted as a pathname where
the created locale definitions shall be stored. If
\fIname\fP 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. (As a consequence of specifying one \fIname\fP,
although several categories can be processed in one execution, only
categories belonging to the same locale can be processed.)
.sp
.SH STDIN
.LP
Unless the \fB-i\fP 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 IEEE\ Std\ 1003.1-2001,
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.
.SH INPUT FILES
.LP
The character set mapping file specified as the \fIcharmap\fP option-argument
is described in the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 6.4, Character Set Description File.
If
a locale category source definition contains a \fBcopy\fP statement,
as defined in the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Chapter 7, Locale, and the \fBcopy\fP statement
names a
valid, existing locale, then \fIlocaledef\fP shall behave as if the
source definition had contained a valid category source
definition for the named locale.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIlocaledef\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_COLLATE\fP
.sp
(This variable has no affect on \fIlocaledef\fP; the POSIX locale
is used for this category.)
.TP 7
\fILC_CTYPE\fP
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 \fIlocaledef\fP
input data; the POSIX locale is used for this purpose, regardless
of the value of this variable.
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
The utility shall report all categories successfully processed, in
an unspecified format.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
The format of the created output is unspecified. If the \fIname\fP
operand does not contain a slash, the existence of an output
file for the locale is unspecified.
.SH EXTENDED DESCRIPTION
.LP
When the \fB-u\fP option is used, the \fIcode_set_name\fP 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 converted via an
implementation-defined method. Both the ISO/IEC\ 10646-1:2000 standard
position constant values and other formats (decimal,
hexadecimal, or octal) shall be valid as encoding values within the
\fIcharmap\fP file. The codeset represented by the
implementation-defined name can be any codeset that is supported by
the implementation.
.LP
When conflicts occur between the \fIcharmap\fP specification of <\fIcode_set_name\fP>,
<\fImb_cur_max\fP>, or
<\fImb_cur_min\fP> and the implementation-defined interpretation of
these respective items for the codeset represented by
the \fB-u\fP option-argument \fIcode_set_name\fP, the result is unspecified.
.LP
When conflicts occur between the \fIcharmap\fP 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.
.LP
If a non-printable character in the \fIcharmap\fP has a width specified
that is not \fB-1\fP, \fIlocaledef\fP shall generate
a warning.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
No errors occurred and the locales were successfully created.
.TP 7
\ 1
Warnings occurred and the locales were successfully created.
.TP 7
\ 2
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.
.TP 7
\ 3
The capability to create new locales is not supported by the implementation.
.TP 7
>3
Warnings or errors occurred and no output was created.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
If an error is detected, no permanent output shall be created.
.LP
If warnings occur, permanent output shall be created if the \fB-c\fP
option was specified. The following conditions shall cause
warning messages to be issued:
.IP " *" 3
If a symbolic name not found in the \fIcharmap\fP file is used for
the descriptions of the \fILC_CTYPE\fP or \fILC_COLLATE\fP
categories (for other categories, this shall be an error condition).
.LP
.IP " *" 3
If the number of operands to the \fBorder\fP keyword exceeds the {COLL_WEIGHTS_MAX}
limit.
.LP
.IP " *" 3
If optional keywords not supported by the implementation are present
in the source.
.LP
.IP " *" 3
If a non-printable character has a width specified other than -1.
.LP
.LP
Other implementation-defined conditions may also cause warnings.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
The \fIcharmap\fP 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 portability, all \fIcharmap\fP
definitions must use the same symbolic names for the portable character
set. As explained in the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 6.4, Character Set Description File,
it
is implementation-defined whether or not users or applications can
provide additional character set description files. Therefore,
the \fB-f\fP option might be operable only when an implementation-defined
\fIcharmap\fP is named.
.SH EXAMPLES
.LP
None.
.SH RATIONALE
.LP
The output produced by the \fIlocaledef\fP utility is implementation-defined.
The \fIname\fP 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.)
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIlocale\fP , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
Section 7.3, Locale Definition
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html .