LOCALEDEF(1POSIX)

💖 LOCALEDEF(1POSIX) — bestie, we're building locales ✨

okay so real talk, this is the POSIX Programmer's Manual page for localedef. Heads up from the jump: the Linux version of this interface might be different from what's written here (so pls go check the matching Linux manual page for the Linux deets), and sometimes it's just… not implemented on Linux at all. 🙈

---

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

---

✨ NAME ✨

localedef — define locale environment. that's it, that's the job. 💅

---

🌸 SYNOPSIS 🌸

localedef [-c] [-f charmap] [-i sourcefile] [-u code_set_name] name

---

🦋 DESCRIPTION 🦋

So localedef converts source definitions for locale categories into a format that actual functions and utilities can use — y'know, the ones whose behavior depends on how the locale environment variables are set, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 7, Locale.

Now, whether users can even create new locales — on top of the ones the implementation already gives you — is implementation-defined. But! If the symbolic constant POSIX2_LOCALEDEF is defined, then the system supports creating new locales. And on XSI-conformant systems, POSIX2_LOCALEDEF shall be defined. no cap. 👑

The utility reads source definitions for one or more locale categories belonging to the same locale — either from the file you name with -i (if you gave one) or from standard input. your call, bestie.

The name operand is the target locale, periodt. And the utility supports making public (generally accessible) locales and private (restricted-access) locales. Implementations may gate the ability to create or modify public locales behind users with appropriate privileges — so like, bring your permissions. 🔐

Every category source definition gets identified by its matching environment variable name, and it's terminated by an END category-name statement. Here's what shall be supported (and lowkey, the input can also contain source for implementation-defined categories too):

• LC_CTYPE — Defines character classification and case conversion.
• LC_COLLATE — Defines collation rules.
• LC_MONETARY — Defines the format and symbols used in formatting of monetary information.
• LC_NUMERIC — Defines the decimal delimiter, grouping, and grouping symbol for non-monetary numeric editing.
• LC_TIME — Defines the format and content of date and time information.
• LC_MESSAGES — Defines the format and values of affirmative and negative responses.

---

💅 OPTIONS 💅

localedef shall conform to the Base Definitions volume of POSIX.1-2017, Section 12.2, Utility Syntax Guidelines. (yes ma'am, we respect the guidelines ✨)

The following options shall be supported:

• -c — Create permanent output even if warning messages have been issued. like, warnings happened but we're still posting the result. 💖
• -f charmap — Specify the pathname of a file containing a mapping of character symbols and collating element symbols to actual character encodings. The format of the charmap is described in the Base Definitions volume of POSIX.1-2017, Section 6.4, Character Set Description File. The application shall ensure that this option is specified if symbolic names (other than collating symbols defined in a collating-symbol keyword) are used. If the -f option is not present, an implementation-defined character mapping shall be used.
• -i inputfile — The pathname of a file containing the source definitions. If this option is not present, source definitions shall be read from standard input. The format of the inputfile is described in the Base Definitions volume of POSIX.1-2017, Section 7.3, Locale Definition.
• -u code_set_name — Specify the name of a codeset used as the target mapping of character symbols and collating element symbols whose encoding values are defined in terms of the ISO/IEC 10646-1:2000 standard position constant values.

---

🌈 OPERANDS 🌈

One operand, and it's the star of the show:

• name — Identifies the locale; see the Base Definitions volume of POSIX.1-2017, Chapter 7, Locale for a description of the use of this name. If the name contains one or more <slash> characters, name shall be interpreted as a pathname where the created locale definitions shall be stored. If name does not contain any <slash> characters, the interpretation of the name is implementation-defined and the locale shall be public. The ability to create public locales in this way may be restricted to users with appropriate privileges. (As a consequence of specifying one name, although several categories can be processed in one execution, only categories belonging to the same locale can be processed.)

🫶 the little parenthetical at the end is important bestie — one name, one locale, even if you're cooking multiple categories at once.

---

⭐ STDIN ⭐

Unless the -i option is specified, the standard input shall be a text file containing one or more locale category source definitions, as described in the Base Definitions volume of POSIX.1-2017, Section 7.3, Locale Definition.

And here's a cute one: when lines are continued using the escape character mechanism, there is no limit to the length of the accumulated continued line. go long, girl. 💜

---

🍓 INPUT FILES 🍓

The character set mapping file specified as the charmap option-argument is described in the Base Definitions volume of POSIX.1-2017, Section 6.4, Character Set Description File.

If a locale category source definition contains a copy statement, as defined in the Base Definitions volume of POSIX.1-2017, Chapter 7, Locale, and the copy statement names a valid, existing locale, then localedef shall behave as if the source definition had contained a valid category source definition for the named locale. (copy-paste but make it legal ✨)

---

🧚 ENVIRONMENT VARIABLES 🧚

These cuties shall affect how localedef runs:

• 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_COLLATE — (This variable has no effect on localedef; the POSIX locale is used for this category.)
• 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). This variable has no effect on the processing of localedef input data; the POSIX locale is used for this purpose, regardless of the value of this variable. 💀 (yes, really, it does nothing here)
• 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.

