LOCALE(1)                  POSIX Programmer's Manual                 LOCALE(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
       locale -- get locale-specific information

SSYYNNOOPPSSIISS
       locale [[-a|-m]]

       locale [[-ck]] _n_a_m_e...

DDEESSCCRRIIPPTTIIOONN
       The _l_o_c_a_l_e utility shall write information about the current locale
       environment, or all public locales, to the standard output. For the
       purposes of this section, a _p_u_b_l_i_c _l_o_c_a_l_e is one provided by the
       implementation that is accessible to the application.

       When _l_o_c_a_l_e is invoked without any arguments, it shall summarize the
       current locale environment for each locale category as determined by
       the settings of the environment variables defined in the Base
       Definitions volume of POSIX.1-2008, _C_h_a_p_t_e_r _7, _L_o_c_a_l_e.

       When invoked with operands, it shall write values that have been
       assigned to the keywords in the locale categories, as follows:

        *  Specifying a keyword name shall select the named keyword and the
           category containing that keyword.

        *  Specifying a category name shall select the named category and all
           keywords in that category.

OOPPTTIIOONNSS
       The _l_o_c_a_l_e utility shall conform to the Base Definitions volume of
       POSIX.1-2008, _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:

       --aa        Write information about all available public locales. The
                 available locales shall include PPOOSSIIXX, representing the POSIX
                 locale. The manner in which the implementation determines
                 what other locales are available is implementation-defined.

       --cc        Write the names of selected locale categories; see the STDOUT
                 section.  The --cc option increases readability when more than
                 one category is selected (for example, via more than one
                 keyword name or via a category name).  It is valid both with
                 and without the --kk option.

       --kk        Write the names and values of selected keywords. The
                 implementation may omit values for some keywords; see the
                 OPERANDS section.

       --mm        Write names of available charmaps; see the Base Definitions
                 volume of POSIX.1-2008, _S_e_c_t_i_o_n _6_._1, _P_o_r_t_a_b_l_e _C_h_a_r_a_c_t_e_r _S_e_t.

