972baa3747
"UTF2" method. Although UTF-8 and the old UTF2 encoding are compatible for 16-bit characters, the new UTF-8 implementation is much more strict about rejecting malformed input and also handles the full 31 bit range of characters.
353 lines
9.0 KiB
Groff
353 lines
9.0 KiB
Groff
.\" Copyright (c) 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" Donn Seeley at BSDI.
|
|
.\"
|
|
.\" 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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.
|
|
.\"
|
|
.\" @(#)setlocale.3 8.1 (Berkeley) 6/9/93
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd October 5, 2002
|
|
.Dt SETLOCALE 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm setlocale ,
|
|
.Nm localeconv
|
|
.Nd natural language formatting for C
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In locale.h
|
|
.Ft char *
|
|
.Fn setlocale "int category" "const char *locale"
|
|
.Ft struct lconv *
|
|
.Fn localeconv "void"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn setlocale
|
|
function sets the C library's notion
|
|
of natural language formatting style
|
|
for particular sets of routines.
|
|
Each such style is called a
|
|
.Sq locale
|
|
and is invoked using an appropriate name passed as a C string.
|
|
The
|
|
.Fn localeconv
|
|
routine returns the current locale's parameters
|
|
for formatting numbers.
|
|
.Pp
|
|
The
|
|
.Fn setlocale
|
|
function recognizes several categories of routines.
|
|
These are the categories and the sets of routines they select:
|
|
.Pp
|
|
.Bl -tag -width LC_MONETARY
|
|
.It Dv LC_ALL
|
|
Set the entire locale generically.
|
|
.It Dv LC_COLLATE
|
|
Set a locale for string collation routines.
|
|
This controls alphabetic ordering in
|
|
.Fn strcoll
|
|
and
|
|
.Fn strxfrm .
|
|
.It Dv LC_CTYPE
|
|
Set a locale for the
|
|
.Xr ctype 3 ,
|
|
.Xr mbrune 3 ,
|
|
.Xr multibyte 3
|
|
and
|
|
.Xr rune 3
|
|
functions.
|
|
This controls recognition of upper and lower case,
|
|
alphabetic or non-alphabetic characters,
|
|
and so on. The real work is done by the
|
|
.Fn setrunelocale
|
|
function.
|
|
.It Dv LC_MESSAGES
|
|
Set a locale for message catalogs, see
|
|
.Xr catopen 3
|
|
function.
|
|
.It Dv LC_MONETARY
|
|
Set a locale for formatting monetary values;
|
|
this affects the
|
|
.Fn localeconv
|
|
function.
|
|
.It Dv LC_NUMERIC
|
|
Set a locale for formatting numbers.
|
|
This controls the formatting of decimal points
|
|
in input and output of floating point numbers
|
|
in functions such as
|
|
.Fn printf
|
|
and
|
|
.Fn scanf ,
|
|
as well as values returned by
|
|
.Fn localeconv .
|
|
.It Dv LC_TIME
|
|
Set a locale for formatting dates and times using the
|
|
.Fn strftime
|
|
function.
|
|
.El
|
|
.Pp
|
|
Only three locales are defined by default,
|
|
the empty string
|
|
.Li "\&""\|""
|
|
which denotes the native environment, and the
|
|
.Li "\&""C""
|
|
and
|
|
.Li "\&""POSIX""
|
|
locales, which denote the C language environment.
|
|
A
|
|
.Fa locale
|
|
argument of
|
|
.Dv NULL
|
|
causes
|
|
.Fn setlocale
|
|
to return the current locale.
|
|
By default, C programs start in the
|
|
.Li "\&""C""
|
|
locale.
|
|
The only function in the library that sets the locale is
|
|
.Fn setlocale ;
|
|
the locale is never changed as a side effect of some other routine.
|
|
.Pp
|
|
The
|
|
.Fn localeconv
|
|
function returns a pointer to a structure
|
|
which provides parameters for formatting numbers,
|
|
especially currency values:
|
|
.Bd -literal -offset indent
|
|
struct lconv {
|
|
char *decimal_point;
|
|
char *thousands_sep;
|
|
char *grouping;
|
|
char *int_curr_symbol;
|
|
char *currency_symbol;
|
|
char *mon_decimal_point;
|
|
char *mon_thousands_sep;
|
|
char *mon_grouping;
|
|
char *positive_sign;
|
|
char *negative_sign;
|
|
char int_frac_digits;
|
|
char frac_digits;
|
|
char p_cs_precedes;
|
|
char p_sep_by_space;
|
|
char n_cs_precedes;
|
|
char n_sep_by_space;
|
|
char p_sign_posn;
|
|
char n_sign_posn;
|
|
char int_p_cs_precedes;
|
|
char int_n_cs_precedes;
|
|
char int_p_sep_by_space;
|
|
char int_n_sep_by_space;
|
|
char int_p_sign_posn;
|
|
char int_n_sign_posn;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The individual fields have the following meanings:
|
|
.Pp
|
|
.Bl -tag -width mon_decimal_point
|
|
.It Fa decimal_point
|
|
The decimal point character, except for currency values.
|
|
.It Fa thousands_sep
|
|
The separator between groups of digits
|
|
before the decimal point, except for currency values.
|
|
.It Fa grouping
|
|
The sizes of the groups of digits, except for currency values.
|
|
This is a pointer to a vector of integers, each of size
|
|
.Va char ,
|
|
representing group size from low order digit groups
|
|
to high order (right to left).
|
|
The list may be terminated with 0 or
|
|
.Dv CHAR_MAX .
|
|
If the list is terminated with 0,
|
|
the last group size before the 0 is repeated to account for all the digits.
|
|
If the list is terminated with
|
|
.Dv CHAR_MAX ,
|
|
no more grouping is performed.
|
|
.It Fa int_curr_symbol
|
|
The standardized international currency symbol.
|
|
.It Fa currency_symbol
|
|
The local currency symbol.
|
|
.It Fa mon_decimal_point
|
|
The decimal point character for currency values.
|
|
.It Fa mon_thousands_sep
|
|
The separator for digit groups in currency values.
|
|
.It Fa mon_grouping
|
|
Like
|
|
.Fa grouping
|
|
but for currency values.
|
|
.It Fa positive_sign
|
|
The character used to denote nonnegative currency values,
|
|
usually the empty string.
|
|
.It Fa negative_sign
|
|
The character used to denote negative currency values,
|
|
usually a minus sign.
|
|
.It Fa int_frac_digits
|
|
The number of digits after the decimal point
|
|
in an international-style currency value.
|
|
.It Fa frac_digits
|
|
The number of digits after the decimal point
|
|
in the local style for currency values.
|
|
.It Fa p_cs_precedes
|
|
1 if the currency symbol precedes the currency value
|
|
for nonnegative values, 0 if it follows.
|
|
.It Fa p_sep_by_space
|
|
1 if a space is inserted between the currency symbol
|
|
and the currency value for nonnegative values, 0 otherwise.
|
|
.It Fa n_cs_precedes
|
|
Like
|
|
.Fa p_cs_precedes
|
|
but for negative values.
|
|
.It Fa n_sep_by_space
|
|
Like
|
|
.Fa p_sep_by_space
|
|
but for negative values.
|
|
.It Fa p_sign_posn
|
|
The location of the
|
|
.Fa positive_sign
|
|
with respect to a nonnegative quantity and the
|
|
.Fa currency_symbol ,
|
|
coded as follows:
|
|
.Bl -tag -width 3n -compact
|
|
.It Li 0
|
|
Parentheses around the entire string.
|
|
.It Li 1
|
|
Before the string.
|
|
.It Li 2
|
|
After the string.
|
|
.It Li 3
|
|
Just before
|
|
.Fa currency_symbol .
|
|
.It Li 4
|
|
Just after
|
|
.Fa currency_symbol .
|
|
.El
|
|
.It Fa n_sign_posn
|
|
Like
|
|
.Fa p_sign_posn
|
|
but for negative currency values.
|
|
.It Fa int_p_cs_precedes
|
|
Same as
|
|
.Fa p_cs_precedes ,
|
|
but for internationally formatted monetary quantities.
|
|
.It Fa int_n_cs_precedes
|
|
Same as
|
|
.Fa n_cs_precedes ,
|
|
but for internationally formatted monetary quantities.
|
|
.It Fa int_p_sep_by_space
|
|
Same as
|
|
.Fa p_sep_by_space ,
|
|
but for internationally formatted monetary quantities.
|
|
.It Fa int_n_sep_by_space
|
|
Same as
|
|
.Fa n_sep_by_space ,
|
|
but for internationally formatted monetary quantities.
|
|
.It Fa int_p_sign_posn
|
|
Same as
|
|
.Fa p_sign_posn ,
|
|
but for internationally formatted monetary quantities.
|
|
.It Fa int_n_sign_posn
|
|
Same as
|
|
.Fa n_sign_posn ,
|
|
but for internationally formatted monetary quantities.
|
|
.El
|
|
.Pp
|
|
Unless mentioned above,
|
|
an empty string as a value for a field
|
|
indicates a zero length result or
|
|
a value that is not in the current locale.
|
|
A
|
|
.Dv CHAR_MAX
|
|
result similarly denotes an unavailable value.
|
|
.Sh RETURN VALUES
|
|
Upon successful completion,
|
|
.Fn setlocale
|
|
returns the string associated with the specified
|
|
.Fa category
|
|
for the requested
|
|
.Fa locale .
|
|
The
|
|
.Fn setlocale
|
|
function returns
|
|
.Dv NULL
|
|
and fails to change the locale
|
|
if the given combination of
|
|
.Fa category
|
|
and
|
|
.Fa locale
|
|
makes no sense.
|
|
The
|
|
.Fn localeconv
|
|
function returns a pointer to a static object
|
|
which may be altered by later calls to
|
|
.Fn setlocale
|
|
or
|
|
.Fn localeconv .
|
|
.Sh ERRORS
|
|
No errors are defined.
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/share/locale/locale/category -compact
|
|
.It Pa $PATH_LOCALE/ Ns Em locale/category
|
|
.It Pa /usr/share/locale/ Ns Em locale/category
|
|
locale file for the locale
|
|
.Em locale
|
|
and the category
|
|
.Em category .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr colldef 1 ,
|
|
.Xr mklocale 1 ,
|
|
.Xr catopen 3 ,
|
|
.Xr ctype 3 ,
|
|
.Xr mbrune 3 ,
|
|
.Xr multibyte 3 ,
|
|
.Xr rune 3 ,
|
|
.Xr strcoll 3 ,
|
|
.Xr strxfrm 3 ,
|
|
.Xr euc 4 ,
|
|
.Xr utf2 4 ,
|
|
.Xr utf8 5
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn setlocale
|
|
and
|
|
.Fn localeconv
|
|
functions conform to
|
|
.St -isoC-99 .
|
|
.Sh HISTORY
|
|
The
|
|
.Fn setlocale
|
|
and
|
|
.Fn localeconv
|
|
functions first appeared in
|
|
.Bx 4.4 .
|