[apple/libc.git] / locale / setlocale.3

.\" Copyright (c) 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Donn Seeley at BSDI.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)setlocale.3	8.1 (Berkeley) 6/9/93
.\" $FreeBSD: src/lib/libc/locale/setlocale.3,v 1.33 2004/10/17 06:51:50 tjr Exp $
.\"
.Dd November 21, 2003
.Dt SETLOCALE 3
.Os
.Sh NAME
.Nm setlocale
.Nd natural language formatting for C
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In locale.h
.Ft char *
.Fo setlocale
.Fa "int category"
.Fa "const char *locale"
.Fc
.Sh DESCRIPTION
The
.Fn setlocale
function sets the C library's notion
of natural language formatting style
for particular sets of routines.
Each such style is called a
.Sq locale
and is invoked using an appropriate name passed as a C string.
.Pp
The
.Fn setlocale
function recognizes several categories of routines.
These are the categories and the sets of routines they select:
.Pp
.Bl -tag -width LC_MONETARY
.It Dv LC_ALL
Set the entire locale generically.
.It Dv LC_COLLATE
Set a locale for string collation routines.
This controls alphabetic ordering in
.Fn strcoll
and
.Fn strxfrm .
.It Dv LC_CTYPE
Set a locale for the
.Xr ctype 3
and
.Xr multibyte 3
functions.
This controls recognition of upper and lower case,
alphabetic or non-alphabetic characters,
and so on.
.It Dv LC_MESSAGES
Set a locale for message catalogs, see
.Xr catopen 3
function.
.It Dv LC_MONETARY
Set a locale for formatting monetary values;
this affects the
.Fn localeconv
function.
.It Dv LC_NUMERIC
Set a locale for formatting numbers.
This controls the formatting of decimal points
in input and output of floating point numbers
in functions such as
.Fn printf
and
.Fn scanf ,
as well as values returned by
.Fn localeconv .
.It Dv LC_TIME
Set a locale for formatting dates and times using the
.Fn strftime
function.
.El
.Pp
Only three locales are defined by default:
the empty string
.Li "\&""\|""
(which denotes the native environment) and the
.Li "\&""C""
and
.Li "\&""POSIX""
locales (which denote the C-language environment).
A
.Fa locale
argument of
.Dv NULL
causes
.Fn setlocale
to return the current locale.
By default, C programs start in the
.Li "\&""C""
locale.
The only function in the library that sets the locale is
.Fn setlocale ;
the locale is never changed as a side effect of some other routine.
.Sh RETURN VALUES
Upon successful completion,
.Fn setlocale
returns the string associated with the specified
.Fa category
for the requested
.Fa locale .
The
.Fn setlocale
function returns
.Dv NULL
and fails to change the locale
if the given combination of
.Fa category
and
.Fa locale
makes no sense.
.Sh ERRORS
No errors are defined.
.Sh FILES
.Bl -tag -width /usr/share/locale/locale/category -compact
.It Pa $PATH_LOCALE/ Ns Em locale/category
.It Pa /usr/share/locale/ Ns Em locale/category
locale file for the locale
.Em locale
and the category
.Em category .
.El
.Sh SEE ALSO
.Xr colldef 1 ,
.Xr mklocale 1 ,
.Xr catopen 3 ,
.Xr ctype 3 ,
.Xr localeconv 3 ,
.Xr multibyte 3 ,
.Xr strcoll 3 ,
.Xr strxfrm 3 ,
.Xr euc 5 ,
.Xr utf8 5 ,
.Xr environ 7
.Sh STANDARDS
The
.Fn setlocale
function conforms to
.St -isoC-99 .
.Sh HISTORY
The
.Fn setlocale
function first appeared in
.Bx 4.4 .
Commit	Line	Data
224c7076 A	1	.\" Copyright (c) 1993
	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" Donn Seeley at BSDI.
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\" 3. All advertising materials mentioning features or use of this software
	16	.\" must display the following acknowledgement:
	17	.\" This product includes software developed by the University of
	18	.\" California, Berkeley and its contributors.
	19	.\" 4. Neither the name of the University nor the names of its contributors
	20	.\" may be used to endorse or promote products derived from this software
	21	.\" without specific prior written permission.
	22	.\"
	23	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	24	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	25	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	26	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	27	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	28	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	29	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	30	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	31	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	32	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	33	.\" SUCH DAMAGE.
	34	.\"
	35	.\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93
	36	.\" $FreeBSD: src/lib/libc/locale/setlocale.3,v 1.33 2004/10/17 06:51:50 tjr Exp $
	37	.\"
	38	.Dd November 21, 2003
	39	.Dt SETLOCALE 3
	40	.Os
	41	.Sh NAME
	42	.Nm setlocale
	43	.Nd natural language formatting for C
	44	.Sh LIBRARY
	45	.Lb libc
	46	.Sh SYNOPSIS
	47	.In locale.h
	48	.Ft char *
	49	.Fo setlocale
	50	.Fa "int category"
	51	.Fa "const char *locale"
	52	.Fc
	53	.Sh DESCRIPTION
	54	The
	55	.Fn setlocale
	56	function sets the C library's notion
	57	of natural language formatting style
	58	for particular sets of routines.
	59	Each such style is called a
	60	.Sq locale
	61	and is invoked using an appropriate name passed as a C string.
	62	.Pp
	63	The
	64	.Fn setlocale