OOPPEERRAANNDDSS
       The following operand shall be supported:

       _n_a_m_e      The name of a locale category as defined in the Base
                 Definitions volume of POSIX.1-2008, _C_h_a_p_t_e_r _7, _L_o_c_a_l_e, the
                 name of a keyword in a locale category, or the reserved name
                 cchhaarrmmaapp.  The named category or keyword shall be selected for
                 output. If a single _n_a_m_e represents both a locale category
                 name and a keyword name in the current locale, the results
                 are unspecified. Otherwise, both category and keyword names
                 can be specified as _n_a_m_e operands, in any sequence. It is
                 implementation-defined whether any keyword values are written
                 for the categories _L_C___C_T_Y_P_E and _L_C___C_O_L_L_A_T_E.

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
       None.

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

       _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-2008, _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_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).

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

       The application shall ensure that the _L_A_N_G, _L_C___*, and _N_L_S_P_A_T_H
       environment variables specify the current locale environment to be
       written out; they shall be used if the --aa option is not specified.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       The _L_A_N_G variable shall be written first using the format:

           ""LLAANNGG==%%ss\\nn"",, <<_v_a_l_u_e>

       If _L_A_N_G is not set or is an empty string, the value is the empty
       string.

       If _l_o_c_a_l_e is invoked without any options or operands, the names and
       values of the _L_C___* environment variables described in this volume of
       POSIX.1-2008 shall be written to the standard output, one variable per
       line, and each line using the following format. Only those variables
       set in the environment and not overridden by _L_C___A_L_L shall be written
       using this format:

           ""%%ss==%%ss\\nn"",, <<_v_a_r_i_a_b_l_e___n_a_m_e>, <_v_a_l_u_e>

       The names of those _L_C___* variables associated with locale categories
       defined in this volume of POSIX.1-2008 that are not set in the
       environment or are overridden by _L_C___A_L_L shall be written in the
       following format:

           ""%%ss==\\""%%ss\\""\\nn"",, <<_v_a_r_i_a_b_l_e___n_a_m_e>, <_i_m_p_l_i_e_d _v_a_l_u_e>

       The <_i_m_p_l_i_e_d _v_a_l_u_e> shall be the name of the locale that has been
       selected for that category by the implementation, based on the values
       in _L_A_N_G and _L_C___A_L_L, as described in the Base Definitions volume of
       POSIX.1-2008, _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.

       The <_v_a_l_u_e> and <_i_m_p_l_i_e_d _v_a_l_u_e> shown above shall be properly quoted
       for possible later reentry to the shell. The <_v_a_l_u_e> shall not be
       quoted using double-quotes (so that it can be distinguished by the user
       from the <_i_m_p_l_i_e_d _v_a_l_u_e> case, which always requires double-quotes).

       The _L_C___A_L_L variable shall be written last, using the first format shown
       above. If it is not set, it shall be written as:

           ""LLCC__AALLLL==\\nn""

       If any arguments are specified:

        1. If the --aa option is specified, the names of all the public locales
           shall be written, each in the following format:

               ""%%ss\\nn"",, <<_l_o_c_a_l_e _n_a_m_e>

        2. If the --cc option is specified, the names of all selected categories
           shall be written, each in the following format:

               ""%%ss\\nn"",, <<_c_a_t_e_g_o_r_y _n_a_m_e>

           If keywords are also selected for writing (see following items),
           the category name output shall precede the keyword output for that
           category.

           If the --cc option is not specified, the names of the categories
           shall not be written; only the keywords, as selected by the <_n_a_m_e>
           operand, shall be written.

        3. If the --kk option is specified, the names and values of selected
           keywords shall be written. If a value is non-numeric and is not a
           compound keyword value, it shall be written in the following
           format:

               ""%%ss==\\""%%ss\\""\\nn"",, <<_k_e_y_w_o_r_d _n_a_m_e>, <_k_e_y_w_o_r_d _v_a_l_u_e>

           If a value is a non-numeric compound keyword value, it shall either
           be written in the format:

               ""%%ss==\\""%%ss\\""\\nn"",, <<_k_e_y_w_o_r_d _n_a_m_e>, <_k_e_y_w_o_r_d _v_a_l_u_e>

           where the <_k_e_y_w_o_r_d _v_a_l_u_e> is a single string of values separated by
           <semicolon> characters, or it shall be written in the format:

               ""%%ss==%%ss\\nn"",, <<_k_e_y_w_o_r_d _n_a_m_e>, <_k_e_y_w_o_r_d _v_a_l_u_e>

           where the <_k_e_y_w_o_r_d _v_a_l_u_e> is encoded as a set of strings, each
           enclosed in double-quotation-marks, separated by <semicolon>
           characters.

           If the keyword was cchhaarrmmaapp, the name of the charmap (if any) that
           was specified via the _l_o_c_a_l_e_d_e_f --ff option when the locale was
           created shall be written, with the word cchhaarrmmaapp as <_k_e_y_w_o_r_d _n_a_m_e>.

           If a value is numeric, it shall be written in one of the following
           formats:

               ""%%ss==%%dd\\nn"",, <<_k_e_y_w_o_r_d _n_a_m_e>, <_k_e_y_w_o_r_d _v_a_l_u_e>

               "%s=%c%o\n", <_k_e_y_w_o_r_d _n_a_m_e>, <_e_s_c_a_p_e _c_h_a_r_a_c_t_e_r>, <_k_e_y_w_o_r_d _v_a_l_u_e>

               "%s=%cx%x\n", <_k_e_y_w_o_r_d _n_a_m_e>, <_e_s_c_a_p_e _c_h_a_r_a_c_t_e_r>, <_k_e_y_w_o_r_d _v_a_l_u_e>

           where the <_e_s_c_a_p_e _c_h_a_r_a_c_t_e_r> is that identified by the eessccaappee__cchhaarr
           keyword in the current locale; see the Base Definitions volume of
           POSIX.1-2008, _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.

           Compound keyword values (list entries) shall be separated in the
           output by <semicolon> characters. When included in keyword values,
           the <semicolon>, <backslash>, double-quote, and any control
           character shall be preceded (escaped) with the escape character.

        4. If the --kk option is not specified, selected keyword values shall be
           written, each in the following format:

               ""%%ss\\nn"",, <<_k_e_y_w_o_r_d _v_a_l_u_e>

           If the keyword was cchhaarrmmaapp, the name of the charmap (if any) that
           was specified via the _l_o_c_a_l_e_d_e_f --ff option when the locale was
           created shall be written.

        5. If the --mm option is specified, then a list of all available
           charmaps shall be written, each in the format:

               ""%%ss\\nn"",, <<_c_h_a_r_m_a_p>

           where <_c_h_a_r_m_a_p> is in a format suitable for use as the option-
           argument to the _l_o_c_a_l_e_d_e_f --ff option.

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

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    All the requested information was found and output successfully.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _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
       If the _L_A_N_G environment variable is not set or set to an empty value,
       or one of the _L_C___* environment variables is set to an unrecognized
       value, the actual locales assumed (if any) are implementation-defined
       as described in the Base Definitions volume of POSIX.1-2008, _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.

       Implementations are not required to write out the actual values for
       keywords in the categories _L_C___C_T_Y_P_E and _L_C___C_O_L_L_A_T_E; however, they must
       write out the categories (allowing an application to determine, for
       example, which character classes are available).

