LOCALE(5) | Standards, Environments, and Macros | LOCALE(5) |
LC_CTYPE
LC_COLLATE
LC_TIME
LC_NUMERIC
LC_MONETARY
LC_MESSAGES
The standard utilities base their behavior on the current locale, as defined in the ENVIRONMENT VARIABLES section for each utility. The behavior of some of the C-language functions will also be modified based on the current locale, as defined by the last call to setlocale(3C).
Locales other than those supplied by the implementation can be created by the application via the localedef(1) utility. The value that is used to specify a locale when using environment variables will be the string specified as the name operand to localedef when the locale was created. The strings "C" and "POSIX" are reserved as identifiers for the POSIX locale.
Applications can select the desired locale by invoking the setlocale() function with the appropriate value. If the function is invoked with an empty string, such as:
setlocale(LC_ALL, "");
the value of the corresponding environment variable is used. If the environment variable is unset or is set to the empty string, the setlocale() function sets the appropriate environment.
The locale definition file must contain one or more locale category source definitions, and must not contain more than one definition for the same locale category.
A category source definition consists of a category header, a category body and a category trailer. A category header consists of the character string naming of the category, beginning with the characters LC_. The category trailer consists of the string END, followed by one or more blank characters and the string used in the corresponding category header.
The category body consists of one or more lines of text. Each line contains an identifier, optionally followed by one or more operands. Identifiers are either keywords, identifying a particular locale element, or collating elements. Each keyword within a locale must have a unique name (that is, two categories cannot have a commonly-named keyword). No keyword can start with the characters LC_. Identifiers must be separated from the operands by one or more blank characters.
Operands must be characters, collating elements, or strings of characters. Strings must be enclosed in double-quotes ("). Literal double-quotes within strings must be preceded by the <escape character>, as described below. When a keyword is followed by more than one operand, the operands must be separated by semicolons (;). Blank characters are allowed both before and after a semicolon.
The first category header in the file can be preceded by a line modifying the comment character. It has the following format, starting in column 1:
"comment_char %c\n",<comment character>
The comment character defaults to the number sign (#). Blank lines and lines containing the <comment character> in the first position are ignored.
The first category header in the file can be preceded by a line modifying the escape character to be used in the file. It has the following format, starting in column 1:
"escape_char %c\n",<escape character>
The escape character defaults to backslash.
A line can be continued by placing an escape character as the last character on the line; this continuation character will be discarded from the input. Although the implementation need not accept any one portion of a continued line with a length exceeding {LINE_MAX} bytes, it places no limits on the accumulated length of the continued line. Comment lines cannot be continued on a subsequent line using an escaped newline character.
Individual characters, characters in strings, and collating elements must be represented using symbolic names, as defined below. In addition, characters can be represented using the characters themselves or as octal, hexadecimal or decimal constants. When non-symbolic notation is used, the resultant locale definitions will in many cases not be portable between systems. The left angle bracket (<) is a reserved symbol, denoting the start of a symbolic name; when used to represent itself it must be preceded by the escape character. The following rules apply to character representation:
Example:
<C>;<c-cedilla> "<M><a><y>"
, ; < > escape_char
must be escaped to be interpreted as the character itself.
Example:
c "May"
Example:
\143;\347;\143\150 "\115\141\171"
Example:
\x63;\xe7;\x63\x68 "\x4d\x61\x79"
Example:
\d99;\d231;\d99\d104 "\d77\d97\d121"
Only characters existing in the character set for which the locale definition is created can be specified, whether using symbolic names, the characters themselves, or octal, decimal or hexadecimal constants. If a charmap file is present, only characters defined in the charmap can be specified using octal, decimal or hexadecimal constants. Symbolic names not present in the charmap file can be specified and will be ignored, as specified under item 1 above.
Example:
\x30;...;\x39;
includes in the character class all characters with encoded values between the endpoints.
The following keywords are recognized. In the descriptions, the term ``automatically included'' means that it is not an error either to include or omit any of the referenced characters.
The character classes digit, xdigit, lower, upper, and space have a set of automatically included characters. These only need to be specified if the character values (that is, encoding) differ from the implementation default values.
upper
In the POSIX locale, the 26 upper-case letters are included:
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
In a locale definition file, no character specified for the keywords cntrl, digit, punct, or space can be specified. The upper-case letters A to Z are automatically included in this class.
lower
a b c d e f g h i j k l m n o p q r s t u v w x y z
In a locale definition file, no character specified for the keywords cntrl, digit, punct, or space can be specified. The lower-case letters a to z of the portable character set are automatically included in this class.
alpha
In the POSIX locale, all characters in the classes upper and lower are included.
In a locale definition file, no character specified for the keywords cntrl, digit, punct, or space can be specified. Characters classified as either upper or lower are automatically included in this class.
digit
In the POSIX locale, only
0 1 2 3 4 5 6 7 8 9
are included.
In a locale definition file, only the digits 0, 1, 2, 3, 4, 5, 6, 7, 8, and 9 can be specified, and in contiguous ascending sequence by numerical value. The digits 0 to 9 of the portable character set are automatically included in this class.
The definition of character class digit requires that only ten characters; the ones defining digits can be specified; alternative digits (for example, Hindi or Kanji) cannot be specified here.
alnum
space
In the POSIX locale, at a minimum, the characters SPACE, FORMFEED, NEWLINE, CARRIAGE RETURN, TAB, and VERTICAL TAB are included.
In a locale definition file, no character specified for the keywords upper, lower, alpha, digit, graph, or xdigit can be specified. The characters SPACE, FORMFEED, NEWLINE, CARRIAGE RETURN, TAB, and VERTICAL TAB of the portable character set, and any characters included in the class blank are automatically included in this class.
cntrl
In the POSIX locale, no characters in classes alpha or print are included.
In a locale definition file, no character specified for the keywords upper, lower, alpha, digit, punct, graph, print, or xdigit can be specified.
punct
In the POSIX locale, neither the space character nor any characters in classes alpha, digit, or cntrl are included.
In a locale definition file, no character specified for the keywords upper, lower, alpha, digit, cntrl, xdigit or as the space character can be specified.
graph
In the POSIX locale, all characters in classes alpha, digit, and punct are included; no characters in class cntrl are included.
In a locale definition file, characters specified for the keywords upper, lower, alpha, digit, xdigit, and punct are automatically included in this class. No character specified for the keyword cntrl can be specified.
In the POSIX locale, all characters in class graph are included; no characters in class cntrl are included.
In a locale definition file, characters specified for the keywords upper, lower, alpha, digit, xdigit, punct, and the space character are automatically included in this class. No character specified for the keyword cntrl can be specified.
xdigit
In the POSIX locale, only:
0 1 2 3 4 5 6 7 8 9 A B C D E F a b c d e f
are included.
In a locale definition file, only the characters defined for the class digit can be specified, in contiguous ascending sequence by numerical value, followed by one or more sets of six characters representing the hexadecimal digits 10 to 15 inclusive, with each set in ascending order (for example A, B, C, D, E, F, a, b, c, d, e, f). The digits 0 to 9, the upper-case letters A to F and the lower-case letters a to f of the portable character set are automatically included in this class.
The definition of character class xdigit requires that the characters included in character class digit be included here also.
blank
In the POSIX locale, only the space and tab characters are included.
In a locale definition file, the characters space and tab are automatically included in this class.
charclass
charclass-name
toupper
In the POSIX locale, at a minimum, the 26 lower-case characters:
a b c d e f g h i j k l m n o p q r s t u v w x y z
are mapped to the corresponding 26 upper-case characters:
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
In a locale definition file, the operand consists of character pairs, separated by semicolons. The characters in each character pair are separated by a comma and the pair enclosed by parentheses. The first character in each pair is the lower-case letter, the second the corresponding upper-case letter. Only characters specified for the keywords lower and upper can be specified. The lower-case letters a to z, and their corresponding upper-case letters A to Z, of the portable character set are automatically included in this mapping, but only when the toupper keyword is omitted from the locale definition.
tolower
In the POSIX locale, at a minimum, the 26 upper-case characters:
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
are mapped to the corresponding 26 lower-case characters:
a b c d e f g h i j k l m n o p q r s t u v w x y z
In a locale definition file, the operand consists of character pairs, separated by semicolons. The characters in each character pair are separated by a comma and the pair enclosed by parentheses. The first character in each pair is the upper-case letter, the second the corresponding lower-case letter. Only characters specified for the keywords lower and upper can be specified. If the tolower keyword is omitted from the locale definition, the mapping will be the reverse mapping of the one specified for toupper.
A collation sequence definition defines the relative order between collating elements (characters and multi-character collating elements) in the locale. This order is expressed in terms of collation values, that is, by assigning each element one or more collation values (also known as collation weights). The following capabilities are provided:
The following keywords are recognized in a collation sequence definition. They are described in detail in the following sections.
copy
collating-element
collating-symbol
order_start
order_end
"collating-element %s from \"%s\"\n",<collating-symbol>,<string>
The <collating-symbol> operand is a symbolic name, enclosed between angle brackets (< and >), and must not duplicate any symbolic name in the current charmap file (if any), or any other symbolic name defined in this collation definition. The string operand is a string of two or more characters that collates as an entity. A <collating-element> defined via this keyword is only recognized with the LC_COLLATE category.
Example:
collating-element <ch> from
"<c><h>"
collating-element <e-acute> from
"<acute><e>"
collating-element <ll> from "ll"
"collating-symbol %s\n",<collating-symbol>
The <collating-symbol> is a symbolic name, enclosed between angle brackets (< and >), and must not duplicate any symbolic name in the current charmap file (if any), or any other symbolic name defined in this collation definition.
A collating-symbol defined via this keyword is only recognized with the LC_COLLATE category.
Example:
collating-symbol <UPPER_CASE>
collating-symbol <HIGH>
The collating-symbol keyword defines a symbolic name that can be associated with a relative position in the character order sequence. While such a symbolic name does not represent any collating element, it can be used as a weight.
The syntax of the order_start keyword is:
"order_start %s;%s;...;%s\n",<sort-rules>,<sort-rules>
The operands to the order_start keyword are optional. If present, the operands define rules to be applied when strings are compared. The number of operands define how many weights each element is assigned. If no operands are present, one forward operand is assumed. If present, the first operand defines rules to be applied when comparing strings using the first (primary) weight; the second when comparing strings using the second weight, and so on. Operands are separated by semicolons (;). Each operand consists of one or more collation directives, separated by commas (,). If the number of operands exceeds the {COLL_WEIGHTS_MAX} limit, the utility will issue a warning message. The following directives will be supported:
forward
backward
position
The directives forward and backward are mutually exclusive.
Example:
order_start forward;backward
If no operands are specified, a single forward operand is assumed.
"%s %s;%s;...;%s\n"<collating-identifier>,<weight>,<weight>,...
Each collating-identifier consists of either a character described in Locale Definition above, a <collating-element>, a <collating-symbol>, an ellipsis, or the special symbol UNDEFINED. The order in which collating elements are specified determines the character order sequence, such that each collating element compares less than the elements following it. The NUL character compares lower than any other character.
A <collating-element> is used to specify multi-character collating elements, and indicates that the character sequence specified via the <collating-element> is to be collated as a unit and in the relative order specified by its place.
A <collating-symbol> is used to define a position in the relative order for use in weights. No weights are specified with a <collating-symbol>.
The ellipsis symbol specifies that a sequence of characters will collate according to their encoded character values. It is interpreted as indicating that all characters with a coded character set value higher than the value of the character in the preceding line, and lower than the coded character set value for the character in the following line, in the current coded character set, will be placed in the character collation order between the previous and the following character in ascending order according to their coded character set values. An initial ellipsis is interpreted as if the preceding line specified the NUL character, and a trailing ellipsis as if the following line specified the highest coded character set value in the current coded character set. An ellipsis is treated as invalid if the preceding or following lines do not specify characters in the current coded character set. The use of the ellipsis symbol ties the definition to a specific coded character set and may preclude the definition from being portable between implementations.
The symbol UNDEFINED is interpreted as including all coded character set values not specified explicitly or via the ellipsis symbol. Such characters are inserted in the character collation order at the point indicated by the symbol, and in ascending order according to their coded character set values. If no UNDEFINED symbol is specified, and the current coded character set contains characters not specified in this section, the utility will issue a warning message and place such characters at the end of the character collation order.
The optional operands for each collation-element are used to define the primary, secondary, or subsequent weights for the collating element. The first operand specifies the relative primary weight, the second the relative secondary weight, and so on. Two or more collation-elements can be assigned the same weight; they belong to the same equivalence class if they have the same primary weight. Collation behaves as if, for each weight level, elements subject to IGNORE are removed, unless the position collation directive is specified for the corresponding level with the order_start keyword. Then each successive pair of elements is compared according to the relative weights for the elements. If the two strings compare equal, the process is repeated for the next weight level, up to the limit {COLL_WEIGHTS_MAX}.
Weights are expressed as characters described in Locale Definition above, <collating-symbol>s, <collating-element>s, an ellipsis, or the special symbol IGNORE. A single character, a <collating-symbol> or a <collating-element> represent the relative position in the character collating sequence of the character or symbol, rather than the character or characters themselves. Thus, rather than assigning absolute values to weights, a particular weight is expressed using the relative order value assigned to a collating element based on its order in the character collation sequence.
One-to-many mapping is indicated by specifying two or more concatenated characters or symbolic names. For example, if the character <eszet> is given the string "<s><s>" as a weight, comparisons are performed as if all occurrences of the character <eszet> are replaced by <s><s> (assuming that <s> has the collating weight <s>). If it is necessary to define <eszet> and <s><s> as an equivalence class, then a collating element must be defined for the string ss.
All characters specified via an ellipsis will by default be assigned unique weights, equal to the relative order of characters. Characters specified via an explicit or implicit UNDEFINED special symbol will by default be assigned the same primary weight (that is, belong to the same equivalence class). An ellipsis symbol as a weight is interpreted to mean that each character in the sequence has unique weights, equal to the relative order of their character in the character collation sequence. The use of the ellipsis as a weight is treated as an error if the collating element is neither an ellipsis nor the special symbol UNDEFINED.
The special keyword IGNORE as a weight indicates that when strings are compared using the weights at the level where IGNORE is specified, the collating element is ignored; that is, as if the string did not contain the collating element. In regular expressions and pattern matching, all characters that are subject to IGNORE in their primary weight form an equivalence class.
An empty operand is interpreted as the collating element itself.
For example, the order statement:
<a> <a>;<a>
is equal to:
<a>
An ellipsis can be used as an operand if the collating element was an ellipsis, and is interpreted as the value of each character defined by the ellipsis.
The collation order as defined in this section defines the interpretation of bracket expressions in regular expressions.
Example:
order_start | forward;backward |
UNDEFINED | IGNORE;IGNORE |
<LOW> | |
<space> | <LOW>;<space> |
... | <LOW>;... |
<a> | <a>;<a> |
<a-acute> | <a>;<a-acute> |
<a-grave> | <a>;<a-grave> |
<A> | <a>;<A> |
<A-acute> | <a>;<A-acute> |
<A-grave> | <a>;<A-grave> |
<ch> | <ch>;<ch> |
<Ch> | <ch>;<Ch> |
<s> | <s>;<s> |
<eszet> | "<s><s>";"<eszet><eszet>" |
order_end |
This example is interpreted as follows:
The following items are defined in this category of the locale. The item names are the keywords recognized by the localedef(1) utility when defining a locale. They are also similar to the member names of the lconv structure defined in <locale.h>. The localeconv function returns {CHAR_MAX} for unspecified integer items and the empty string ("") for unspecified or size zero string items.
In a locale definition file the operands are strings. For some keywords, the strings can contain only integers. Keywords that are not provided, string values set to the empty string (""), or integer keywords set to -1, are used to indicate that the value is not available in the locale.
int_curr_symbol
currency_symbol
mon_decimal_point
mon_thousands_sep
mon_grouping
The following is an example of the interpretation of the mon_grouping keyword. Assuming that the value to be formatted is 123456789 and the mon_thousands_sep is ', then the following table shows the result. The third column shows the equivalent string in the ISO C standard that would be used by the localeconv function to accommodate this grouping.
mon_grouping Formatted Value ISO C String 3;-1 123456'789 "\3\177" 3 123'456'789 "\3" 3;2;-1 1234'56'789 "\3\2\177" 3;2 12'34'56'789 "\3\2" -1 1234567898 "\177"
In these examples, the octal value of {CHAR_MAX} is 177.
positive_sign
negative_sign
int_frac_digits
frac_digits
p_cs_precedes
In an application not conforming to the SUSv3 standard, an integer set to 1 if the currency_symbol or int_currency_symbol precedes the value for a monetary quantity with a non-negative value, and set to 0 if the symbol succeeds the value.
p_sep_by_space
In an application not conforming to the SUSv3 standard, an integer set to 0 if no space separates the currency_symbol or int_curr_symbol from the value for a monetary quantity with a non-negative value, set to 1 if a space separates the symbol from the value, and set to 2 if a space separates the symbol and the sign string, if adjacent.
n_cs_precedes
In an application not conforming to the SUSv3 standard, an integer set to 1 if the currency_symbol or int_currency_symbol precedes the value for a monetary quantity with a negative value, and set to 0 if the symbol succeeds the value.
n_sep_by_space
In an application not conforming to the SUSv3 standard, an integer set to 0 if no space separates the currency_symbol or int_curr_symbol from the value for a monetary quantity with a negative value, set to 1 if a space separates the symbol from the value, and set to 2 if a space separates the symbol and the sign string, if adjacent.
p_sign_posn
In an application conforming to the SUSv3 standard:
0
1
2
3
4
In an application not conforming to the SUSv3 standard:
0
1
2
3
4
n_sign_posn
int_p_cs_precedes
int_n_cs_precedes
int_p_sep_by_space
int_n_sep_by_space
int_p_sign_posn
0
1
2
3
4
int_n_sign_posn
The following table shows the result of various combinations:
p_sep_by_space | ||||
2 | 1 | 0 | ||
p_cs_precedes= 1 | p_sign_posn= 0 | ($1.25) | ($1.25) | ($1.25) |
p_sign_posn= 1 | +$1.25 | +$1.25 | +$1.25 | |
p_sign_posn= 2 | $1.25+ | $1.25+ | $1.25+ | |
p_sign_posn= 3 | +$1.25 | +$1.25 | +$1.25 | |
p_sign_posn= 4 | $+1.25 | $+1.25 | $+1.25 | |
p_cs_precedes= 0 | p_sign_posn= 0 | (1.25 $) | (1.25 $) | (1.25$) |
p_sign_posn= 1 | +1.25 $ | +1.25 $ | +1.25$ | |
p_sign_posn= 2 | 1.25$ + | 1.25 $+ | 1.25$+ | |
p_sign_posn= 3 | 1.25+ $ | 1.25 +$ | 1.25+$ | |
p_sign_posn= 4 | 1.25$ + | 1.25 $+ | 1.25$+ |
The monetary formatting definitions for the POSIX locale follow. The code listing depicts the localedef(1) input, the table representing the same information with the addition of localeconv(3C) and nl_langinfo(3C) formats. All values are unspecified in the POSIX locale.
LC_MONETARY # This is the POSIX locale definition for # the LC_MONETARY category. # int_curr_symbol "" currency_symbol "" mon_decimal_point "" mon_thousands_sep "" mon_grouping -1 positive_sign "" negative_sign "" int_frac_digits -1 frac_digits -1 p_cs_precedes -1 p_sep_by_space -1 n_cs_precedes -1 n_sep_by_space -1 p_sign_posn -1 n_sign_posn -1 int_p_cs_precedes -1 int_p_sep_by_space -1 int_n_cs_precedes -1 int_n_sep_by_space -1 int_p_sign_posn -1 int_n_sign_posn -1 # END LC_MONETARY
The entry n/a indicates that the value is not available in the POSIX locale.
The following items are defined in this category of the locale. The item names are the keywords recognized by the localedef utility when defining a locale. They are also similar to the member names of the lconv structure defined in <locale.h>. The localeconv() function returns {CHAR_MAX} for unspecified integer items and the empty string ("") for unspecified or size zero string items.
In a locale definition file the operands are strings. For some keywords, the strings only can contain integers. Keywords that are not provided, string values set to the empty string (""), or integer keywords set to -1, will be used to indicate that the value is not available in the locale. The following keywords are recognized:
decimal_point
thousands_sep
grouping
LC_NUMERIC # This is the POSIX locale definition for # the LC_NUMERIC category. # decimal_point "<period>" thousands_sep "" grouping -1 # END LC_NUMERIC
POSIX locale | langinfo | localeconv() | localedef | |
Item | Value | Constant | Value | Value |
decimal_point | "." | RADIXCHAR | "." | . |
thousands_sep | n/a | THOUSEP | "" | "" |
grouping | n/a | - | "" | −1 |
The entry n/a indicates that the value is not available in the POSIX locale.
abday
day
abmon
mon
d_t_fmt
date_fmt
d_fmt
t_fmt
am_pm
t_fmt_ampm
era
direction:offset:start_date:end_date:era_name:era_format
according to the definitions below. There can be as many era description segments as are necessary to describe the different eras.
The start of an era might not be the earliest point For example, the Christian era B.C. starts on the day before January 1, A.D. 1, and increases with earlier time.
direction
offset
start_date
end_date
era_name
era_format
era_d_fmt
era_t_fmt
era_d_t_fmt
alt_digits
ABDAY_x
DAY_x
ABMON_x
MON_x
D_T_FMT
D_FMT
T_FMT
AM_STR
PM_STR
T_FMT_AMPM
ERA
direction:offset:start_date:end_date:era_name:era_format
according to the definitions below. There will be as many era description segments as are necessary to describe the different eras. Era description segments are separated by semicolons.
The start of an era might not be the earliest point For example, the Christian era B.C. starts on the day before January 1, A.D. 1, and increases with earlier time.
direction
offset
start_date
end_date
era_name
era_format
ERA_D_FMT
ERA_T_FMT
ERA_D_T_FMT
ALT_DIGITS
localedef | langinfo | Conversion |
Keyword | Constant | Specifier |
abday | ABDAY_x | %a |
day | DAY_x | %A |
abmon | ABMON_x | %b |
mon | MON | %B |
d_t_fmt | D_T_FMT | %c |
date_fmt | DATE_FMT | %C |
d_fmt | D_FMT | %x |
t_fmt | T_FMT | %X |
am_pm | AM_STR | %p |
am_pm | PM_STR | %p |
t_fmt_ampm | T_FMT_AMPM | %r |
era | ERA | %EC, %Eg, |
%EG, %Ey, %EY | ||
era_d_fmt | ERA_D_FMT | %Ex |
era_t_fmt | ERA_T_FMT | %EX |
era_d_t_fmt | ERA_D_T_FMT | %Ec |
alt_digits | ALT_DIGITS | %O |
The LC_TIME descriptions of abday, day, mon, and abmon imply a Gregorian style calendar (7-day weeks, 12-month years, leap years, and so forth). Formatting time strings for other types of calendars is outside the scope of this document set.
As specified under date in Locale Definition and strftime(3C), the field descriptors corresponding to the optional keywords consist of a modifier followed by a traditional field descriptor (for instance %Ex). If the optional keywords are not supported by the implementation or are unspecified for the current locale, these field descriptors are treated as the traditional field descriptor. For instance, assume the following keywords:
alt_digits "0th" ; "1st" ; "2nd" ; "3rd" ; "4th" ; "5th" ; \ "6th" ; "7th" ; "8th" ; "9th" ; "10th"> d_fmt "The %Od day of %B in %Y"
On 7/4/1776, the %x field descriptor would result in "The 4th day of July in 1776" while 7/14/1789 would come out as "The 14 day of July in 1789" The above example is for illustrative purposes only. The %O modifier is primarily intended to provide for Kanji or Hindi digits in date formats.
The following keywords are recognized as part of the locale definition file. The nl_langinfo(3C) function accepts upper-case versions of the first four keywords.
yesexpr
noexpr
yesstr
nostr
LC_MESSAGES # This is the POSIX locale definition for # the LC_MESSAGES category. # yesexpr "<circumflex><left-square-bracket><y><Y>\ <right-square-bracket>" # noexpr "<circumflex><left-square-bracket><n><N>\ <right-square-bracket>" # yesstr "yes" nostr "no" END LC_MESSAGES
localedef Keyword | langinfo Constant | POSIX Locale Value |
yesexpr | YESEXPR | "^[yY]" |
noexpr | NOEXPR | "^[nN]" |
yesstr | YESSTR | "yes" |
nostr | NOSTR | "no" |
In an application conforming to the SUSv3 standard, the information on yesstr and nostr is not available.
May 16, 2020 |