path: root/man1p/locale.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "LOCALE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" locale 
.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
categories \fILC_CTYPE\fP and \fILC_COLLATE .\fP
.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
The application shall ensure that the \fILANG ,\fP \fILC_* ,\fP and
\fINLSPATH\fP  \ environment variables specify the current locale
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
implementation, based on the values in \fILANG\fP and \fILC_ALL ,\fP
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
\fIlocaledef\fP , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
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 .