HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ATTRIBUTES |STANDARDS |HISTORY |SEE ALSO |COLOPHON | |
setlocale(3) Library Functions Manualsetlocale(3)setlocale - set the current locale
Standard C library (libc,-lc)
#include <locale.h>char *setlocale(intcategory, const char *locale);
Thesetlocale() function is used to set or query the program's current locale. Iflocale is not NULL, the program's current locale is modified according to the arguments. The argumentcategory determines which parts of the program's current locale should be modified.Category GovernsLC_ALLAll of the localeLC_ADDRESSFormatting of addresses and geography-related items (*)LC_COLLATEString collationLC_CTYPECharacter classificationLC_IDENTIFICATIONMetadata describing the locale (*)LC_MEASUREMENTSettings related to measurements (metric versus US customary) (*)LC_MESSAGESLocalizable natural-language messagesLC_MONETARYFormatting of monetary valuesLC_NAMEFormatting of salutations for persons (*)LC_NUMERICFormatting of nonmonetary numeric valuesLC_PAPERSettings related to the standard paper size (*)LC_TELEPHONEFormats to be used with telephone services (*)LC_TIMEFormatting of date and time values The categories marked with an asterisk in the above table are GNU extensions. For further information on these locale categories, seelocale(7). The argumentlocale is a pointer to a character string containing the required setting ofcategory. Such a string is either a well- known constant like "C" or "da_DK" (see below), or an opaque string that was returned by another call ofsetlocale(). Iflocale is an empty string,"", each part of the locale that should be modified is set according to the environment variables. The details are implementation-dependent. For glibc, first (regardless ofcategory), the environment variableLC_ALLis inspected, next the environment variable with the same name as the category (see the table above), and finally the environment variableLANG. The first existing environment variable is used. If its value is not a valid locale specification, the locale is unchanged, andsetlocale() returns NULL. The locale"C"or"POSIX"is a portable locale; it exists on all conforming systems. A locale name is typically of the formlanguage[_territory][.codeset][@modifier], wherelanguage is an ISO 639 language code,territory is an ISO 3166 country code, andcodeset is a character set or encoding identifier likeISO-8859-1 orUTF-8. For a list of all supported locales, try "locale -a" (seelocale(1)). Iflocale is NULL, the current locale is only queried, not modified. On startup of the main program, the portable"C"locale is selected as default. A program may be made portable to all locales by calling: setlocale(LC_ALL, ""); after program initialization, and then: • using the values returned from alocaleconv(3) call for locale- dependent information; • using the multibyte and wide character functions for text processing ifMB_CUR_MAX > 1; • usingstrcoll(3) andstrxfrm(3) to compare strings; and • usingwcscoll(3) andwcsxfrm(3) to compare wide-character strings.
A successful call tosetlocale() returns an opaque string that corresponds to the locale set. This string may be allocated in static storage. The string returned is such that a subsequent call with that string and its associated category will restore that part of the process's locale. The return value is NULL if the request cannot be honored.
For an explanation of the terms used in this section, seeattributes(7). ┌───────────────────┬───────────────┬────────────────────────────┐ │Interface│Attribute│Value│ ├───────────────────┼───────────────┼────────────────────────────┤ │setlocale() │ Thread safety │ MT-Unsafe const:locale env │ └───────────────────┴───────────────┴────────────────────────────┘
C11, POSIX.1-2008.CategoriesLC_ALLLC_COLLATELC_CTYPELC_MONETARYLC_NUMERICLC_TIME C11, POSIX.1-2008.LC_MESSAGES POSIX.1-2008. Others: GNU.
POSIX.1-2001, C89.CategoriesLC_ALLLC_COLLATELC_CTYPELC_MONETARYLC_NUMERICLC_TIME C89, POSIX.1-2001.LC_MESSAGES POSIX.1-2001. Others: GNU.
locale(1),localedef(1),isalpha(3),localeconv(3),nl_langinfo(3),rpmatch(3),strcoll(3),strftime(3),charsets(7),locale(7)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17setlocale(3)Pages that refer to this page:apropos(1), flatpak-config(1), localedef(1), man(1), whatis(1), catgets(3), catopen(3), duplocale(3), ecvt(3), getdate(3), gettext(3), isalpha(3), lconv(3type), localeconv(3), locale_t(3type), ncurses(3x), newlocale(3), nl_langinfo(3), printf(3), rpmatch(3), sscanf(3), strcoll(3), strfmon(3), strftime(3), strptime(3), strxfrm(3), toupper(3), uselocale(3), locale(5), locale(7), unicode(7), utf-8(7), lsof(8)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |