LOCALE(1POSIX)

✨ PROLOG ✨

This manual page (LOCALE(1POSIX)) is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ — so pls consult the corresponding Linux manual page for details of Linux behavior — or the interface may not even be implemented on Linux. 😭 No cap, bestie, it's giving "consult your local man page" energy.

🌸 NAME 🌸

locale — get locale-specific information 💅

✨ SYNOPSIS ✨

locale [-a|-m]

locale [-ck] name...

🦋 DESCRIPTION 🦋

The locale utility shall write information about the current locale environment, or all public locales, to the standard output. For the purposes of this section, a public locale is one provided by the implementation that is accessible to the application. 💖

When locale 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 POSIX.1‐2017, Chapter 7, Locale. ✨

When invoked with operands, it shall write values that have been assigned to the keywords in the locale categories, as follows:

• Specifying a keyword name shall select the named keyword and the category containing that keyword. 👑
• Specifying a category name shall select the named category and all keywords in that category. 🌈

💅 OPTIONS 💅

The locale utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.

The following options shall be supported:

• -a — Write information about all available public locales. The available locales shall include POSIX, representing the POSIX locale. The manner in which the implementation determines what other locales are available is implementation-defined. 🫶
• -c — Write the names of selected locale categories; see the STDOUT section. The -c 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 -k option. 💖
• -k — Write the names and values of selected keywords. The implementation may omit values for some keywords; see the OPERANDS section. 👑
• -m — Write names of available charmaps; see the Base Definitions volume of POSIX.1‐2017, Section 6.1, Portable Character Set. 🎀

🌸 OPERANDS 🌸

The following operand shall be supported:

• name — The name of a locale category as defined in the Base Definitions volume of POSIX.1‐2017, Chapter 7, Locale, the name of a keyword in a locale category, or the reserved name charmap. The named category or keyword shall be selected for output. If a single name 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 name operands, in any sequence. It is implementation-defined whether any keyword values are written for the categories LC_CTYPE and LC_COLLATE. 😭

🦋 STDIN 🦋

Not used.

✨ INPUT FILES ✨

None.

💖 ENVIRONMENT VARIABLES 💖

The following environment variables shall affect the execution of locale:

• LANG — Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of POSIX.1‐2017, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.) 🌸
• LC_ALL — If set to a non-empty string value, override the values of all the other internationalization variables. 👑
• LC_CTYPE — 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). 💅
• LC_MESSAGES — Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error. 😭
• NLSPATH — Determine the location of message catalogs for the processing of LC_MESSAGES. 🎀

The application shall ensure that the LANG, LC_*, and NLSPATH environment variables specify the current locale environment to be written out; they shall be used if the -a option is not specified. ✨

🌈 ASYNCHRONOUS EVENTS 🌈

Default.

👑 STDOUT 👑

The LANG variable shall be written first using the format:

"LANG=%s\n", <value>

If LANG is not set or is an empty string, the value is the empty string.

If locale is invoked without any options or operands, the names and values of the LC_* environment variables described in this volume of POSIX.1‐2017 shall be written to the standard output, one variable per line, and each line using the following format. Only those variables set in the environment and not overridden by LC_ALL shall be written using this format:

"%s=%s\n", <variable_name>, <value>

The names of those LC_* variables associated with locale categories defined in this volume of POSIX.1‐2017 that are not set in the environment or are overridden by LC_ALL shall be written in the following format:

"%s=\"%s\"\n", <variable_name>, <implied value>

The <implied value> shall be the name of the locale that has been selected for that category by the implementation, based on the values in LANG and LC_ALL, as described in the Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment Variables.

The <value> and <implied value> shown above shall be properly quoted for possible later reentry to the shell. The <value> shall not be quoted using double-quotes (so that it can be distinguished by the user from the <implied value> case, which always requires double-quotes). 💅

The LC_ALL variable shall be written last, using the first format shown above. If it is not set, it shall be written as:

"LC_ALL=\n"

If any arguments are specified:

1. If the -a option is specified, the names of all the public locales shall be written, each in the following format:

"%s\n", <locale name>

2. If the -c option is specified, the names of all selected categories shall be written, each in the following format:

"%s\n", <category name>

If keywords are also selected for writing (see following items), the category name output shall precede the keyword output for that category.

If the -c option is not specified, the names of the categories shall not be written; only the keywords, as selected by the <name> operand, shall be written.

3. If the -k option is specified, the names and values of selected keywords shall be written. If a value is non-numeric and is not a compound keyword value, it shall be written in the following format:

"%s=\"%s\"\n", <keyword name>, <keyword value>

If a value is a non-numeric compound keyword value, it shall either be written in the format:

"%s=\"%s\"\n", <keyword name>, <keyword value>

where the <keyword value> is a single string of values separated by <semicolon> characters, or it shall be written in the format:

"%s=%s\n", <keyword name>, <keyword value>