65	function recognizes several categories of routines.
66	These are the categories and the sets of routines they select:
67	.Pp
68	.Bl -tag -width LC_MONETARY
69	.It Dv LC_ALL
70	Set the entire locale generically.
71	.It Dv LC_COLLATE
72	Set a locale for string collation routines.
73	This controls alphabetic ordering in
74	.Fn strcoll
75	and
76	.Fn strxfrm .
77	.It Dv LC_CTYPE
78	Set a locale for the
79	.Xr ctype 3
80	and
81	.Xr multibyte 3
82	functions.
83	This controls recognition of upper and lower case,
84	alphabetic or non-alphabetic characters,
85	and so on.
86	.It Dv LC_MESSAGES
87	Set a locale for message catalogs, see
88	.Xr catopen 3
89	function.
90	.It Dv LC_MONETARY
91	Set a locale for formatting monetary values;
92	this affects the
93	.Fn localeconv
94	function.
95	.It Dv LC_NUMERIC
96	Set a locale for formatting numbers.
97	This controls the formatting of decimal points
98	in input and output of floating point numbers
99	in functions such as
100	.Fn printf
101	and
102	.Fn scanf ,
103	as well as values returned by
104	.Fn localeconv .
105	.It Dv LC_TIME
106	Set a locale for formatting dates and times using the
107	.Fn strftime
108	function.
109	.El
110	.Pp
111	Only three locales are defined by default:
112	the empty string
113	.Li "\&""\\|""
114	(which denotes the native environment) and the
115	.Li "\&""C""
116	and
117	.Li "\&""POSIX""
118	locales (which denote the C-language environment).
119	A
120	.Fa locale
121	argument of
122	.Dv NULL
123	causes
124	.Fn setlocale
125	to return the current locale.
126	By default, C programs start in the
127	.Li "\&""C""
128	locale.
129	The only function in the library that sets the locale is
130	.Fn setlocale ;
131	the locale is never changed as a side effect of some other routine.
132	.Sh RETURN VALUES
133	Upon successful completion,
134	.Fn setlocale
135	returns the string associated with the specified
136	.Fa category
137	for the requested
138	.Fa locale .
139	The
140	.Fn setlocale
141	function returns
142	.Dv NULL
143	and fails to change the locale
144	if the given combination of
145	.Fa category
146	and
147	.Fa locale
148	makes no sense.
149	.Sh ERRORS
150	No errors are defined.
151	.Sh FILES
152	.Bl -tag -width /usr/share/locale/locale/category -compact
153	.It Pa $PATH_LOCALE/ Ns Em locale/category
154	.It Pa /usr/share/locale/ Ns Em locale/category
155	locale file for the locale
156	.Em locale
157	and the category
158	.Em category .
159	.El
160	.Sh SEE ALSO
161	.Xr colldef 1 ,
162	.Xr mklocale 1 ,
163	.Xr catopen 3 ,
164	.Xr ctype 3 ,
165	.Xr localeconv 3 ,
166	.Xr multibyte 3 ,
167	.Xr strcoll 3 ,
168	.Xr strxfrm 3 ,
169	.Xr euc 5 ,
170	.Xr utf8 5 ,
171	.Xr environ 7
172	.Sh STANDARDS
173	The
174	.Fn setlocale
175	function conforms to
176	.St -isoC-99 .
177	.Sh HISTORY
178	The
179	.Fn setlocale
180	function first appeared in
181	.Bx 4.4 .