---

💖 ASYNCHRONOUS EVENTS 💖

Default. nothing extra, moving on. 😌

---

🎀 STDOUT 🎀

The utility shall report all categories successfully processed, in an unspecified format. so like, it will tell you, just don't expect a specific look. 👑

---

🦋 STDERR 🦋

The standard error shall be used only for diagnostic messages.

---

🌸 OUTPUT FILES 🌸

The format of the created output is unspecified. If the name operand does not contain a <slash>, the existence of an output file for the locale is unspecified. (mysterious. iconic. we don't know where it lives. 🙈)

---

💅 EXTENDED DESCRIPTION 💅

When the -u option is used, the code_set_name option-argument shall be interpreted as an implementation-defined name of a codeset to which the ISO/IEC 10646-1:2000 standard position constant values shall be converted via an implementation-defined method. Both the ISO/IEC 10646-1:2000 standard position constant values and other formats (decimal, hexadecimal, or octal) shall be valid as encoding values within the charmap file. The codeset represented by the implementation-defined name can be any codeset that is supported by the implementation.

When conflicts occur between the charmap specification of <code_set_name>, <mb_cur_max>, or <mb_cur_min> and the implementation-defined interpretation of these respective items for the codeset represented by the -u option-argument code_set_name, the result is unspecified. 🚨

When conflicts occur between the charmap encoding values specified for symbolic names of characters of the portable character set and the implementation-defined assignment of character encoding values, the result is unspecified. 🚨

⚠️ and this one is a big yikes: if a non-printable character in the charmap has a width specified that is not -1, the result will be undefined. do not do this. i am begging. 😭

---

✨ EXIT STATUS ✨

Here's the tea — the following exit values shall be returned:

1. 0 — No errors occurred and the locales were successfully created. (ate 💅)
2. 1 — Warnings occurred and the locales were successfully created.
3. 2 — The locale specification exceeded implementation limits or the coded character set or sets used were not supported by the implementation, and no locale was created.
4. 3 — The capability to create new locales is not supported by the implementation.
5. >3 — Warnings or errors occurred and no output was created.

---

🔥 CONSEQUENCES OF ERRORS 🔥

If an error is detected, no permanent output shall be created. periodt.

If warnings occur, permanent output shall be created if the -c option was specified. (see, that's what -c is for, bestie 🫶)

The following conditions shall cause warning messages to be issued:

• If a symbolic name not found in the charmap file is used for the descriptions of the LC_CTYPE or LC_COLLATE categories (for other categories, this shall be an error condition).
• If the number of operands to the order keyword exceeds the {COLL_WEIGHTS_MAX} limit.
• If optional keywords not supported by the implementation are present in the source.

Other implementation-defined conditions may also cause warnings.

The following sections are informative. (translation: the required stuff is done, now we gossip ✨)

---

💜 APPLICATION USAGE 💜

The charmap definition is optional, and is contained outside the locale definition. This allows both completely self-defined source files, and generic sources (applicable to more than one codeset). To aid portability, all charmap definitions must use the same symbolic names for the portable character set.

As explained in the Base Definitions volume of POSIX.1-2017, Section 6.4, Character Set Description File, it is implementation-defined whether or not users or applications can provide additional character set description files. Therefore, the -f option might be operable only when an implementation-defined charmap is named. 🙈

---

🌈 EXAMPLES 🌈

None. yeah, they left us hanging bestie. 😭

---

part 2 is coming, don't go anywhere 🦋

✨ RATIONALE ✨

okay bestie so here's the tea ☕ — the output that localedef produces is implementation-defined. meaning: every system does its own lil thing and that's just how it is, no cap. 🫶

and the name operand? that's the whole identity of the locale, it's giving main character energy for exactly one locale. 💅 so like — yeah you can process several categories in a single execution, slay, but (and this is the important bit) only categories that belong to the same locale can be processed together. different locales in one run? not happening, sorry babe 😭 it's a consequence of how the name operand works, fr fr.

---

🔮 FUTURE DIRECTIONS 🔮

None. that's it. that's the whole section. nothing coming, nothing planned, the future is empty and honestly? iconic. ✨

---

👀 SEE ALSO 👀

• locale — go read this one too, it's the sibling energy you need 💖

and from the Base Definitions volume of POSIX.1‐2017:

• Section 6.4, Character Set Description File 🌸
• Chapter 7, Locale 🦋
• Chapter 8, Environment Variables 🌈
• Section 12.2, Utility Syntax Guidelines ⭐

---

📜 COPYRIGHT 📜

bestie this part is legal-speak so I'm keeping every word, don't come for me 💀

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 the whole page, we did it bestie!! 🎀 the source is IEEE/The Open Group, the version is 2017, and the date on the tin is 2017 too — so this absolute legend of a man page has been out here since 2017 serving Unix realness. LOCALEDEF(1POSIX) forever 💜 go forth and build locales, you gorgeous genius 🦋✨