[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.26 2003/03/20 08:13:34 ache Exp $
.\"
.Dd October 5, 2002
.Dt SETLOCALE 3
.Os
.Sh NAME
.Nm setlocale ,
.Nm localeconv
.Nd natural language formatting for C
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In locale.h
.Ft char *
.Fn setlocale "int category" "const char *locale"
.Ft struct lconv *
.Fn localeconv "void"
.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.
The
.Fn localeconv
routine returns the current locale's parameters
for formatting numbers.
.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 ,
.Xr mbrune 3 ,
.Xr multibyte 3
and
.Xr rune 3
functions.
This controls recognition of upper and lower case,
alphabetic or non-alphabetic characters,
and so on.  The real work is done by the
.Fn setrunelocale
function.
.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.
.Pp
The
.Fn localeconv
function returns a pointer to a structure
which provides parameters for formatting numbers,
especially currency values:
.Bd -literal -offset indent
struct lconv {
	char	*decimal_point;
	char	*thousands_sep;
	char	*grouping;
	char	*int_curr_symbol;
	char	*currency_symbol;
	char	*mon_decimal_point;
	char	*mon_thousands_sep;
	char	*mon_grouping;
	char	*positive_sign;
	char	*negative_sign;
	char	int_frac_digits;
	char	frac_digits;
	char	p_cs_precedes;
	char	p_sep_by_space;
	char	n_cs_precedes;
	char	n_sep_by_space;
	char	p_sign_posn;
	char	n_sign_posn;
	char	int_p_cs_precedes;
	char	int_n_cs_precedes;
	char	int_p_sep_by_space;
	char	int_n_sep_by_space;
	char	int_p_sign_posn;
	char	int_n_sign_posn;
};
.Ed
.Pp
The individual fields have the following meanings:
.Pp
.Bl -tag -width mon_decimal_point
.It Fa decimal_point
The decimal point character, except for currency values,
can't be the empty string.
.It Fa thousands_sep
The separator between groups of digits
before the decimal point, except for currency values.
.It Fa grouping
The sizes of the groups of digits, except for currency values.
This is a pointer to a vector of integers, each of size
.Va char ,
representing group size from low order digit groups
to high order (right to left).
The list may be terminated with 0 or
.Dv CHAR_MAX .
If the list is terminated with 0,
the last group size before the 0 is repeated to account for all the digits.
If the list is terminated with
.Dv CHAR_MAX ,
no more grouping is performed.
.It Fa int_curr_symbol
The standardized international currency symbol.
.It Fa currency_symbol
The local currency symbol.
.It Fa mon_decimal_point
The decimal point character for currency values.
.It Fa mon_thousands_sep
The separator for digit groups in currency values.
.It Fa mon_grouping
Like
.Fa grouping
but for currency values.
.It Fa positive_sign
The character used to denote nonnegative currency values,
usually the empty string.
.It Fa negative_sign
The character used to denote negative currency values,
usually a minus sign.
.It Fa int_frac_digits
The number of digits after the decimal point
in an international-style currency value.
.It Fa frac_digits
The number of digits after the decimal point
in the local style for currency values.
.It Fa p_cs_precedes
1 if the currency symbol precedes the currency value
for nonnegative values, 0 if it follows.
.It Fa p_sep_by_space
1 if a space is inserted between the currency symbol
and the currency value for nonnegative values, 0 otherwise.
.It Fa n_cs_precedes
Like
.Fa p_cs_precedes
but for negative values.
.It Fa n_sep_by_space
Like
.Fa p_sep_by_space
but for negative values.
.It Fa p_sign_posn
The location of the
.Fa positive_sign
with respect to a nonnegative quantity and the
.Fa currency_symbol ,
coded as follows:
.Bl -tag -width 3n -compact
.It Li 0
Parentheses around the entire string.
.It Li 1
Before the string.
.It Li 2
After the string.
.It Li 3
Just before
.Fa currency_symbol .
.It Li 4
Just after
.Fa currency_symbol .
.El
.It Fa n_sign_posn
Like
.Fa p_sign_posn
but for negative currency values.
.It Fa int_p_cs_precedes
Same as
.Fa p_cs_precedes ,
but for internationally formatted monetary quantities.
.It Fa int_n_cs_precedes
Same as
.Fa n_cs_precedes ,
but for internationally formatted monetary quantities.
.It Fa int_p_sep_by_space
Same as
.Fa p_sep_by_space ,
but for internationally formatted monetary quantities.
.It Fa int_n_sep_by_space
Same as
.Fa n_sep_by_space ,
but for internationally formatted monetary quantities.
.It Fa int_p_sign_posn
Same as
.Fa p_sign_posn ,
but for internationally formatted monetary quantities.
.It Fa int_n_sign_posn
Same as
.Fa n_sign_posn ,
but for internationally formatted monetary quantities.
.El
.Pp
Unless mentioned above,
an empty string as a value for a field
indicates a zero length result or
a value that is not in the current locale.
A
.Dv CHAR_MAX
result similarly denotes an unavailable value.
.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.
The
.Fn localeconv
function returns a pointer to a static object
which may be altered by later calls to
.Fn setlocale
or
.Fn localeconv .
.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 mbrune 3 ,
.Xr multibyte 3 ,
.Xr rune 3 ,
.Xr strcoll 3 ,
.Xr strxfrm 3 ,
.Xr euc 4 ,
.Xr utf2 4 ,
.Xr utf8 5
.Sh STANDARDS
The
.Fn setlocale
and
.Fn localeconv
functions conform to
.St -isoC-99 .
.Sh HISTORY
The
.Fn setlocale
and
.Fn localeconv
functions 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
9385eb3d	36	.\" $FreeBSD: src/lib/libc/locale/setlocale.3,v 1.26 2003/03/20 08:13:34 ache Exp $
5b2abdfb	37	.\"
9385eb3d	38	.Dd October 5, 2002
5b2abdfb A	39	.Dt SETLOCALE 3
	40	.Os
	41	.Sh NAME
	42	.Nm setlocale ,
	43	.Nm localeconv
	44	.Nd natural language formatting for C
	45	.Sh LIBRARY
	46	.Lb libc
	47	.Sh SYNOPSIS
	48	.In locale.h
	49	.Ft char *
	50	.Fn setlocale "int category" "const char *locale"
	51	.Ft struct lconv *
	52	.Fn localeconv "void"
	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	The
	63	.Fn localeconv
	64	routine returns the current locale's parameters
	65	for formatting numbers.
	66	.Pp
	67	The
	68	.Fn setlocale
	69	function recognizes several categories of routines.
	70	These are the categories and the sets of routines they select:
	71	.Pp
	72	.Bl -tag -width LC_MONETARY
	73	.It Dv LC_ALL
	74	Set the entire locale generically.
	75	.It Dv LC_COLLATE
	76	Set a locale for string collation routines.
	77	This controls alphabetic ordering in
	78	.Fn strcoll
	79	and
	80	.Fn strxfrm .
	81	.It Dv LC_CTYPE
	82	Set a locale for the
	83	.Xr ctype 3 ,
	84	.Xr mbrune 3 ,
	85	.Xr multibyte 3
	86	and
	87	.Xr rune 3
	88	functions.
	89	This controls recognition of upper and lower case,
	90	alphabetic or non-alphabetic characters,
	91	and so on. The real work is done by the
	92	.Fn setrunelocale
	93	function.
	94	.It Dv LC_MESSAGES
	95	Set a locale for message catalogs, see
	96	.Xr catopen 3
	97	function.
	98	.It Dv LC_MONETARY
	99	Set a locale for formatting monetary values;
	100	this affects the
	101	.Fn localeconv
	102	function.
103	.It Dv LC_NUMERIC
104	Set a locale for formatting numbers.
105	This controls the formatting of decimal points
106	in input and output of floating point numbers
107	in functions such as
108	.Fn printf
109	and
110	.Fn scanf ,
111	as well as values returned by
112	.Fn localeconv .
113	.It Dv LC_TIME
114	Set a locale for formatting dates and times using the
115	.Fn strftime
116	function.
117	.El
118	.Pp
119	Only three locales are defined by default,
120	the empty string
121	.Li "\&""\\|""
122	which denotes the native environment, and the
123	.Li "\&""C""
124	and
125	.Li "\&""POSIX""
126	locales, which denote the C language environment.
127	A
128	.Fa locale
129	argument of
130	.Dv NULL
131	causes
132	.Fn setlocale
133	to return the current locale.
134	By default, C programs start in the
135	.Li "\&""C""
136	locale.
137	The only function in the library that sets the locale is
138	.Fn setlocale ;
139	the locale is never changed as a side effect of some other routine.
140	.Pp
141	The
142	.Fn localeconv
143	function returns a pointer to a structure
144	which provides parameters for formatting numbers,
145	especially currency values:
146	.Bd -literal -offset indent
147	struct lconv {
148	char *decimal_point;
149	char *thousands_sep;
150	char *grouping;
151	char *int_curr_symbol;
152	char *currency_symbol;
153	char *mon_decimal_point;
154	char *mon_thousands_sep;
155	char *mon_grouping;
156	char *positive_sign;
157	char *negative_sign;
158	char int_frac_digits;
159	char frac_digits;
160	char p_cs_precedes;
161	char p_sep_by_space;
162	char n_cs_precedes;
163	char n_sep_by_space;
164	char p_sign_posn;
165	char n_sign_posn;
9385eb3d A	166	char int_p_cs_precedes;
	167	char int_n_cs_precedes;
	168	char int_p_sep_by_space;
	169	char int_n_sep_by_space;
	170	char int_p_sign_posn;
	171	char int_n_sign_posn;
5b2abdfb A	172	};
	173	.Ed
	174	.Pp
	175	The individual fields have the following meanings:
	176	.Pp
	177	.Bl -tag -width mon_decimal_point
	178	.It Fa decimal_point
9385eb3d A	179	The decimal point character, except for currency values,
9385eb3d A	180	can't be the empty string.
5b2abdfb A	181	.It Fa thousands_sep
	182	The separator between groups of digits
	183	before the decimal point, except for currency values.
	184	.It Fa grouping
	185	The sizes of the groups of digits, except for currency values.
	186	This is a pointer to a vector of integers, each of size
	187	.Va char ,
	188	representing group size from low order digit groups
	189	to high order (right to left).
	190	The list may be terminated with 0 or
	191	.Dv CHAR_MAX .
	192	If the list is terminated with 0,
	193	the last group size before the 0 is repeated to account for all the digits.
	194	If the list is terminated with
	195	.Dv CHAR_MAX ,
	196	no more grouping is performed.
	197	.It Fa int_curr_symbol
	198	The standardized international currency symbol.
	199	.It Fa currency_symbol
	200	The local currency symbol.
	201	.It Fa mon_decimal_point
	202	The decimal point character for currency values.
	203	.It Fa mon_thousands_sep
	204	The separator for digit groups in currency values.
	205	.It Fa mon_grouping
	206	Like
	207	.Fa grouping
	208	but for currency values.
	209	.It Fa positive_sign
	210	The character used to denote nonnegative currency values,
	211	usually the empty string.
	212	.It Fa negative_sign
	213	The character used to denote negative currency values,
	214	usually a minus sign.
	215	.It Fa int_frac_digits
	216	The number of digits after the decimal point
	217	in an international-style currency value.
	218	.It Fa frac_digits
	219	The number of digits after the decimal point
	220	in the local style for currency values.
	221	.It Fa p_cs_precedes
	222	1 if the currency symbol precedes the currency value
	223	for nonnegative values, 0 if it follows.
	224	.It Fa p_sep_by_space
	225	1 if a space is inserted between the currency symbol
	226	and the currency value for nonnegative values, 0 otherwise.
	227	.It Fa n_cs_precedes
	228	Like
	229	.Fa p_cs_precedes
	230	but for negative values.
	231	.It Fa n_sep_by_space
	232	Like
	233	.Fa p_sep_by_space
	234	but for negative values.
	235	.It Fa p_sign_posn
	236	The location of the
	237	.Fa positive_sign
	238	with respect to a nonnegative quantity and the
	239	.Fa currency_symbol ,
	240	coded as follows:
	241	.Bl -tag -width 3n -compact
	242	.It Li 0
	243	Parentheses around the entire string.
	244	.It Li 1
245	Before the string.
246	.It Li 2
247	After the string.
248	.It Li 3
249	Just before
250	.Fa currency_symbol .
251	.It Li 4
252	Just after
253	.Fa currency_symbol .
254	.El
255	.It Fa n_sign_posn
256	Like
257	.Fa p_sign_posn
258	but for negative currency values.
9385eb3d A	259	.It Fa int_p_cs_precedes
	260	Same as
	261	.Fa p_cs_precedes ,
	262	but for internationally formatted monetary quantities.
	263	.It Fa int_n_cs_precedes
	264	Same as
	265	.Fa n_cs_precedes ,
	266	but for internationally formatted monetary quantities.
	267	.It Fa int_p_sep_by_space
	268	Same as
	269	.Fa p_sep_by_space ,
	270	but for internationally formatted monetary quantities.
	271	.It Fa int_n_sep_by_space
	272	Same as
	273	.Fa n_sep_by_space ,
	274	but for internationally formatted monetary quantities.
	275	.It Fa int_p_sign_posn
	276	Same as
	277	.Fa p_sign_posn ,
	278	but for internationally formatted monetary quantities.
	279	.It Fa int_n_sign_posn
	280	Same as
	281	.Fa n_sign_posn ,
	282	but for internationally formatted monetary quantities.
5b2abdfb A	283	.El
	284	.Pp
	285	Unless mentioned above,
	286	an empty string as a value for a field
	287	indicates a zero length result or
	288	a value that is not in the current locale.
	289	A
	290	.Dv CHAR_MAX
	291	result similarly denotes an unavailable value.
	292	.Sh RETURN VALUES
9385eb3d A	293	Upon successful completion,
	294	.Fn setlocale
	295	returns the string associated with the specified
	296	.Fa category
	297	for the requested
	298	.Fa locale .
5b2abdfb A	299	The
	300	.Fn setlocale
	301	function returns
	302	.Dv NULL
	303	and fails to change the locale
	304	if the given combination of
	305	.Fa category
	306	and
	307	.Fa locale
	308	makes no sense.
	309	The
	310	.Fn localeconv
	311	function returns a pointer to a static object
	312	which may be altered by later calls to
	313	.Fn setlocale
	314	or
	315	.Fn localeconv .
9385eb3d A	316	.Sh ERRORS
9385eb3d A	317	No errors are defined.
5b2abdfb A	318	.Sh FILES
	319	.Bl -tag -width /usr/share/locale/locale/category -compact
	320	.It Pa $PATH_LOCALE/ Ns Em locale/category
	321	.It Pa /usr/share/locale/ Ns Em locale/category
	322	locale file for the locale
	323	.Em locale
	324	and the category
	325	.Em category .
	326	.El
	327	.Sh SEE ALSO
	328	.Xr colldef 1 ,
	329	.Xr mklocale 1 ,
	330	.Xr catopen 3 ,
	331	.Xr ctype 3 ,
	332	.Xr mbrune 3 ,
	333	.Xr multibyte 3 ,
	334	.Xr rune 3 ,
	335	.Xr strcoll 3 ,
	336	.Xr strxfrm 3 ,
	337	.Xr euc 4 ,
9385eb3d A	338	.Xr utf2 4 ,
9385eb3d A	339	.Xr utf8 5
5b2abdfb A	340	.Sh STANDARDS
	341	The
	342	.Fn setlocale
	343	and
	344	.Fn localeconv
	345	functions conform to
9385eb3d	346	.St -isoC-99 .
5b2abdfb A	347	.Sh HISTORY
	348	The
	349	.Fn setlocale
	350	and
	351	.Fn localeconv
	352	functions first appeared in
	353	.Bx 4.4 .