1 '\" te
2 .\"
3 .\" This file and its contents are supplied under the terms of the
4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
5 .\" You may only use this file in accordance with the terms of version
6 .\" 1.0 of the CDDL.
7 .\"
8 .\" A full copy of the text of the CDDL should have accompanied this
9 .\" source. A copy of the CDDL is also available via the Internet at
10 .\" http://www.illumos.org/license/CDDL.
11 .\"
12 .\"
13 .\" Copyright (c) 2014 Joyent, Inc. All rights reserved.
14 .\"
15 .TH USELOCALE 3C "Jun 11, 2014"
16
17 .SH NAME
18
19 uselocale \- get and set the locale for an individual thread
20
21 .SH SYNOPSIS
22
23 .LP
24 .nf
25 #include <locale.h>
26
27 .BI "locale_t uselocale(locale_t " loc );
28
29 .SH DESCRIPTION
30 .LP
31
32 The
33 .B uselocale()
34 function is used to obtain and set the current locale for a thread. When
35 a thread is created, it uses the global locale as specified by calls to
36 .BR setlocale() .
37 A call to
38 .B uselocale()
39 causes all operations in the thread to use the locale specified in
40 .IR loc .
41 The thread ignores all subsequent changes to the global locale that
42 occur through calls to
43 .BR setlocale() .
44 When the special locale,
45 .BR LC_GLOBAL_LOCALE ,
46 is passed in to
47 .BR uselocale() ,
48 the thread returns to using the global locale, and subsequent calls to
49 .B setlocale()
50 cause changes for the thread.
51
52 .LP
53 In addition,
54 .B uselocale()
55 can be used to obtain the current locale in use by thread, this is done
56 by passing in the special locale
57 .BR (locale_t) 0.
58 If the thread has never set a locale through
59 .BR uselocale() ,
60 then the current global locale as determined through calls to
61 .B setlocale()
62 will be returned.
63
64 .LP
65 Locale objects to pass in to
66 .B uselocale()
67 can be created and destroyed with the functions
68 .BR duplocale (3C),
69 .BR newlocale (3C),
70 and
71 .BR freelocale (3C).
72
73 .SH RETURN VALUES
74
75 Upon successful completion, the
76 .B uselocale()
77 function always returns the previous locale that was set. If no locale
78 was previously set, the global locale,
79 .BR LC_GLOBAL_LOCALE ,
80 is returned. If the locale object
81 .I loc
82 is the special locale
83 .BR (lcoale_t) 0,
84 then the current locale of the thread is not updated. On failure, the
85 .B uselocale()
86 function returns
87 .B (locale_t) 0, and sets
88 .B errno
89 to indicate the error.
90
91 .SH ERRORS
92
93 .sp
94 .ne 2
95 .na
96 .B EINVAL
97 .ad
98 .RS 10n
99 An invalid locale was encountered or an internal error occurred that
100 caused the system to be unable to update the locale.
101 .RE
102
103 .SH ATTRIBUTES
104 .sp
105 .TS
106 box;
107 c | c
108 l | l .
109 ATTRIBUTE TYPE ATTRIBUTE VALUE
110 _
111 Interface Stability Standard
112 _
113 MT-Level Safe
114 .TE
115
116 .SH SEE ALSO
117 .BR locale (1),
118 .BR duplocale (3C),
119 .BR newlocale (3C),
120 .BR setlocale (3C),
121 .BR environ (5),
122 .BR locale (5)
|
1 '\" te
2 .\"
3 .\" This file and its contents are supplied under the terms of the
4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
5 .\" You may only use this file in accordance with the terms of version
6 .\" 1.0 of the CDDL.
7 .\"
8 .\" A full copy of the text of the CDDL should have accompanied this
9 .\" source. A copy of the CDDL is also available via the Internet at
10 .\" http://www.illumos.org/license/CDDL.
11 .\"
12 .\"
13 .\" Copyright (c) 2014 Joyent, Inc. All rights reserved.
14 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
15 .\"
16 .TH USELOCALE 3C "Jun 24, 2014"
17
18 .SH NAME
19 uselocale \- get and set the locale for an individual thread
20 .SH SYNOPSIS
21 .LP
22 .nf
23 #include <locale.h>
24
25 \fBlocale_t\fR \fBuselocale\fR(\fBlocale_t\fR \fIloc\fR);
26 .fi
27 .SH DESCRIPTION
28 .LP
29 The
30 .B uselocale()
31 function is used to obtain and set the current locale for a thread. When
32 a thread is created, it uses the global locale as specified by calls to
33 .BR setlocale() .
34 .LP
35 If
36 .BR (locale_t) 0
37 is supplied for
38 .IR loc ,
39 then no change is made to the thread's locale setting. This can be used
40 to query the thread's locale without making any change.
41 .LP
42 If
43 .B LC_GLOBAL_LOCALE
44 is supplied for
45 .IR loc ,
46 then the thread will use the global locale, undoing the effect of any
47 prior call to establish a thread-specific locale.
48 .LP
49 Otherwise the thread will use the supplied
50 .I loc
51 locale object as a thread-specific locale. Changes to the global
52 locale, or to the locale of any other thread, will not affect this thread.
53 .LP
54 Locale objects for use with
55 .B uselocale()
56 can be created with the functions
57 .BR duplocale (3C)
58 and
59 .BR newlocale (3C).
60 .SH RETURN VALUES
61 Upon successful completion, the
62 .B uselocale()
63 function always returns the previous locale that was set. If no locale
64 was previously set, the global locale,
65 .BR LC_GLOBAL_LOCALE ,
66 is returned. On failure, the
67 .B uselocale()
68 function returns
69 .BR (locale_t) 0,
70 and sets
71 .B errno
72 to indicate the error.
73 .SH ERRORS
74 .TP
75 .B EINVAL
76 An invalid locale was encountered or an internal error occurred that
77 caused the system to be unable to update the locale.
78 .SH ATTRIBUTES
79 .TS
80 box;
81 c | c
82 l | l .
83 ATTRIBUTE TYPE ATTRIBUTE VALUE
84 _
85 Interface Stability Standard
86 _
87 MT-Level MT-Safe
88 .TE
89
90 .SH SEE ALSO
91 .BR locale (1),
92 .BR duplocale (3C),
93 .BR newlocale (3C),
94 .BR setlocale (3C),
95 .BR locale (5)
|