[apple/libc.git] / locale / FreeBSD / nl_langinfo.3

.\" Copyright (c) 2001 Alexey Zelkin <phantom@FreeBSD.org>
.\" All rights reserved.
.\"
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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.
.\"
.\" $FreeBSD: src/lib/libc/locale/nl_langinfo.3,v 1.7 2009/11/16 14:33:31 brueffer Exp $
.\"
.Dd May 3, 2001
.Dt NL_LANGINFO 3
.Os
.Sh NAME
.Nm nl_langinfo ,
.Nm nl_langinfo_l
.Nd language information
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In langinfo.h
.Ft char *
.Fo nl_langinfo
.Fa "nl_item item"
.Fc
.In langinfo.h
.In xlocale.h
.Ft char *
.Fo nl_langinfo_l
.Fa "nl_item item"
.Fa "locale_t loc"
.Fc
.Sh DESCRIPTION
The
.Fn nl_langinfo
function returns a pointer to a string containing information relevant to
the particular language or cultural area defined in the program's locale.
The manifest constant names and values of
.Fa item
are defined in
.In langinfo.h .
.Pp
Calls to
.Fn setlocale
with a category corresponding to the category of
.Fa item ,
or to the
category
.Dv LC_ALL ,
may overwrite the buffer pointed to by the return value.
.Sh RETURN VALUES
In a locale where langinfo data is not defined,
.Fn nl_langinfo
returns a pointer to the corresponding string in the
.Tn POSIX
locale.
In all locales,
.Fn nl_langinfo
returns a pointer to an empty string if
.Fa item
contains an invalid setting.
.Sh EXAMPLES
For example:
.Pp
.Dl nl_langinfo(ABDAY_1)
.Pp
would return a pointer to the string
.Qq Li Dom
if the identified language was
Portuguese, and
.Qq Li Sun
if the identified language was English.
.Pp
While the
.Fn nl_langinfo
function uses the current locale, the
.Fn nl_langinfo_l
function may be passed a locale directly. See
.Xr xlocale 3
for more information.
.Sh SEE ALSO
.Xr setlocale 3 ,
.Xr xlocale 3
.Sh STANDARDS
The
.Fn nl_langinfo
function conforms to
.St -susv2 .
.Sh HISTORY
The
.Fn nl_langinfo
function first appeared in
.Fx 4.6 .
Commit	Line	Data
9385eb3d	1	.\" Copyright (c) 2001 Alexey Zelkin <phantom@FreeBSD.org>
5b2abdfb A	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\"
	13	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
	14	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	15	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	16	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	17	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	18	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	19	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	20	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	21	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	22	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	23	.\" SUCH DAMAGE.
	24	.\"
1f2f436a	25	.\" $FreeBSD: src/lib/libc/locale/nl_langinfo.3,v 1.7 2009/11/16 14:33:31 brueffer Exp $
5b2abdfb A	26	.\"
	27	.Dd May 3, 2001
	28	.Dt NL_LANGINFO 3
	29	.Os
	30	.Sh NAME
ad3c9f2a A	31	.Nm nl_langinfo ,
ad3c9f2a A	32	.Nm nl_langinfo_l
5b2abdfb A	33	.Nd language information
	34	.Sh LIBRARY
	35	.Lb libc
	36	.Sh SYNOPSIS
	37	.In langinfo.h
	38	.Ft char *
ad3c9f2a A	39	.Fo nl_langinfo
	40	.Fa "nl_item item"
	41	.Fc
	42	.In langinfo.h
	43	.In xlocale.h
	44	.Ft char *
	45	.Fo nl_langinfo_l
	46	.Fa "nl_item item"
	47	.Fa "locale_t loc"
	48	.Fc
5b2abdfb A	49	.Sh DESCRIPTION
	50	The
	51	.Fn nl_langinfo
	52	function returns a pointer to a string containing information relevant to
	53	the particular language or cultural area defined in the program's locale.
	54	The manifest constant names and values of
	55	.Fa item
	56	are defined in
3d9156a7	57	.In langinfo.h .
5b2abdfb A	58	.Pp
	59	Calls to
	60	.Fn setlocale
	61	with a category corresponding to the category of
	62	.Fa item ,
	63	or to the
	64	category
	65	.Dv LC_ALL ,
1f2f436a	66	may overwrite the buffer pointed to by the return value.
5b2abdfb A	67	.Sh RETURN VALUES
	68	In a locale where langinfo data is not defined,
	69	.Fn nl_langinfo
	70	returns a pointer to the corresponding string in the
	71	.Tn POSIX
	72	locale.
	73	In all locales,
	74	.Fn nl_langinfo
	75	returns a pointer to an empty string if
	76	.Fa item
	77	contains an invalid setting.
1f2f436a A	78	.Sh EXAMPLES
	79	For example:
	80	.Pp
	81	.Dl nl_langinfo(ABDAY_1)
	82	.Pp
	83	would return a pointer to the string
	84	.Qq Li Dom
	85	if the identified language was
	86	Portuguese, and
	87	.Qq Li Sun
	88	if the identified language was English.
ad3c9f2a A	89	.Pp
	90	While the
	91	.Fn nl_langinfo
	92	function uses the current locale, the
	93	.Fn nl_langinfo_l
	94	function may be passed a locale directly. See
	95	.Xr xlocale 3
	96	for more information.
5b2abdfb	97	.Sh SEE ALSO
ad3c9f2a A	98	.Xr setlocale 3 ,
ad3c9f2a A	99	.Xr xlocale 3
5b2abdfb A	100	.Sh STANDARDS
	101	The
	102	.Fn nl_langinfo
	103	function conforms to
	104	.St -susv2 .
	105	.Sh HISTORY
	106	The
	107	.Fn nl_langinfo
	108	function first appeared in
9385eb3d	109	.Fx 4.6 .