EEXXAAMMPPLLEESS
       In the following examples, the assumption is that locale environment
       variables are set as follows:

           LLAANNGG==llooccaallee__xx
           LLCC__CCOOLLLLAATTEE==llooccaallee__yy

       The command _l_o_c_a_l_e would result in the following output:

           LLAANNGG==llooccaallee__xx
           LLCC__CCTTYYPPEE==""llooccaallee__xx""
           LLCC__CCOOLLLLAATTEE==llooccaallee__yy
           LLCC__TTIIMMEE==""llooccaallee__xx""
           LLCC__NNUUMMEERRIICC==""llooccaallee__xx""
           LLCC__MMOONNEETTAARRYY==""llooccaallee__xx""
           LLCC__MMEESSSSAAGGEESS==""llooccaallee__xx""
           LLCC__AALLLL==

       The order of presentation of the categories is not specified by this
       volume of POSIX.1-2008.

       The command:

           LLCC__AALLLL==PPOOSSIIXX llooccaallee --cckk ddeecciimmaall__ppooiinntt

       would produce:

           LLCC__NNUUMMEERRIICC
           ddeecciimmaall__ppooiinntt==""..""

       The following command shows an application of _l_o_c_a_l_e to determine
       whether a user-supplied response is affirmative:

           iiff pprriinnttff ""%%ss\\nn$$rreessppoonnssee"" || ggrreepp --EEqq ""$$((llooccaallee yyeesseexxpprr))""
           tthheenn
               aaffffiirrmmaattiivvee pprroocceessssiinngg ggooeess hheerree
           eellssee
               nnoonn--aaffffiirrmmaattiivvee pprroocceessssiinngg ggooeess hheerree
           ffii

RRAATTIIOONNAALLEE
       The output for categories _L_C___C_T_Y_P_E and _L_C___C_O_L_L_A_T_E has been made
       implementation-defined because there is a questionable value in having
       a shell script receive an entire array of characters.  It is also
       difficult to return a logical collation description, short of returning
       a complete _l_o_c_a_l_e_d_e_f source.

       The --mm option was included to allow applications to query for the
       existence of charmaps.  The output is a list of the charmaps
       (implementation-supplied and user-supplied, if any) on the system.

       The --cc option was included for readability when more than one category
       is selected (for example, via more than one keyword name or via a
       category name). It is valid both with and without the --kk option.

       The cchhaarrmmaapp keyword, which returns the name of the charmap (if any)
       that was used when the current locale was created, was included to
       allow applications needing the information to retrieve it.

       According to the Base Definitions volume of POSIX.1-2008, _S_e_c_t_i_o_n _6_._1,
       _P_o_r_t_a_b_l_e _C_h_a_r_a_c_t_e_r _S_e_t, the standard requires that all supported
       locales must have the same encoding for <period> and <slash>, because
       these two characters are used within the locale-independent pathname
       resolution sequence. Therefore, it would be an error if _l_o_c_a_l_e --aa
       listed both ASCII and EBCDIC-based locales, since those two encodings
       do not share the same representation for either <period> or <slash>.
       Any system that supports both environments would be expected to provide
       two POSIX locales, one in either codeset, where only the locales
       appropriate to the current environment can be visible at a time. In an
       XSI-compliant implementation, the _d_d utility is the only portable means
       for performing conversions between the two character sets.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _l_o_c_a_l_e_d_e_f

       The Base Definitions volume of POSIX.1-2008, _S_e_c_t_i_o_n _6_._1, _P_o_r_t_a_b_l_e
       _C_h_a_r_a_c_t_e_r _S_e_t, _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, 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
       Electrical 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.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                            LOCALE(1)
