git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

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