LOCALEDEF(1)               POSIX Programmer's Manual              LOCALEDEF(1)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NAME
       localedef -- define locale environment

SYNOPSIS
       localedef [[-c]] [[-f charmap]] [[-i sourcefile]] [[-u code__set__name]] name

DESCRIPTION
       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 the Base Definitions volume of
       POSIX.1-2017, 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.

       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 restricted-access locales. Implementations may
       restrict the capability to create or modify public locales to users
       with appropriate privileges.

       Each category source definition shall be identified by the
       corresponding 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-2017, 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
                 character symbols and collating element symbols to actual
                 character encodings.  The format of the charmap is described
                 in the Base Definitions volume of POSIX.1-2017, 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 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-2017, 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
                 encoding 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-2017, Chapter _7, Locale 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 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
                 public. The ability to create public locales in this way may
                 be restricted to users with appropriate privileges. (As a
                 consequence 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-2017, 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-2017, Section
       6.4, Character Set Description File.  If a locale category source
       definition contains a copy statement, as defined in the Base
       Definitions volume of POSIX.1-2017, 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
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, Section 8.2, Internationalization
                 Variables 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
                 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.

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
       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 charmap file. The codeset represented by the
       implementation-defined name can be any codeset that is supported by the
       implementation.

       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
       represented by the -u option-argument code__set__name, the result is
       unspecified.

       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 --11, 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
             implementation, 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
       portability, all charmap definitions must use the same symbolic names
       for the portable character set. As explained in the Base Definitions
       volume of POSIX.1-2017, 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 -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
       consequence, 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-2017, 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-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

       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.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                         LOCALEDEF(1)