where the <keyword value> is encoded as a set of strings, each enclosed in double-quotation-marks, separated by <semicolon> characters.

If the keyword was charmap, the name of the charmap (if any) that was specified via the localedef -f option when the locale was created shall be written, with the word charmap as <keyword name>. 🎀

If a value is numeric, it shall be written in one of the following formats:

"%s=%d\n", <keyword name>, <keyword value>

"%s=%c%o\n", <keyword name>, <escape character>, <keyword value>

"%s=%cx%x\n", <keyword name>, <escape character>, <keyword value>

where the <escape character> is that identified by the escape_char keyword in the current locale; see the Base Definitions volume of POSIX.1‐2017, Section 7.3, Locale Definition.

Compound keyword values (list entries) shall be separated in the output by <semicolon> characters. When included in keyword values, the <semicolon>, <backslash>, double-quote, and any control character shall be preceded (escaped) with the escape character. 😭

4. If the -k option is not specified, selected keyword values shall be written, each in the following format:

"%s\n", <keyword value>

If the keyword was charmap, the name of the charmap (if any) that was specified via the localedef -f option when the locale was created shall be written. 🌸

5. If the -m option is specified, then a list of all available charmaps shall be written, each in the format:

"%s\n", <charmap>

where <charmap> is in a format suitable for use as the option-argument to the localedef -f option. ✨

💀 STDERR 💀

The standard error shall be used only for diagnostic messages.

🎀 OUTPUT FILES 🎀

None.

🌟 EXTENDED DESCRIPTION 🌟

None.

👑 EXIT STATUS 👑

The following exit values shall be returned:

• 0 — All the requested information was found and output successfully. 💖
• >0 — An error occurred. 😭

🌈 CONSEQUENCES OF ERRORS 🌈

Default.

The following sections are informative.

💅 APPLICATION USAGE 💅

If the LANG environment variable is not set or set to an empty value, or one of the LC_* 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 POSIX.1‐2017, Chapter 8, Environment Variables. 🦋

Implementations are not required to write out the actual values for keywords in the categories LC_CTYPE and LC_COLLATE; however, they must write out the categories (allowing an application to determine, for example, which character classes are available). 👑

🌸 EXAMPLES 🌸

Okay bestie, for these examples let's just pretend the locale environment variables are set like this, mmkay?

LANG=locale_x
LC_COLLATE=locale_y

So if you ran the command locale, you'd get back this whole situation:

LANG=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=

Heads up: the order those categories show up in? Not specified by this volume of POSIX.1‐2017. So don't come for me if yours is shuffled. 💅

Now, this command:

LC_ALL=POSIX locale -ck decimal_point

would produce:

LC_NUMERIC
decimal_point="."

And here's the cute one — an actual application of locale to figure out whether a user typed a yes or a no:

printf 'Prompt for response: '
read response
if printf "%s\n$response" | grep -- -Eq "$(locale yesexpr)"
then
    affirmative processing goes here
else
    non-affirmative processing goes here
fi

---

🧠 RATIONALE 🧠

Okay so why is everything like this? Let me spill. 🍵

The output for the categories LC_CTYPE and LC_COLLATE has been made implementation-defined because there's a questionable value in having a shell script receive an entire array of characters. It's also difficult to return a logical collation description, short of returning a complete localedef source. Like, imagine dumping a whole collation essay into your shell script? No thank you.

The -m 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. So it's basically a charmap census. ✨

The -c 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 -k option.

The charmap 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. 🎀

According to the Base Definitions volume of POSIX.1‐2017, Section 6.1, Portable Character Set, the standard requires that all supported locales must have the same encoding for <period> and <slash>, because these two characters are used within the locale-independent pathname resolution sequence. So yeah — it would be an error if locale -a listed both ASCII and EBCDIC-based locales, since those two encodings do not share the same representation for either <period> or <slash>. 💀 Any system that supports both environments would be expected to provide two POSIX locales, one in either codeset, where only the locales appropriate to the current environment can be visible at a time. And in an XSI-compliant implementation, the dd utility is the only portable means for performing conversions between the two character sets. (dd carrying the whole team on its back fr fr.)

---

🔮 FUTURE DIRECTIONS 🔮

None. Literally nothing. The future is a blank canvas, bestie. 🦋

---

👀 SEE ALSO 👀

• localedef

And also, from the Base Definitions volume of POSIX.1‐2017:

• Section 6.1, Portable Character Set
• Chapter 7, Locale
• Chapter 8, Environment Variables
• Section 12.2, Utility Syntax Guidelines

---

📜 COPYRIGHT 📜

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 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 .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

And that's a wrap on LOCALE(1POSIX), bestie!! 💖 This masterpiece was brought to you by IEEE/The Open Group, 2017 — yeah, the footer said LOCALE(1POSIX) and honestly? Iconic. Go forth and set your locales correctly, you absolute main character. 🫶✨