1setlocale(3C)            Standard C Library Functions            setlocale(3C)
2
3
4

NAME

6       setlocale - modify and query a program's locale
7

SYNOPSIS

9       #include <locale.h>
10
11       char *setlocale(int category, const char *locale);
12
13

DESCRIPTION

15       The setlocale() function selects the appropriate piece of the program's
16       locale as specified by the category and locale arguments. The  category
17       argument  may have the following values: LC_CTYPE, LC_NUMERIC, LC_TIME,
18       LC_COLLATE, LC_MONETARY,  LC_MESSAGES,  and  LC_ALL.  These  names  are
19       defined  in  the <locale.h> header.  The LC_ALL variable names all of a
20       program's locale categories.
21
22
23       The LC_CTYPE variable affects the behavior of character handling  func‐
24       tions  such  as  isdigit(3C)  and  tolower(3C), and multibyte character
25       functions such as  mbtowc(3C) and wctomb(3C).
26
27
28       The LC_NUMERIC variable affects the decimal point character  and  thou‐
29       sands  separator character for the formatted input/output functions and
30       string conversion functions.
31
32
33       The LC_TIME variable affects the date and time format as  delivered  by
34       ascftime(3C), cftime(3C), getdate(3C), strftime(3C), and strptime(3C).
35
36
37       The  LC_COLLATE  variable  affects the sort order produced by collating
38       functions such as strcoll(3C) and strxfrm(3C).
39
40
41       The LC_MONETARY variable affects  the  monetary  formatted  information
42       returned by localeconv(3C).
43
44
45       The  LC_MESSAGES  variable  affects the behavior of messaging functions
46       such as dgettext(3C), gettext(3C), and gettxt(3C).
47
48
49       A value of "C" for locale specifies the traditional UNIX system  behav‐
50       ior. At program startup, the equivalent of
51
52
53       setlocale(LC_ALL, "C")
54
55
56       is  executed.  This has the effect of initializing each category to the
57       locale described by the environment "C".
58
59
60       A value of "" for locale specifies that the locale should be taken from
61       environment variables. The order in which the environment variables are
62       checked for the various categories is given below:
63
64
65
66
67       ┌───────────────┬────────────────┬────────────────┬───────────────┐
68       │   Category    │  1st Env Var   │  2nd Env Var   │ 3rd Env Var   │
69       ├───────────────┼────────────────┼────────────────┼───────────────┤
70       │LC_CTYPE:      │ LC_ALL         │ LC_CTYPE       │LANG           │
71       ├───────────────┼────────────────┼────────────────┼───────────────┤
72       │LC_COLLATE:    │ LC_ALL         │ LC_COLLATE     │LANG           │
73       ├───────────────┼────────────────┼────────────────┼───────────────┤
74       │LC_TIME:       │ LC_ALL         │ LC_TIME        │LANG           │
75       ├───────────────┼────────────────┼────────────────┼───────────────┤
76       │LC_NUMERIC:    │ LC_ALL         │ LC_NUMERIC     │LANG           │
77       ├───────────────┼────────────────┼────────────────┼───────────────┤
78       │LC_MONETARY:   │ LC_ALL         │ LC_MONETARY    │LANG           │
79       ├───────────────┼────────────────┼────────────────┼───────────────┤
80       │LC_MESSAGES:   │ LC_ALL         │ LC_MESSAGES    │LANG           │
81       └───────────────┴────────────────┴────────────────┴───────────────┘
82
83
84       If a pointer to a string is given for locale, setlocale()  attempts  to
85       set  the  locale  for the given category to locale. If setlocale() suc‐
86       ceeds, locale is returned. If setlocale()  fails,  a  null  pointer  is
87       returned and the program's locale is not changed.
88
89
90       For  category  LC_ALL, the behavior is slightly different. If a pointer
91       to a string is given for locale and LC_ALL is given for category,  set‐
92       locale()  attempts  to set the locale for all the categories to locale.
93       The locale may be a simple locale, consisting of a single locale, or  a
94       composite  locale.  If  the locales for all the categories are the same
95       after all the attempted  locale  changes,  setlocale()  will  return  a
96       pointer  to  the common simple locale. If there is a mixture of locales
97       among the categories, setlocale() will return a composite locale.
98

RETURN VALUES

100       Upon successful completion, setlocale() returns the  string  associated
101       with  the specified category for the new locale. Otherwise, setlocale()
102       returns a null pointer and the program's locale is not changed.
103
104
105       A null pointer for locale causes setlocale() to return a pointer to the
106       string  associated  with the category for the program's current locale.
107       The program's locale is not changed.
108
109
110       The string returned by setlocale() is such that a subsequent call  with
111       that  string  and its associated category will restore that part of the
112       program's locale. The string returned must not be modified by the  pro‐
113       gram, but may be overwritten by a subsequent call to setlocale().
114

ERRORS

116       No errors are defined.
117

FILES

119       /usr/lib/locale/locale    locale database directory for locale
120
121

ATTRIBUTES

123       See attributes(5) for descriptions of the following attributes:
124
125
126
127
128       ┌─────────────────────────────┬─────────────────────────────┐
129       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
130       ├─────────────────────────────┼─────────────────────────────┤
131       │CSI                          │Enabled                      │
132       ├─────────────────────────────┼─────────────────────────────┤
133       │Interface Stability          │Standard                     │
134       ├─────────────────────────────┼─────────────────────────────┤
135       │MT-Level                     │MT-Safe with exceptions      │
136       └─────────────────────────────┴─────────────────────────────┘
137

SEE ALSO

139       locale(1), ctype(3C), getdate(3C) gettext(3C), gettxt(3C), isdigit(3C),
140       libc(3LIB),  localeconv(3C),  mbtowc(3C),  strcoll(3C),   strftime(3C),
141       strptime(3C)  strxfrm(3C) tolower(3C), wctomb(3C), attributes(5), envi‐
142       ron(5), locale(5), standards(5)
143

NOTES

145       It is unsafe for any thread to change locale  (by  calling  setlocale()
146       with  a  non-null locale argument) in a multithreaded application while
147       any other thread in the application is using any locale-sensitive  rou‐
148       tine.  To  change  locale  in  a multithreaded application, setlocale()
149       should be called prior to using  any  locale-sensitive  routine.  Using
150       setlocale()  to  query  the current locale is safe and can be used any‐
151       where in a multithreaded application except when some other  thread  is
152       changing locale.
153
154
155       It  is the user's responsibility to ensure that mixed locale categories
156       are compatible. For example, setting LC_CTYPE=C and  LC_TIME=ja  (where
157       ja  indicates  Japanese) will not work, because Japanese time cannot be
158       represented in the "C" locale's ASCII codeset.
159
160
161
162SunOS 5.11                        19 Sep 2005                    setlocale(3C)
Impressum