2fe8fb192f
There is important information about booting non-ack images in docs/UPDATING. ack/aout-format images can't be built any more, and booting clang/ELF-format ones is a little different. Updating to the new boot monitor is recommended. Changes in this commit: . drop boot monitor -> allowing dropping ack support . facility to copy ELF boot files to /boot so that old boot monitor can still boot fairly easily, see UPDATING . no more ack-format libraries -> single-case libraries . some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases . drop several ack toolchain commands, but not all support commands (e.g. aal is gone but acksize is not yet). . a few libc files moved to netbsd libc dir . new /bin/date as minix date used code in libc/ . test compile fix . harmonize includes . /usr/lib is no longer special: without ack, /usr/lib plays no kind of special bootstrapping role any more and bootstrapping is done exclusively through packages, so releases depend even less on the state of the machine making them now. . rename nbsd_lib* to lib* . reduce mtree
407 lines
11 KiB
Groff
407 lines
11 KiB
Groff
.\" $NetBSD: setlocale.3,v 1.21 2004/01/24 16:58:54 wiz Exp $
|
|
.\"
|
|
.\" 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. 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
|
|
.\"
|
|
.Dd May 30, 2003
|
|
.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:
|
|
.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
|
|
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.
|
|
This controls the selection of message catalogs by the
|
|
.Xr catgets 3
|
|
and
|
|
.Xr gettext 3
|
|
families of functions.
|
|
.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 format of the locale string is described in
|
|
.Xr nls 7 .
|
|
.Pp
|
|
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
|
|
Changing the setting of
|
|
.Dv LC_MESSAGES
|
|
has no effect on catalogs that have already been opened by
|
|
.Xr catopen 3 .
|
|
.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:
|
|
.Bl -tag -width int_p_sep_by_space
|
|
.It Fa decimal_point
|
|
The decimal point character, except for monetary values.
|
|
.It Fa thousands_sep
|
|
The separator between groups of digits
|
|
before the decimal point, except for monetary values.
|
|
.It Fa grouping
|
|
The sizes of the groups of digits, except for monetary 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 (ISO 4217:1995) international currency symbol.
|
|
.It Fa currency_symbol
|
|
The local currency symbol.
|
|
.It Fa mon_decimal_point
|
|
The decimal point character for monetary values.
|
|
.It Fa mon_thousands_sep
|
|
The separator for digit groups in monetary values.
|
|
.It Fa mon_grouping
|
|
Like
|
|
.Fa grouping
|
|
but for monetary values.
|
|
.It Fa positive_sign
|
|
The character used to denote nonnegative monetary values,
|
|
usually the empty string.
|
|
.It Fa negative_sign
|
|
The character used to denote negative monetary values,
|
|
usually a minus sign.
|
|
.It Fa int_frac_digits
|
|
The number of digits after the decimal point
|
|
in an internationally formatted monetary value.
|
|
.It Fa frac_digits
|
|
The number of digits after the decimal point
|
|
in an locally formatted monetary value.
|
|
.It Fa p_cs_precedes
|
|
1 if the currency symbol precedes the monetary 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 monetary 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 .
|
|
.It Fa n_sign_posn
|
|
Like
|
|
.Fa p_sign_posn
|
|
but for negative currency values.
|
|
.It Fa int_p_cs_precedes
|
|
1 if the currency symbol precedes the internationally
|
|
formatted monetary value for nonnegative values, 0 if it follows.
|
|
.It Fa int_n_cs_precedes
|
|
Like
|
|
.Fa int_p_cs_precedes
|
|
but for negative values.
|
|
.It Fa int_p_sep_by_space
|
|
1 if a space is inserted between the currency symbol
|
|
and the internationally formatted monetary value for
|
|
nonnegative values, 0 otherwise.
|
|
.It Fa int_n_sep_by_space
|
|
Like
|
|
.Fa int_p_sep_by_space
|
|
but for negative values.
|
|
.It Fa int_p_sign_posn
|
|
The location of the
|
|
.Fa positive_sign
|
|
with respect to a nonnegative quantity and the
|
|
.Fa currency_symbol ,
|
|
for internationally formatted nonnegative monetary values.
|
|
.It Fa int_n_sign_posn
|
|
Like
|
|
.Fa int_p_sign_posn
|
|
but for negative values.
|
|
.El
|
|
.Pp
|
|
The positional parameters in
|
|
.Fa p_sign_posn ,
|
|
.Fa n_sign_posn ,
|
|
.Fa int_p_sign_posn
|
|
and
|
|
.Fa int_n_sign_posn
|
|
are encoded 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
|
|
.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
|
|
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 EXAMPLES
|
|
The following code illustrates how a program can initialize the
|
|
international environment for one language, while selectively
|
|
modifying the program's locale such that regular expressions and
|
|
string operations can be applied to text recorded in a different
|
|
language:
|
|
.Bd -literal
|
|
setlocale(LC_ALL, "de");
|
|
setlocale(LC_COLLATE, "fr");
|
|
.Ed
|
|
.Pp
|
|
When a process is started, its current locale is set to the C or POSIX
|
|
locale.
|
|
An internationalized program that depends on locale data not defined in
|
|
the C or POSIX locale must invoke the setlocale subroutine in the
|
|
following manner before using any of the locale-specific information:
|
|
.Bd -literal
|
|
setlocale(LC_ALL, "");
|
|
.Ed
|
|
.\" .Sh FILES XXX
|
|
.\" .Bl -tag -width /usr/share/locale/locale/category -compact XXX
|
|
.\" .It Pa $PATH_LOCALE/\fIlocale\fP/\fIcategory\fP XXX
|
|
.\" .It Pa /usr/share/locale/\fIlocale\fP/\fIcategory\fP XXX
|
|
.\" locale file for the locale \fIlocale\fP XXX
|
|
.\" and the category \fIcategory\fP. XXX
|
|
.\" .El
|
|
.Sh SEE ALSO
|
|
.Xr catopen 3 ,
|
|
.Xr gettext 3 ,
|
|
.Xr nl_langinfo 3 ,
|
|
.Xr nls 7
|
|
.\" .Xr strcoll 3 , XXX
|
|
.\" .Xr strxfrm 3 XXX
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn setlocale
|
|
and
|
|
.Fn localeconv
|
|
functions conform to
|
|
.St -ansiC
|
|
and
|
|
.St -isoC-90 .
|
|
.Pp
|
|
The
|
|
.Fa int_p_cs_precedes ,
|
|
.Fa int_n_cs_precedes ,
|
|
.Fa int_p_sep_by_space ,
|
|
.Fa int_n_sep_by_space ,
|
|
.Fa int_p_sign_posn
|
|
and
|
|
.Fa int_n_sign_posn
|
|
members of
|
|
.Ft struct lconv
|
|
were introduced in
|
|
.St -isoC-99 .
|
|
.Sh HISTORY
|
|
The
|
|
.Fn setlocale
|
|
and
|
|
.Fn localeconv
|
|
functions first appeared in
|
|
.Bx 4.4 .
|
|
.Sh BUGS
|
|
The current implementation supports only the
|
|
.Li "\&""C""
|
|
and
|
|
.Li "\&""POSIX""
|
|
locales for all but the
|
|
.Dv LC_CTYPE
|
|
locale.
|
|
.Pp
|
|
In spite of the gnarly currency support in
|
|
.Fn localeconv ,
|
|
the standards don't include any functions
|
|
for generalized currency formatting.
|
|
.Pp
|
|
.Dv LC_COLLATE
|
|
does not make sense for many languages.
|
|
Use of
|
|
.Dv LC_MONETARY
|
|
could lead to misleading results until we have a real time currency
|
|
conversion function.
|
|
.Dv LC_NUMERIC
|
|
and
|
|
.Dv LC_TIME
|
|
are personal choices and should not be wrapped up with the other categories.
|
|
.Pp
|
|
Multibyte locales aren't supported for static binaries.
|