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



PPRROOLLOOGG
       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.

NNAAMMEE
       localedef -- define locale environment

SSYYNNOOPPSSIISS
       localedef [[-c]] [[-f _c_h_a_r_m_a_p]] [[-i _s_o_u_r_c_e_f_i_l_e]] [[-u _c_o_d_e___s_e_t___n_a_m_e]] _n_a_m_e

DDEESSCCRRIIPPTTIIOONN
       The _l_o_c_a_l_e_d_e_f 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, _C_h_a_p_t_e_r _7, _L_o_c_a_l_e.  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 --ii
       option (if specified) or from standard input.

       The _n_a_m_e operand identifies the target locale. The utility shall
       support the creation of _p_u_b_l_i_c, or generally accessible locales, as
       well as _p_r_i_v_a_t_e, 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 EENNDD
       _c_a_t_e_g_o_r_y_-_n_a_m_e statement. The following categories shall be supported.
       In addition, the input may contain source for implementation-defined
       categories.

       _L_C___C_T_Y_P_E  Defines character classification and case conversion.

       _L_C___C_O_L_L_A_T_E
                 Defines collation rules.

       _L_C___M_O_N_E_T_A_R_Y
                 Defines the format and symbols used in formatting of monetary
                 information.

       _L_C___N_U_M_E_R_I_C
                 Defines the decimal delimiter, grouping, and grouping symbol
                 for non-monetary numeric editing.

       _L_C___T_I_M_E   Defines the format and content of date and time information.

       _L_C___M_E_S_S_A_G_E_S
                 Defines the format and values of affirmative and negative
                 responses.

OOPPTTIIOONNSS
       The _l_o_c_a_l_e_d_e_f utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following options shall be supported:

       --cc        Create permanent output even if warning messages have been
                 issued.

       --ff _c_h_a_r_m_a_p
                 Specify the pathname of a file containing a mapping of
                 character symbols and collating element symbols to actual
                 character encodings.  The format of the _c_h_a_r_m_a_p is described
                 in the Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _6_._4,
                 _C_h_a_r_a_c_t_e_r _S_e_t _D_e_s_c_r_i_p_t_i_o_n _F_i_l_e.  The application shall ensure
                 that this option is specified if symbolic names (other than
                 collating symbols defined in a ccoollllaattiinngg--ssyymmbbooll keyword) are
                 used. If the --ff option is not present, an implementation-
                 defined character mapping shall be used.

       --ii _i_n_p_u_t_f_i_l_e
                 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 _i_n_p_u_t_f_i_l_e is described
                 in the Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _7_._3,
                 _L_o_c_a_l_e _D_e_f_i_n_i_t_i_o_n.

       --uu _c_o_d_e___s_e_t___n_a_m_e
                 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.

OOPPEERRAANNDDSS
       The following operand shall be supported:

       _n_a_m_e      Identifies the locale; see the Base Definitions volume of
                 POSIX.1-2017, _C_h_a_p_t_e_r _7, _L_o_c_a_l_e for a description of the use
                 of this name. If the name contains one or more <slash>
                 characters, _n_a_m_e shall be interpreted as a pathname where the
                 created locale definitions shall be stored. If _n_a_m_e 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 _n_a_m_e, although several
                 categories can be processed in one execution, only categories
                 belonging to the same locale can be processed.)

SSTTDDIINN
       Unless the --ii 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, _S_e_c_t_i_o_n _7_._3,
       _L_o_c_a_l_e _D_e_f_i_n_i_t_i_o_n.  When lines are continued using the escape character
       mechanism, there is no limit to the length of the accumulated continued
       line.

IINNPPUUTT FFIILLEESS
       The character set mapping file specified as the _c_h_a_r_m_a_p option-argument
       is described in the Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n
       _6_._4, _C_h_a_r_a_c_t_e_r _S_e_t _D_e_s_c_r_i_p_t_i_o_n _F_i_l_e.  If a locale category source
       definition contains a ccooppyy statement, as defined in the Base
       Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _7, _L_o_c_a_l_e, and the ccooppyy
       statement names a valid, existing locale, then _l_o_c_a_l_e_d_e_f shall behave
       as if the source definition had contained a valid category source
       definition for the named locale.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of
       _l_o_c_a_l_e_d_e_f:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_O_L_L_A_T_E
                 (This variable has no affect on _l_o_c_a_l_e_d_e_f; the POSIX locale
                 is used for this category.)

       _L_C___C_T_Y_P_E  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
                 _l_o_c_a_l_e_d_e_f input data; the POSIX locale is used for this
                 purpose, regardless of the value of this variable.

       _L_C___M_E_S_S_A_G_E_S
                 Determine the locale that should be used to affect the format
                 and contents of diagnostic messages written to standard
                 error.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

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

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       The format of the created output is unspecified. If the _n_a_m_e operand
       does not contain a <slash>, the existence of an output file for the
       locale is unspecified.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       When the --uu option is used, the _c_o_d_e___s_e_t___n_a_m_e 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 _c_h_a_r_m_a_p file. The codeset represented by the
       implementation-defined name can be any codeset that is supported by the
       implementation.

       When conflicts occur between the _c_h_a_r_m_a_p specification of
       <_c_o_d_e___s_e_t___n_a_m_e>, <_m_b___c_u_r___m_a_x>, or <_m_b___c_u_r___m_i_n> and the implementation-
       defined interpretation of these respective items for the codeset
       represented by the --uu option-argument _c_o_d_e___s_e_t___n_a_m_e, the result is
       unspecified.

       When conflicts occur between the _c_h_a_r_m_a_p 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 _c_h_a_r_m_a_p has a width specified that
       is not --11, the result will be undefined.

EEXXIITT SSTTAATTUUSS
       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.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       If an error is detected, no permanent output shall be created.

       If warnings occur, permanent output shall be created if the --cc option
       was specified. The following conditions shall cause warning messages to
       be issued:

        *  If a symbolic name not found in the _c_h_a_r_m_a_p file is used for the
           descriptions of the _L_C___C_T_Y_P_E or _L_C___C_O_L_L_A_T_E categories (for other
           categories, this shall be an error condition).

        *  If the number of operands to the oorrddeerr 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.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The _c_h_a_r_m_a_p 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 _c_h_a_r_m_a_p definitions must use the same symbolic names
       for the portable character set. As explained in the Base Definitions
       volume of POSIX.1-2017, _S_e_c_t_i_o_n _6_._4, _C_h_a_r_a_c_t_e_r _S_e_t _D_e_s_c_r_i_p_t_i_o_n _F_i_l_e, it
       is implementation-defined whether or not users or applications can
       provide additional character set description files. Therefore, the --ff
       option might be operable only when an implementation-defined _c_h_a_r_m_a_p is
       named.

EEXXAAMMPPLLEESS
       None.

RRAATTIIOONNAALLEE
       The output produced by the _l_o_c_a_l_e_d_e_f utility is implementation-defined.
       The _n_a_m_e 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.)

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _l_o_c_a_l_e

       The Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _6_._4, _C_h_a_r_a_c_t_e_r _S_e_t
       _D_e_s_c_r_i_p_t_i_o_n _F_i_l_e, _C_h_a_p_t_e_r _7, _L_o_c_a_l_e, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s,
       _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

CCOOPPYYRRIIGGHHTT
       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)
