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