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	.\" 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	.Fn setlocale "int category" "const char *locale"
	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.
	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
	76	.Xr ctype 3
	77	and
	78	.Xr multibyte 3
	79	functions.
	80	This controls recognition of upper and lower case,
	81	alphabetic or non-alphabetic characters,
	82	and so on.
	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.
	129	.Sh RETURN VALUES
	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 .
	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.
	146	.Sh ERRORS
	147	No errors are defined.
	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 ,
	162	.Xr localeconv 3 ,
	163	.Xr multibyte 3 ,
	164	.Xr strcoll 3 ,
	165	.Xr strxfrm 3 ,
	166	.Xr euc 5 ,
	167	.Xr utf8 5 ,
	168	.Xr environ 7
	169	.Sh STANDARDS
	170	The
	171	.Fn setlocale
	172	function conforms to
	173	.St -isoC-99 .
	174	.Sh HISTORY
	175	The
	176	.Fn setlocale
	177	function first appeared in
	178	.Bx 4.4 .