diff options
Diffstat (limited to 'man-pages-posix-2003/man1p/locale.1p')
| -rw-r--r-- | man-pages-posix-2003/man1p/locale.1p | 446 |
1 files changed, 446 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man1p/locale.1p b/man-pages-posix-2003/man1p/locale.1p new file mode 100644 index 0000000..91016cd --- /dev/null +++ b/man-pages-posix-2003/man1p/locale.1p @@ -0,0 +1,446 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LOCALE" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" locale +.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 \- 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 . |