locale.1p (14497B)
- '\" et
- .TH LOCALE "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH 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.
- .\"
- .SH NAME
- locale
- \(em get locale-specific information
- .SH SYNOPSIS
- .LP
- .nf
- locale \fB[\fR-a|-m\fB]\fR
- .P
- locale \fB[\fR-ck\fB] \fIname\fR...
- .fi
- .SH DESCRIPTION
- The
- .IR 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
- .IR "public locale"
- is one provided by the implementation that is accessible to the
- application.
- .P
- When
- .IR 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\(hy2017,
- .IR "Chapter 7" ", " "Locale".
- .P
- When invoked with operands, it shall write values that have been
- assigned to the keywords in the locale categories, as follows:
- .IP " *" 4
- Specifying a keyword name shall select the named keyword and the
- category containing that keyword.
- .IP " *" 4
- Specifying a category name shall select the named category and all
- keywords in that category.
- .SH OPTIONS
- The
- .IR locale
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following options shall be supported:
- .IP "\fB\-a\fP" 10
- Write information about all available public locales. The available
- locales shall include
- .BR POSIX ,
- representing the POSIX locale. The manner in which the implementation
- determines what other locales are available is
- implementation-defined.
- .IP "\fB\-c\fP" 10
- Write the names of selected locale categories; see the STDOUT section.
- The
- .BR \-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
- .BR \-k
- option.
- .IP "\fB\-k\fP" 10
- Write the names and values of selected keywords. The implementation
- may omit values for some keywords; see the OPERANDS section.
- .IP "\fB\-m\fP" 10
- Write names of available charmaps; see the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 6.1" ", " "Portable Character Set".
- .SH OPERANDS
- The following operand shall be supported:
- .IP "\fIname\fR" 10
- The name of a locale category as defined in the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 7" ", " "Locale",
- the name of a keyword in a locale category, or the reserved name
- .BR charmap .
- The named category or keyword shall be selected for output. If a
- single
- .IR 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
- .IR name
- operands, in any sequence. It is implementation-defined whether any
- keyword values are written for the categories
- .IR LC_CTYPE
- and
- .IR LC_COLLATE .
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- None.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR locale :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- 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).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .P
- The application shall ensure that the
- .IR LANG ,
- .IR LC_* ,
- and
- .IR NLSPATH
- environment variables specify the current locale environment to be
- written out; they shall be used if the
- .BR \-a
- option is not specified.
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- The
- .IR LANG
- variable shall be written first using the format:
- .sp
- .RS 4
- .nf
- "LANG=%s\en", <\fIvalue\fR>
- .fi
- .P
- .RE
- .P
- If
- .IR LANG
- is not set or is an empty string, the value is the empty string.
- .P
- If
- .IR locale
- is invoked without any options or operands, the names and values of the
- .IR LC_*
- environment variables described in this volume of POSIX.1\(hy2017 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
- .IR LC_ALL
- shall be written using this format:
- .sp
- .RS 4
- .nf
- "%s=%s\en", <\fIvariable_name\fR>, <\fIvalue\fR>
- .fi
- .P
- .RE
- .P
- The names of those
- .IR LC_*
- variables associated with locale categories defined in this volume of POSIX.1\(hy2017 that are
- not set in the environment or are overridden by
- .IR LC_ALL
- shall be written in the following format:
- .sp
- .RS 4
- .nf
- "%s=\e"%s\e"\en", <\fIvariable_name\fR>, <\fIimplied value\fR>
- .fi
- .P
- .RE
- .P
- The <\fIimplied\ value\fP> shall be the name of the locale that has
- been selected for that category by the implementation, based on the
- values in
- .IR LANG
- and
- .IR LC_ALL ,
- as described in the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables".
- .P
- The <\fIvalue\fP> and <\fIimplied\ value\fP> shown above shall be
- properly quoted for possible later reentry to the shell. The
- <\fIvalue\fP> shall not be quoted using double-quotes (so that it can
- be distinguished by the user from the <\fIimplied\ value\fP> case,
- which always requires double-quotes).
- .P
- The
- .IR LC_ALL
- variable shall be written last, using the first format shown above. If
- it is not set, it shall be written as:
- .sp
- .RS 4
- .nf
- "LC_ALL=\en"
- .fi
- .P
- .RE
- .P
- If any arguments are specified:
- .IP " 1." 4
- If the
- .BR \-a
- option is specified, the names of all the public locales shall be
- written, each in the following format:
- .RS 4
- .sp
- .RS 4
- .nf
- "%s\en", <\fIlocale\ name\fR>
- .fi
- .P
- .RE
- .RE
- .IP " 2." 4
- If the
- .BR \-c
- option is specified, the names of all selected categories shall be
- written, each in the following format:
- .RS 4
- .sp
- .RS 4
- .nf
- "%s\en", <\fIcategory\ name\fR>
- .fi
- .P
- .RE
- .P
- If keywords are also selected for writing (see following items), the
- category name output shall precede the keyword output for that
- category.
- .P
- If the
- .BR \-c
- option is not specified, the names of the categories shall not be
- written; only the keywords, as selected by the <\fIname\fP> operand,
- shall be written.
- .RE
- .IP " 3." 4
- If the
- .BR \-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:
- .RS 4
- .sp
- .RS 4
- .nf
- "%s=\e"%s\e"\en", <\fIkeyword name\fR>, <\fIkeyword value\fR>
- .fi
- .P
- .RE
- .P
- If a value is a non-numeric compound keyword value, it shall either be
- written in the format:
- .sp
- .RS 4
- .nf
- "%s=\e"%s\e"\en", <\fIkeyword name\fR>, <\fIkeyword value\fR>
- .fi
- .P
- .RE
- .P
- where the <\fIkeyword value\fR> is a single string of values separated by
- <semicolon>
- characters, or it shall be written in the format:
- .sp
- .RS 4
- .nf
- "%s=%s\en", <\fIkeyword name\fR>, <\fIkeyword value\fR>
- .fi
- .P
- .RE
- .P
- where the <\fIkeyword value\fP> is encoded as a set of strings, each
- enclosed in double-quotation-marks, separated by
- <semicolon>
- characters.
- .P
- If the keyword was
- .BR charmap ,
- the name of the charmap (if any) that was specified via the
- .IR localedef
- .BR \-f
- option when the locale was created shall be written, with the word
- .BR charmap
- as <\fIkeyword\ name\fP>.
- .P
- If a value is numeric, it shall be written in one of the following
- formats:
- .sp
- .RS 4
- .nf
- "%s=%d\en", <\fIkeyword name\fR>, <\fIkeyword value\fR>
- .P
- "%s=%c%o\en", <\fIkeyword name\fR>, <\fIescape character\fR>, <\fIkeyword value\fR>
- .P
- "%s=%cx%x\en", <\fIkeyword name\fR>, <\fIescape character\fR>, <\fIkeyword value\fR>
- .fi
- .P
- .RE
- .P
- where the <\fIescape\ character\fP> is that identified by the
- .BR escape_char
- keyword in the current locale; see the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 7.3" ", " "Locale Definition".
- .P
- 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.
- .RE
- .IP " 4." 4
- If the
- .BR \-k
- option is not specified, selected keyword values shall be written, each
- in the following format:
- .RS 4
- .sp
- .RS 4
- .nf
- "%s\en", <\fIkeyword value\fR>
- .fi
- .P
- .RE
- .P
- If the keyword was
- .BR charmap ,
- the name of the charmap (if any) that was specified via the
- .IR localedef
- .BR \-f
- option when the locale was created shall be written.
- .RE
- .IP " 5." 4
- If the
- .BR \-m
- option is specified, then a list of all available charmaps shall be
- written, each in the format:
- .RS 4
- .sp
- .RS 4
- .nf
- "%s\en", <\fIcharmap\fR>
- .fi
- .P
- .RE
- .P
- where <\fIcharmap\fP> is in a format suitable for use as the
- option-argument to the
- .IR localedef
- .BR \-f
- option.
- .RE
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- All the requested information was found and output successfully.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- If the
- .IR LANG
- environment variable is not set or set to an empty value, or one of the
- .IR 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\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables".
- .P
- Implementations are not required to write out the actual values for
- keywords in the categories
- .IR LC_CTYPE
- and
- .IR LC_COLLATE ;
- however, they must write out the categories (allowing an application to
- determine, for example, which character classes are available).
- .SH EXAMPLES
- In the following examples, the assumption is that locale environment
- variables are set as follows:
- .sp
- .RS 4
- .nf
- LANG=locale_x
- LC_COLLATE=locale_y
- .fi
- .P
- .RE
- .P
- The command
- .IR locale
- would result in the following output:
- .sp
- .RS 4
- .nf
- 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=
- .fi
- .P
- .RE
- .P
- The order of presentation of the categories is not specified by this volume of POSIX.1\(hy2017.
- .P
- The command:
- .sp
- .RS 4
- .nf
- LC_ALL=POSIX locale -ck decimal_point
- .fi
- .P
- .RE
- .P
- would produce:
- .sp
- .RS 4
- .nf
- LC_NUMERIC
- decimal_point="."
- .fi
- .P
- .RE
- .P
- The following command shows an application of
- .IR locale
- to determine whether a user-supplied response is affirmative:
- .sp
- .RS 4
- .nf
- printf \(aqPrompt for response: \(aq
- read response
- if printf "%s\en$response" | grep -- -Eq "$(locale yesexpr)"
- then
- affirmative processing goes here
- else
- non-affirmative processing goes here
- fi
- .fi
- .P
- .RE
- .SH RATIONALE
- The output for categories
- .IR LC_CTYPE
- and
- .IR 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
- .IR localedef
- source.
- .P
- The
- .BR \-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.
- .P
- The
- .BR \-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
- .BR \-k
- option.
- .P
- The
- .BR 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.
- .P
- According to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "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
- .IR locale
- .BR \-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
- .IR dd
- utility is the only portable means for performing conversions between
- the two character sets.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIlocaledef\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 6.1" ", " "Portable Character Set",
- .IR "Chapter 7" ", " "Locale",
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .\"
- .SH 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 .
- .PP
- 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 .