locale

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



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.


NAME
       locale — get locale-specific information

SYNOPSIS
       locale [−a|−m]

       locale [−ck] name...

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

       When locale 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, Chapter 7, Locale.

       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.

OPTIONS
       The locale utility shall conform to the Base Definitions volume of
       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.

       The following options shall be supported:

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

       −c        Write the names of selected locale categories; see the STDOUT
                 section.  The −c 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 −k option.

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

       −m        Write names of available charmaps; see the Base Definitions
                 volume of POSIX.1‐2008, Section 6.1, Portable Character Set.

OPERANDS
       The following operand shall be supported:

       name      The name of a locale category as defined in the Base
                 Definitions volume of POSIX.1‐2008, Chapter 7, Locale, the name
                 of a keyword in a locale category, or the reserved name
                 charmap.  The named category or keyword shall be selected for
                 output. If a single name 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 name operands, in any sequence. It is
                 implementation-defined whether any keyword values are written
                 for the categories LC_CTYPE and LC_COLLATE.

STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of locale:

       LANG      Provide a default value for the internationalization variables
                 that are unset or null. (See the Base Definitions volume of
                 POSIX.1‐2008, 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_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).

       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.

       The application shall ensure that the LANG, LC_*, and NLSPATH environment
       variables specify the current locale environment to be written out; they
       shall be used if the −a option is not specified.

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       The LANG variable shall be written first using the format:

           "LANG=%s\n", <value>

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

       If locale is invoked without any options or operands, the names and
       values of the LC_* 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 LC_ALL shall be written using
       this format:

           "%s=%s\n", <variable_name>, <value>

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

           "%s=\"%s\"\n", <variable_name>, <implied value>

       The <implied value> shall be the name of the locale that has been
       selected for that category by the implementation, based on the values in
       LANG and LC_ALL, as described in the Base Definitions volume of
       POSIX.1‐2008, Chapter 8, Environment Variables.

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

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

           "LC_ALL=\n"

       If any arguments are specified:

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

               "%s\n", <locale name>

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

               "%s\n", <category name>

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

           If the −c option is not specified, the names of the categories shall
           not be written; only the keywords, as selected by the <name> operand,
           shall be written.

        3. If the −k 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:

               "%s=\"%s\"\n", <keyword name>, <keyword value>

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

               "%s=\"%s\"\n", <keyword name>, <keyword value>

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

               "%s=%s\n", <keyword name>, <keyword value>

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

           If the keyword was charmap, the name of the charmap (if any) that was
           specified via the localedef −f option when the locale was created
           shall be written, with the word charmap as <keyword name>.

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

               "%s=%d\n", <keyword name>, <keyword value>

               "%s=%c%o\n", <keyword name>, <escape character>, <keyword value>

               "%s=%cx%x\n", <keyword name>, <escape character>, <keyword value>

           where the <escape character> is that identified by the escape_char
           keyword in the current locale; see the Base Definitions volume of
           POSIX.1‐2008, Section 7.3, Locale Definition.

           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 −k option is not specified, selected keyword values shall be
           written, each in the following format:

               "%s\n", <keyword value>

           If the keyword was charmap, the name of the charmap (if any) that was
           specified via the localedef −f option when the locale was created
           shall be written.

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

               "%s\n", <charmap>

           where <charmap> is in a format suitable for use as the option-
           argument to the localedef −f option.

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

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       The following exit values shall be returned:

        0    All the requested information was found and output successfully.

       >0    An error occurred.

CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       If the LANG environment variable is not set or set to an empty value, or
       one of the LC_* 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, Chapter 8,
       Environment Variables.

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

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

           LANG=locale_x
           LC_COLLATE=locale_y

       The command locale would result in the following output:

           LANG=locale_x
           LC_CTYPE="locale_x"
           LC_COLLATE=locale_y
           LC_TIME="locale_x"
           LC_NUMERIC="locale_x"
           LC_MONETARY="locale_x"
           LC_MESSAGES="locale_x"
           LC_ALL=

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

       The command:

           LC_ALL=POSIX locale −ck decimal_point

       would produce:

           LC_NUMERIC
           decimal_point="."

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

           if printf "%s\n$response" | grep −Eq "$(locale yesexpr)"
           then
               affirmative processing goes here
           else
               non-affirmative processing goes here
           fi

RATIONALE
       The output for categories LC_CTYPE and LC_COLLATE 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
       localedef source.

       The −m 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 −c 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 −k option.

       The charmap 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, Section 6.1,
       Portable Character Set, 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 locale −a 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 dd utility is the only portable means for performing conversions
       between the two character sets.

FUTURE DIRECTIONS
       None.

SEE ALSO
       localedef

       The Base Definitions volume of POSIX.1‐2008, Section 6.1, Portable
       Character Set, 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 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(1POSIX)