setlocale(3)

1setlocale(3)               Library Functions Manual               setlocale(3)
2
3
4

NAME

6       setlocale - set the current locale
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <locale.h>
13
14       char *setlocale(int category, const char *locale);
15

DESCRIPTION

17       The  setlocale() function is used to set or query the program's current
18       locale.
19
20       If locale is not NULL, the program's current locale is modified accord‐
21       ing  to the arguments.  The argument category determines which parts of
22       the program's current locale should be modified.
23
24       Category            Governs
25       LC_ALL              All of the locale
26       LC_ADDRESS          Formatting of addresses and geography-related items
27                           (*)
28       LC_COLLATE          String collation
29       LC_CTYPE            Character classification
30       LC_IDENTIFICATION   Metadata describing the locale (*)
31       LC_MEASUREMENT      Settings related to measurements (metric versus US
32                           customary) (*)
33       LC_MESSAGES         Localizable natural-language messages
34       LC_MONETARY         Formatting of monetary values
35       LC_NAME             Formatting of salutations for persons (*)
36       LC_NUMERIC          Formatting of nonmonetary numeric values
37       LC_PAPER            Settings related to the standard paper size (*)
38       LC_TELEPHONE        Formats to be used with telephone services (*)
39       LC_TIME             Formatting of date and time values
40
41       The categories marked with an asterisk in the above table are  GNU  ex‐
42       tensions.   For further information on these locale categories, see lo‐
43       cale(7).
44
45       The argument locale is a pointer to a character string  containing  the
46       required  setting  of  category.   Such a string is either a well-known
47       constant like "C" or "da_DK" (see below), or an opaque string that  was
48       returned by another call of setlocale().
49
50       If  locale  is an empty string, "", each part of the locale that should
51       be modified is set according to the environment variables.  The details
52       are  implementation-dependent.  For glibc, first (regardless of catego‐
53       ry), the environment variable LC_ALL is inspected, next the environment
54       variable  with the same name as the category (see the table above), and
55       finally the environment variable LANG.  The first existing  environment
56       variable  is  used.   If its value is not a valid locale specification,
57       the locale is unchanged, and setlocale() returns NULL.
58
59       The locale "C" or "POSIX" is a portable locale; it exists on  all  con‐
60       forming systems.
61
62       A  locale  name  is  typically  of the form language[_territory][.code‐
63       set][@modifier], where language is an ISO 639 language code,  territory
64       is an ISO 3166 country code, and codeset is a character set or encoding
65       identifier like ISO-8859-1 or UTF-8.  For a list of all  supported  lo‐
66       cales, try "locale -a" (see locale(1)).
67
68       If locale is NULL, the current locale is only queried, not modified.
69
70       On  startup of the main program, the portable "C" locale is selected as
71       default.  A program may be made portable to all locales by calling:
72
73           setlocale(LC_ALL, "");
74
75       after program initialization, and then:
76
77       •  using the values returned from a localeconv(3) call  for  locale-de‐
78          pendent information;
79
80       •  using the multibyte and wide character functions for text processing
81          if MB_CUR_MAX > 1;
82
83       •  using strcoll(3) and strxfrm(3) to compare strings; and
84
85       •  using wcscoll(3) and wcsxfrm(3) to compare wide-character strings.
86

RETURN VALUE

88       A successful call to setlocale() returns an opaque string  that  corre‐
89       sponds to the locale set.  This string may be allocated in static stor‐
90       age.  The string returned is such that  a  subsequent  call  with  that
91       string  and  its  associated  category  will  restore  that part of the
92       process's locale.  The return value is NULL if the  request  cannot  be
93       honored.
94

ATTRIBUTES

96       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
97       tributes(7).
98
99       ┌─────────────────────────┬───────────────┬────────────────────────────┐
100       │Interface                │ Attribute     │ Value                      │
101       ├─────────────────────────┼───────────────┼────────────────────────────┤
102       │setlocale()              │ Thread safety │ MT-Unsafe const:locale env │
103       └─────────────────────────┴───────────────┴────────────────────────────┘
104

STANDARDS

106       C11, POSIX.1-2008.
107
108   Categories
109       LC_ALL
110       LC_COLLATE
111       LC_CTYPE
112       LC_MONETARY
113       LC_NUMERIC
114       LC_TIME
115              C11, POSIX.1-2008.
116
117       LC_MESSAGES
118              POSIX.1-2008.
119
120       Others:
121              GNU.
122

HISTORY

124       POSIX.1-2001, C89.
125
126   Categories
127       LC_ALL
128       LC_COLLATE
129       LC_CTYPE
130       LC_MONETARY
131       LC_NUMERIC
132       LC_TIME
133              C89, POSIX.1-2001.
134
135       LC_MESSAGES
136              POSIX.1-2001.
137
138       Others:
139              GNU.
140