2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "LOCALE" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" locale
|
2007-09-20 06:03:25 +00:00
|
|
|
.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.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
locale \- get locale-specific information
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fBlocale\fP \fB[\fP\fB-a| -m\fP\fB]\fP\fB
|
|
|
|
.br
|
|
|
|
.sp
|
|
|
|
locale\fP \fB[\fP\fB-ck\fP\fB]\fP \fIname\fP\fB...
|
|
|
|
.br
|
|
|
|
\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fIlocale\fP utility shall write information about the current
|
|
|
|
locale environment, or all public locales, to the standard
|
|
|
|
output. For the purposes of this section, a \fIpublic locale\fP is
|
|
|
|
one provided by the implementation that is accessible to the
|
|
|
|
application.
|
|
|
|
.LP
|
|
|
|
When \fIlocale\fP 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.
|
|
|
|
.LP
|
|
|
|
When invoked with operands, it shall write values that have been assigned
|
|
|
|
to the keywords in the locale categories, as
|
|
|
|
follows:
|
|
|
|
.IP " *" 3
|
|
|
|
Specifying a keyword name shall select the named keyword and the category
|
|
|
|
containing that keyword.
|
|
|
|
.LP
|
|
|
|
.IP " *" 3
|
|
|
|
Specifying a category name shall select the named category and all
|
|
|
|
keywords in that category.
|
|
|
|
.LP
|
|
|
|
.SH OPTIONS
|
|
|
|
.LP
|
|
|
|
The \fIlocale\fP utility shall conform to the Base Definitions volume
|
|
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
|
|
.LP
|
|
|
|
The following options shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fB-a\fP
|
|
|
|
Write information about all available public locales. The available
|
|
|
|
locales shall include \fBPOSIX\fP, representing the POSIX
|
|
|
|
locale. The manner in which the implementation determines what other
|
|
|
|
locales are available is implementation-defined.
|
|
|
|
.TP 7
|
|
|
|
\fB-c\fP
|
|
|
|
Write the names of selected locale categories; see the STDOUT section.
|
|
|
|
The \fB-c\fP 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 \fB-k\fP option.
|
|
|
|
.TP 7
|
|
|
|
\fB-k\fP
|
|
|
|
Write the names and values of selected keywords. The implementation
|
|
|
|
may omit values for some keywords; see the OPERANDS
|
|
|
|
section.
|
|
|
|
.TP 7
|
|
|
|
\fB-m\fP
|
|
|
|
Write names of available charmaps; see the Base Definitions volume
|
|
|
|
of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character Set.
|
|
|
|
.sp
|
|
|
|
.SH OPERANDS
|
|
|
|
.LP
|
|
|
|
The following operand shall be supported:
|
|
|
|
.TP 7
|
|
|
|
\fIname\fP
|
|
|
|
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
|
|
|
|
\fBcharmap\fP. The named category or keyword shall be selected for
|
|
|
|
output. If a single \fIname\fP 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 \fIname\fP operands, in any sequence. It is implementation-defined
|
|
|
|
whether any keyword values are written for the
|
2007-09-20 06:41:41 +00:00
|
|
|
categories \fILC_CTYPE\fP and \fILC_COLLATE\fP.
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
|
|
|
.SH STDIN
|
|
|
|
.LP
|
|
|
|
Not used.
|
|
|
|
.SH INPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH ENVIRONMENT VARIABLES
|
|
|
|
.LP
|
|
|
|
The following environment variables shall affect the execution of
|
|
|
|
\fIlocale\fP:
|
|
|
|
.TP 7
|
|
|
|
\fILANG\fP
|
|
|
|
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 precedence of internationalization variables used to determine
|
|
|
|
the values of locale categories.)
|
|
|
|
.TP 7
|
|
|
|
\fILC_ALL\fP
|
|
|
|
If set to a non-empty string value, override the values of all the
|
|
|
|
other internationalization variables.
|
|
|
|
.TP 7
|
|
|
|
\fILC_CTYPE\fP
|
|
|
|
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).
|
|
|
|
.TP 7
|
|
|
|
\fILC_MESSAGES\fP
|
|
|
|
Determine the locale that should be used to affect the format and
|
|
|
|
contents of diagnostic messages written to standard
|
|
|
|
error.
|
|
|
|
.TP 7
|
|
|
|
\fINLSPATH\fP
|
|
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
|
|
\&.\fP
|
|
|
|
.sp
|
|
|
|
.LP
|
2007-09-20 06:41:41 +00:00
|
|
|
The application shall ensure that the \fILANG\fP, \fILC_*\fP, and
|
2007-11-18 06:52:48 +00:00
|
|
|
\fINLSPATH\fP environment variables specify the current locale
|
2004-11-03 13:51:07 +00:00
|
|
|
environment to be written out; they shall be used
|
|
|
|
if the \fB-a\fP option is not specified.
|
|
|
|
.SH ASYNCHRONOUS EVENTS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.SH STDOUT
|
|
|
|
.LP
|
|
|
|
If \fIlocale\fP is invoked without any options or operands, the names
|
|
|
|
and values of the \fILANG\fP and \fILC_*\fP environment
|
|
|
|
variables described in this volume of IEEE\ Std\ 1003.1-2001 shall
|
|
|
|
be written to the standard output, one variable per
|
|
|
|
line, with \fILANG\fP first, and each line using the following format.
|
|
|
|
Only those variables set in the environment and not
|
|
|
|
overridden by \fILC_ALL\fP shall be written using this format:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB"%s=%s\\n", <\fP\fIvariable_name\fP\fB>, <\fP\fIvalue\fP\fB>
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The names of those \fILC_*\fP 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 \fILC_ALL\fP shall be written in the
|
|
|
|
following format:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB"%s=\\"%s\\"\\n", <\fP\fIvariable_name\fP\fB>, <\fP\fIimplied value\fP\fB>
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The <\fIimplied\ value\fP> shall be the name of the locale that has
|
|
|
|
been selected for that category by the
|
2007-09-20 06:41:41 +00:00
|
|
|
implementation, based on the values in \fILANG\fP and \fILC_ALL\fP,
|
2004-11-03 13:51:07 +00:00
|
|
|
as described in the Base Definitions volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables.
|
|
|
|
.LP
|
|
|
|
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).
|
|
|
|
.LP
|
|
|
|
The \fILC_ALL\fP variable shall be written last, using the first format
|
|
|
|
shown above. If it is not set, it shall be written
|
|
|
|
as:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB"LC_ALL=\\n"
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
If any arguments are specified:
|
|
|
|
.IP " 1." 4
|
|
|
|
If the \fB-a\fP option is specified, the names of all the public locales
|
|
|
|
shall be written, each in the following format:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB"%s\\n", <\fP\fIlocale name\fP\fB>
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
.IP " 2." 4
|
|
|
|
If the \fB-c\fP option is specified, the names of all selected categories
|
|
|
|
shall be written, each in the following format:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB"%s\\n", <\fP\fIcategory name\fP\fB>
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
If keywords are also selected for writing (see following items), the
|
|
|
|
category name output shall precede the keyword output for
|
|
|
|
that category.
|
|
|
|
.LP
|
|
|
|
If the \fB-c\fP 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.
|
|
|
|
.LP
|
|
|
|
.IP " 3." 4
|
|
|
|
If the \fB-k\fP 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:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB"%s=\\"%s\\"\\n", <\fP\fIkeyword name\fP\fB>, <\fP\fIkeyword value\fP\fB>
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
If the keyword was \fBcharmap\fP, the name of the charmap (if any)
|
|
|
|
that was specified via the \fIlocaledef\fP \fB-f\fP option when the
|
|
|
|
locale was created shall be written, with the word
|
|
|
|
\fBcharmap\fP as <\fIkeyword\ name\fP>.
|
|
|
|
.LP
|
|
|
|
If a value is numeric, it shall be written in one of the following
|
|
|
|
formats:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB"%s=%d\\n", <\fP\fIkeyword name\fP\fB>, <\fP\fIkeyword value\fP\fB>
|
|
|
|
.sp
|
|
|
|
|
|
|
|
"%s=%c%o\\n", <\fP\fIkeyword name\fP\fB>, <\fP\fIescape character\fP\fB>, <\fP\fIkeyword value\fP\fB>
|
|
|
|
.sp
|
|
|
|
|
|
|
|
"%s=%cx%x\\n", <\fP\fIkeyword name\fP\fB>, <\fP\fIescape character\fP\fB>, <\fP\fIkeyword value\fP\fB>
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
where the <\fIescape\ character\fP> is that identified by the \fBescape_char\fP
|
|
|
|
keyword in the current locale; see
|
|
|
|
the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 7.3,
|
|
|
|
Locale
|
|
|
|
Definition.
|
|
|
|
.LP
|
|
|
|
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.
|
|
|
|
.LP
|
|
|
|
.IP " 4." 4
|
|
|
|
If the \fB-k\fP option is not specified, selected keyword values shall
|
|
|
|
be written, each in the following format:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB"%s\\n", <\fP\fIkeyword value\fP\fB>
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
If the keyword was \fBcharmap\fP, the name of the charmap (if any)
|
|
|
|
that was specified via the \fIlocaledef\fP \fB-f\fP option when the
|
|
|
|
locale was created shall be written.
|
|
|
|
.LP
|
|
|
|
.IP " 5." 4
|
|
|
|
If the \fB-m\fP option is specified, then a list of all available
|
|
|
|
charmaps shall be written, each in the format:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fB"%s\\n", <\fP\fIcharmap\fP\fB>
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
where <\fIcharmap\fP> is in a format suitable for use as the option-argument
|
|
|
|
to the \fIlocaledef\fP \fB-f\fP option.
|
|
|
|
.LP
|
|
|
|
.SH STDERR
|
|
|
|
.LP
|
|
|
|
The standard error shall be used only for diagnostic messages.
|
|
|
|
.SH OUTPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXTENDED DESCRIPTION
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXIT STATUS
|
|
|
|
.LP
|
|
|
|
The following exit values shall be returned:
|
|
|
|
.TP 7
|
|
|
|
\ 0
|
|
|
|
All the requested information was found and output successfully.
|
|
|
|
.TP 7
|
|
|
|
>0
|
|
|
|
An error occurred.
|
|
|
|
.sp
|
|
|
|
.SH CONSEQUENCES OF ERRORS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
If the \fILANG\fP environment variable is not set or set to an empty
|
|
|
|
value, or one of the \fILC_*\fP 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.
|
|
|
|
.LP
|
|
|
|
Implementations are not required to write out the actual values for
|
|
|
|
keywords in the categories \fILC_CTYPE\fP and \fILC_COLLATE
|
|
|
|
;\fP however, they must write out the categories (allowing an application
|
|
|
|
to determine, for example, which character classes are
|
|
|
|
available).
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
In the following examples, the assumption is that locale environment
|
|
|
|
variables are set as follows:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBLANG=locale_x
|
|
|
|
LC_COLLATE=locale_y
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The command \fIlocale\fP would result in the following output:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBLANG=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=
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The order of presentation of the categories is not specified by this
|
|
|
|
volume of IEEE\ Std\ 1003.1-2001.
|
|
|
|
.LP
|
|
|
|
The command:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBLC_ALL=POSIX locale -ck decimal_point
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
would produce:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBLC_NUMERIC
|
|
|
|
decimal_point="."
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The following command shows an application of \fIlocale\fP to determine
|
|
|
|
whether a user-supplied response is affirmative:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBif printf "%s\\n" "$response" | grep -Eq "$(locale yesexpr)"
|
|
|
|
then
|
|
|
|
affirmative processing goes here
|
|
|
|
else
|
|
|
|
non-affirmative processing goes here
|
|
|
|
fi
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
The output for categories \fILC_CTYPE\fP and \fILC_COLLATE\fP 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 \fIlocaledef\fP
|
|
|
|
source.
|
|
|
|
.LP
|
|
|
|
The \fB-m\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-c\fP 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 \fB-k\fP option.
|
|
|
|
.LP
|
|
|
|
The \fBcharmap\fP 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.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
2007-09-20 06:36:16 +00:00
|
|
|
\fIlocaledef\fP, the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
2004-11-03 13:51:07 +00:00
|
|
|
Section 7.3, Locale Definition
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications 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 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 .
|