[apple/libc.git] / locale / FreeBSD / 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 *
.Fn setlocale "int category" "const char *locale"
.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
5b2abdfb 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
3d9156a7	36	.\" $FreeBSD: src/lib/libc/locale/setlocale.3,v 1.33 2004/10/17 06:51:50 tjr Exp $
5b2abdfb	37	.\"
3d9156a7	38	.Dd November 21, 2003
5b2abdfb A	39	.Dt SETLOCALE 3
	40	.Os
	41	.Sh NAME
3d9156a7	42	.Nm setlocale
5b2abdfb A	43	.Nd natural language formatting for C
	44	.Sh LIBRARY
	45	.Lb libc
	46	.Sh SYNOPSIS
	47	.In locale.h
	48	.Ft char *
	49	.Fn setlocale "int category" "const char *locale"
5b2abdfb A	50	.Sh DESCRIPTION
	51	The
	52	.Fn setlocale
	53	function sets the C library's notion
	54	of natural language formatting style
	55	for particular sets of routines.
	56	Each such style is called a
	57	.Sq locale
	58	and is invoked using an appropriate name passed as a C string.
5b2abdfb A	59	.Pp
	60	The
	61	.Fn setlocale
	62	function recognizes several categories of routines.
	63	These are the categories and the sets of routines they select:
	64	.Pp
	65	.Bl -tag -width LC_MONETARY
	66	.It Dv LC_ALL
	67	Set the entire locale generically.
	68	.It Dv LC_COLLATE
	69	Set a locale for string collation routines.
	70	This controls alphabetic ordering in
	71	.Fn strcoll
	72	and
	73	.Fn strxfrm .
	74	.It Dv LC_CTYPE
	75	Set a locale for the
3d9156a7	76	.Xr ctype 3
5b2abdfb	77	and
3d9156a7	78	.Xr multibyte 3
5b2abdfb A	79	functions.
	80	This controls recognition of upper and lower case,
	81	alphabetic or non-alphabetic characters,
3d9156a7	82	and so on.
5b2abdfb A	83	.It Dv LC_MESSAGES
	84	Set a locale for message catalogs, see
	85	.Xr catopen 3
	86	function.
	87	.It Dv LC_MONETARY
	88	Set a locale for formatting monetary values;
	89	this affects the
	90	.Fn localeconv
	91	function.
	92	.It Dv LC_NUMERIC
	93	Set a locale for formatting numbers.
	94	This controls the formatting of decimal points
	95	in input and output of floating point numbers
	96	in functions such as
	97	.Fn printf
	98	and
	99	.Fn scanf ,
	100	as well as values returned by
	101	.Fn localeconv .
	102	.It Dv LC_TIME
	103	Set a locale for formatting dates and times using the
	104	.Fn strftime
	105	function.
	106	.El
	107	.Pp
	108	Only three locales are defined by default,
	109	the empty string
	110	.Li "\&""\\|""
	111	which denotes the native environment, and the
	112	.Li "\&""C""
	113	and
	114	.Li "\&""POSIX""
	115	locales, which denote the C language environment.
	116	A
	117	.Fa locale
	118	argument of
	119	.Dv NULL
	120	causes
	121	.Fn setlocale
	122	to return the current locale.
	123	By default, C programs start in the
	124	.Li "\&""C""
	125	locale.
	126	The only function in the library that sets the locale is
	127	.Fn setlocale ;
	128	the locale is never changed as a side effect of some other routine.
5b2abdfb	129	.Sh RETURN VALUES
9385eb3d A	130	Upon successful completion,
	131	.Fn setlocale
	132	returns the string associated with the specified
	133	.Fa category
	134	for the requested
	135	.Fa locale .
5b2abdfb A	136	The
	137	.Fn setlocale
	138	function returns
	139	.Dv NULL
	140	and fails to change the locale
	141	if the given combination of
	142	.Fa category
	143	and
	144	.Fa locale
	145	makes no sense.
9385eb3d A	146	.Sh ERRORS
9385eb3d A	147	No errors are defined.
5b2abdfb A	148	.Sh FILES
	149	.Bl -tag -width /usr/share/locale/locale/category -compact
	150	.It Pa $PATH_LOCALE/ Ns Em locale/category
	151	.It Pa /usr/share/locale/ Ns Em locale/category
	152	locale file for the locale
	153	.Em locale
	154	and the category
	155	.Em category .
	156	.El
	157	.Sh SEE ALSO
	158	.Xr colldef 1 ,
	159	.Xr mklocale 1 ,
	160	.Xr catopen 3 ,
	161	.Xr ctype 3 ,
3d9156a7	162	.Xr localeconv 3 ,
5b2abdfb	163	.Xr multibyte 3 ,
5b2abdfb A	164	.Xr strcoll 3 ,
5b2abdfb A	165	.Xr strxfrm 3 ,
3d9156a7 A	166	.Xr euc 5 ,
	167	.Xr utf8 5 ,
	168	.Xr environ 7
5b2abdfb A	169	.Sh STANDARDS
	170	The
	171	.Fn setlocale
3d9156a7	172	function conforms to
9385eb3d	173	.St -isoC-99 .
5b2abdfb A	174	.Sh HISTORY
	175	The
	176	.Fn setlocale
3d9156a7	177	function first appeared in
5b2abdfb	178	.Bx 4.4 .