Man Pages

locale(1p) - phpMan locale(1p) - phpMan

Command: man perldoc info search(apropos)  


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



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (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
       IEEE Std 1003.1-2001, Chapter 7, Locale.

       When  invoked  with operands, it shall write values that have been assigned to the keywords in the locale cate-
       gories, 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 IEEE Std 1003.1-2001, 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, repre-
              senting 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 read-
              ability 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 IEEE Std 1003.1-2001, 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 IEEE Std 1003.1-2001, 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 key-
              word 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 IEEE Std 1003.1-2001, Section 8.2, Internationalization Variables for the prece-
              dence 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 exam-
              ple, 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  writ-
              ten 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
       If locale is invoked without any options or operands, the names and values of the  LANG  and  LC_*  environment
       variables  described  in this volume of IEEE Std 1003.1-2001 shall be written to the standard output, one vari-
       able per line, with LANG first, 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
       IEEE Std 1003.1-2001 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 implementa-
       tion,  based  on  the  values  in  LANG  and  LC_ALL,  as  described  in  the  Base   Definitions   volume   of
       IEEE Std 1003.1-2001, 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, it shall be written in the following format:


           "%s=\"%s\"\n", <keyword name>, <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, 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 IEEE Std 1003.1-2001, Section 7.3, Locale Definition.

       Compound keyword values (list entries) shall be separated in the output by semicolons. When included in keyword
       values, the semicolon, the double-quote, the backslash, 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 IEEE Std 1003.1-2001, 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 IEEE Std 1003.1-2001.

       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  affirma-
       tive:


              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 ques-
       tionable 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.

FUTURE DIRECTIONS
       None.

SEE ALSO
       localedef, the Base Definitions volume of IEEE Std 1003.1-2001, Section 7.3, Locale Definition

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Stan-
       dard  for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifica-
       tions 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 Stan-
       dard, 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 .



IEEE/The Open Group                  2003                           LOCALE(1P)