.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
+.\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" <jochen.hein@delphi.central.de>
.\" Modified Thu Apr 25 00:43:19 2002 by Bruno Haible <bruno@clisp.org>
.\"
-.\" FIXME Document LOCPATH;
-.\" see http://sourceware.org/bugzilla/show_bug.cgi?id=174
-.TH LOCALE 7 2014-03-07 "Linux" "Linux Programmer's Manual"
+.TH LOCALE 7 2019-03-06 "Linux" "Linux Programmer's Manual"
.SH NAME
locale \- description of multilanguage support
.SH SYNOPSIS
.BR localeconv (3)
to get information about number formatting.
.PP
-There are different categories for local information a program might
+There are different categories for locale information a program might
need; they are declared as macros.
Using them as the first argument
to the
.BR setlocale (3)
function, it is possible to set one of these to the desired locale:
.TP
+.BR LC_ADDRESS " (GNU extension, since glibc 2.2)"
+.\" See ISO/IEC Technical Report 14652
+Change settings that describe the formats (e.g., postal addresses)
+used to describe locations and geography-related items.
+Applications that need this information can use
+.BR nl_langinfo (3)
+to retrieve nonstandard elements, such as
+.B _NL_ADDRESS_COUNTRY_NAME
+(country name, in the language of the locale)
+and
+.B _NL_ADDRESS_LANG_NAME
+(language name, in the language of the locale),
+which return strings such as "Deutschland" and "Deutsch"
+(for German-language locales).
+(Other element names are listed in
+.IR <langinfo.h> .)
+.TP
.B LC_COLLATE
-This is used to change the behavior of the functions
+This category governs the collation rules used for
+sorting and regular expressions,
+including character equivalence classes and
+multicharacter collating elements.
+This locale category changes the behavior of the functions
.BR strcoll (3)
and
.BR strxfrm (3),
the German sharp s is sorted as "ss".
.TP
.B LC_CTYPE
-This changes the behavior of the character handling and
+This category determines the interpretation of byte sequences as characters
+(e.g., single versus multibyte characters), character classifications
+(e.g., alphabetic or digit), and the behavior of character classes.
+On glibc systems, this category also determines
+the character transliteration rules for
+.BR iconv (1)
+and
+.BR iconv (3).
+It changes the behavior of the character handling and
classification functions, such as
.BR isupper (3)
and
or
.BR wctomb (3).
.TP
+.BR LC_IDENTIFICATION " (GNU extension, since glibc 2.2)"
+.\" See ISO/IEC Technical Report 14652
+Change settings that relate to the metadata for the locale.
+Applications that need this information can use
+.BR nl_langinfo (3)
+to retrieve nonstandard elements, such as
+.B _NL_IDENTIFICATION_TITLE
+(title of this locale document)
+and
+.B _NL_IDENTIFICATION_TERRITORY
+(geographical territory to which this locale document applies),
+which might return strings such as "English locale for the USA"
+and "USA".
+(Other element names are listed in
+.IR <langinfo.h> .)
+.TP
.B LC_MONETARY
+This category determines the formatting used for
+monetary-related numeric values.
This changes the information returned by
-.BR localeconv (3)
+.BR localeconv (3),
which describes the way numbers are usually printed, with details such
as decimal point versus decimal comma.
This information is internally
.BR strfmon (3).
.TP
.B LC_MESSAGES
-This changes the language messages are displayed in and what an affirmative or
-negative answer looks like.
-The GNU C-library contains the
+This category affects the language in which messages are displayed
+and what an affirmative or negative answer looks like.
+The GNU C library contains the
.BR gettext (3),
.BR ngettext (3),
and
(containing a colon-separated list of locales)
if the category is set to a valid locale other than
.BR """C""" .
+This category also affects the behavior of
+.BR catopen (3).
+.TP
+.BR LC_MEASUREMENT " (GNU extension, since glibc 2.2)"
+Change the settings relating to the measurement system in the locale
+(i.e., metric versus US customary units).
+Applications can use
+.BR nl_langinfo (3)
+to retrieve the nonstandard
+.B _NL_MEASUREMENT_MEASUREMENT
+element, which returns a pointer to a character
+that has the value 1 (metric) or 2 (US customary units).
+.TP
+.BR LC_NAME " (GNU extension, since glibc 2.2)"
+.\" See ISO/IEC Technical Report 14652
+Change settings that describe the formats used to address persons.
+Applications that need this information can use
+.BR nl_langinfo (3)
+to retrieve nonstandard elements, such as
+.B _NL_NAME_NAME_MR
+(general salutation for men)
+and
+.B _NL_NAME_NAME_MS
+(general salutation for women)
+elements, which return strings such as "Herr" and "Frau"
+(for German-language locales).
+(Other element names are listed in
+.IR <langinfo.h> .)
.TP
.B LC_NUMERIC
-This changes the information used by the
-.BR printf (3)
+This category determines the formatting rules used for nonmonetary
+numeric values\(emfor example,
+the thousands separator and the radix character
+(a period in most English-speaking countries,
+but a comma in many other regions).
+It affects functions such as
+.BR printf (3),
+.BR scanf (3),
and
-.BR scanf (3)
-family of functions, when they are advised to use the locale settings.
+.BR strtod (3).
This information can also be read with the
.BR localeconv (3)
function.
.TP
+.BR LC_PAPER " (GNU extension, since glibc 2.2)"
+.\" See ISO/IEC Technical Report 14652
+Change the settings relating to the dimensions of the standard paper size
+(e.g., US letter versus A4).
+Applications that need the dimensions can obtain them by using
+.BR nl_langinfo (3)
+to retrieve the nonstandard
+.B _NL_PAPER_WIDTH
+and
+.B _NL_PAPER_HEIGHT
+elements, which return
+.I int
+values specifying the dimensions in millimeters.
+.TP
+.BR LC_TELEPHONE " (GNU extension, since glibc 2.2)"
+.\" See ISO/IEC Technical Report 14652
+Change settings that describe the formats to be used with telephone services.
+Applications that need this information can use
+.BR nl_langinfo (3)
+to retrieve nonstandard elements, such as
+.B _NL_TELEPHONE_INT_PREFIX
+(international prefix used to call numbers in this locale),
+which returns a string such as "49" (for Germany).
+(Other element names are listed in
+.IR <langinfo.h> .)
+.TP
.B LC_TIME
-This changes the behavior of the
-.BR strftime (3)
-function to display the current time in a locally acceptable form; for
-example, most of Europe uses a 24-hour clock versus the
+This category governs the formatting used for date and time values.
+For example, most of Europe uses a 24-hour clock versus the
12-hour clock used in the United States.
+The setting of this category affects the behavior of functions such as
+.BR strftime (3)
+and
+.BR strptime (3).
.TP
.B LC_ALL
All of the above.
-.\" FIXME glibc 2.2.2 added new nonstandard locale categories:
-.\" LC_ADDRESS, LC_IDENTIFICATION, LC_MEASUREMENT, LC_NAME,
-.\" LC_PAPER, LC_TELEPHONE. These need to be documented.
.PP
If the second argument to
.BR setlocale (3)
is an empty string,
-.BR """""" ,
+.IR """""" ,
for the default locale, it is determined using the following steps:
-.IP 1.
+.IP 1. 3
If there is a non-null environment variable
.BR LC_ALL ,
the value of
returned by the
.BR localeconv (3)
function, which has the following declaration:
-.in +2n
-.nf
-
+.PP
+.in +4n
+.EX
struct lconv {
/* Numeric (nonmonetary) information */
char *decimal_point; /* Radix character */
char *thousands_sep; /* Separator for digit groups to left
of radix character */
- char *grouping; /* Each element is the number of digits in a
- group; elements with higher indices are
- further left. An element with value CHAR_MAX
- means that no further grouping is done. An
- element with value 0 means that the previous
- element is used for all groups further left. */
+ char *grouping; /* Each element is the number of digits in
+ a group; elements with higher indices
+ are further left. An element with value
+ CHAR_MAX means that no further grouping
+ is done. An element with value 0 means
+ that the previous element is used for
+ all groups further left. */
/* Remaining fields are for monetary information */
- char *int_curr_symbol; /* First three chars are a currency symbol
- from ISO 4217. Fourth char is the
- separator. Fifth char is \(aq\\0\(aq. */
+ char *int_curr_symbol; /* First three chars are a currency
+ symbol from ISO 4217. Fourth char
+ is the separator. Fifth char
+ is \(aq\e0\(aq. */
char *currency_symbol; /* Local currency symbol */
char *mon_decimal_point; /* Radix character */
char *mon_thousands_sep; /* Like \fIthousands_sep\fP above */
char frac_digits; /* Local fractional digits */
char p_cs_precedes; /* 1 if currency_symbol precedes a
positive value, 0 if succeeds */
- char p_sep_by_space; /* 1 if a space separates currency_symbol
- from a positive value */
+ char p_sep_by_space; /* 1 if a space separates
+ currency_symbol from a positive
+ value */
char n_cs_precedes; /* 1 if currency_symbol precedes a
negative value, 0 if succeeds */
- char n_sep_by_space; /* 1 if a space separates currency_symbol
- from a negative value */
+ char n_sep_by_space; /* 1 if a space separates
+ currency_symbol from a negative
+ value */
/* Positive and negative sign positions:
0 Parentheses surround the quantity and currency_symbol.
1 The sign string precedes the quantity and currency_symbol.
char p_sign_posn;
char n_sign_posn;
};
-.fi
+.EE
.in
.SS POSIX.1-2008 extensions to the locale API
POSIX.1-2008 standardized a number of extensions to the locale API,
based on implementations that first appeared in version 2.3
of the GNU C library.
-These extensions are designed to address the problem that
+These extensions are designed to address the problem that
the traditional locale APIs do not mix well with multithreaded applications
and with applications that must deal with multiple locales.
-
+.PP
The extensions take the form of new functions for creating and
manipulating locale objects
.RB ( newlocale (3),
.BR toupper (3))
to allow the specification of a locale object that should apply when
executing the function.
+.SH ENVIRONMENT
+The following environment variable is used by
+.BR newlocale (3)
+and
+.BR setlocale (3),
+and thus affects all unprivileged localized programs:
+.TP
+.B LOCPATH
+A list of pathnames, separated by colons (\(aq:\(aq),
+that should be used to find locale data.
+If this variable is set,
+only the individual compiled locale data files from
+.I LOCPATH
+and the system default locale data path are used;
+any available locale archives are not used (see
+.BR localedef (1)).
+The individual compiled locale data files are searched for under
+subdirectories which depend on the currently used locale.
+For example, when
+.I en_GB.UTF-8
+is used for a category, the following subdirectories are searched for,
+in this order:
+.IR en_GB.UTF-8 ,
+.IR en_GB.utf8 ,
+.IR en_GB ,
+.IR en.UTF-8 ,
+.IR en.utf8 ,
+and
+.IR en .
+.SH FILES
+.TP
+.I /usr/lib/locale/locale-archive
+Usual default locale archive location.
+.TP
+.I /usr/lib/locale
+Usual default path for compiled individual locale files.
.SH CONFORMING TO
POSIX.1-2001.
-.\"
+.\"
.\" The GNU gettext functions are specified in LI18NUX2000.
.SH SEE ALSO
+.BR iconv (1),
.BR locale (1),
.BR localedef (1),
.BR catopen (3),
.BR gettext (3),
+.BR iconv (3),
.BR localeconv (3),
+.BR mbstowcs (3),
.BR newlocale (3),
.BR ngettext (3),
.BR nl_langinfo (3),
.BR strftime (3),
.BR strxfrm (3),
.BR uselocale (3),
-.BR locale (5)
+.BR wcstombs (3),
+.BR locale (5),
+.BR charsets (7),
+.BR unicode (7),
+.BR utf-8 (7)
projects / thirdparty / man-pages.git / blobdiff