[apple/libc.git] / locale / newlocale.3

.Dd March 11, 2005
.Dt NEWLOCALE 3
.Os
.Sh NAME
.Nm newlocale
.Nd Create a new locale
.Sh SYNOPSIS
.In xlocale.h
.Ft locale_t
.Fn newlocale "int mask" "const char * locale" "locale_t base"
.Sh DESCRIPTION
Creates a new
.Vt locale_t
based off the locale specified by
.Va base .
The categories specified by
.Va mask
will be replaced to correspond with the named
.Va locale .
.Pp
The
.Va mask
is the logical OR of the following:
.Bl -tag -width LC_MONETARY_MASK
.It Dv LC_COLLATE_MASK
Collation
.It Dv LC_CTYPE_MASK
Character type
.It Dv LC_MESSAGES_MASK
Messages
.It Dv LC_MONETARY_MASK
Monetary
.It Dv LC_NUMERIC_MASK
Numeric
.It Dv LC_TIME_MASK
Time
.It Dv LC_ALL_MASK
The logical OR of all of the above
.El
.Pp
The
.Va locale
string is typically the name of one of the directories in
.Pa /usr/share/locale .
If
.Va locale
is
.Dv NULL ,
then the C locale is used. If
.Va locale
is an empty string, then it will look for environment variables:
LC_ALL, then LC_* if the corresponding LC_*_MASK bit is set, then
the LANG environment variable. If none of these are found, it
will default to the C locale.
.Pp
If
.Va base
is
.Dv NULL ,
the current locale is used. If
.Va base
is
.Dv LC_GLOBAL_LOCALE ,
the global locale is used.
.Pp
If
.Va mask
is
.Dv LC_ALL_MASK ,
.Va base
is ignored. In order to create a C
.Vt locale_t
value, use
.Fn newlocale "LC_ALL_MASK" "NULL" "NULL" .
.Sh RETURN VALUES
Returns a new
.Vt locale_t ,
or
.Dv NULL
in case of error.
New locales should be freed with
.Xr freelocale 3 .
.Sh SEE ALSO
.Xr duplocale 3 ,
.Xr freelocale 3 ,
.Xr querylocale 3 ,
.Xr uselocale 3 ,
.Xr xlocale 3
Commit	Line	Data
3d9156a7 A	1	.Dd March 11, 2005
	2	.Dt NEWLOCALE 3
	3	.Os
	4	.Sh NAME
	5	.Nm newlocale
	6	.Nd Create a new locale
	7	.Sh SYNOPSIS
	8	.In xlocale.h
	9	.Ft locale_t
	10	.Fn newlocale "int mask" "const char * locale" "locale_t base"
	11	.Sh DESCRIPTION
	12	Creates a new
	13	.Vt locale_t
	14	based off the locale specified by
	15	.Va base .
	16	The categories specified by
	17	.Va mask
	18	will be replaced to correspond with the named
	19	.Va locale .
	20	.Pp
	21	The
	22	.Va mask
	23	is the logical OR of the following:
	24	.Bl -tag -width LC_MONETARY_MASK
	25	.It Dv LC_COLLATE_MASK
	26	Collation
	27	.It Dv LC_CTYPE_MASK
	28	Character type
	29	.It Dv LC_MESSAGES_MASK
	30	Messages
	31	.It Dv LC_MONETARY_MASK
	32	Monetary
	33	.It Dv LC_NUMERIC_MASK
	34	Numeric
	35	.It Dv LC_TIME_MASK
	36	Time
	37	.It Dv LC_ALL_MASK
	38	The logical OR of all of the above
	39	.El
	40	.Pp
	41	The
	42	.Va locale
	43	string is typically the name of one of the directories in
	44	.Pa /usr/share/locale .
	45	If
	46	.Va locale
	47	is
	48	.Dv NULL ,
	49	then the C locale is used. If
	50	.Va locale
	51	is an empty string, then it will look for environment variables:
	52	LC_ALL, then LC_* if the corresponding LC_*_MASK bit is set, then
	53	the LANG environment variable. If none of these are found, it
	54	will default to the C locale.
	55	.Pp
	56	If
	57	.Va base
	58	is
	59	.Dv NULL ,
	60	the current locale is used. If
	61	.Va base
	62	is
	63	.Dv LC_GLOBAL_LOCALE ,
	64	the global locale is used.
65	.Pp
66	If
67	.Va mask
68	is
69	.Dv LC_ALL_MASK ,
70	.Va base
71	is ignored. In order to create a C
72	.Vt locale_t
73	value, use
74	.Fn newlocale "LC_ALL_MASK" "NULL" "NULL" .
75	.Sh RETURN VALUES
76	Returns a new
77	.Vt locale_t ,
78	or
79	.Dv NULL
80	in case of error.
81	New locales should be freed with
82	.Xr freelocale 3 .
83	.Sh SEE ALSO
3d9156a7 A	84	.Xr duplocale 3 ,
	85	.Xr freelocale 3 ,
	86	.Xr querylocale 3 ,
224c7076 A	87	.Xr uselocale 3 ,
224c7076 A	88	.Xr xlocale 3