d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
3a522ba1bc
freebsd-dev/lib/libc/locale/newlocale.3

126 lines
3.6 KiB
Groff
Raw Normal View History

Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
.\" Copyright (c) 2011 The FreeBSD Foundation
.\" All rights reserved.
.\"
.\" This documentation was written by David Chisnall under sponsorship from
.\" the FreeBSD Foundation.
.\"
.\" 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 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.
.\"
.\" $FreeBSD$
newlocale(3): Fix a memory leak. newlocale() optionally takes a "base" locale, from which components not specified in the mask are inherited. POSIX says that newlocale() may modify "base" and return it, or free "base" and return a newly allocated locale. We were not doing either, so applications which use newlocale() to modify an existing base locale end up leaking memory on FreeBSD. This diff fixes the leak by releasing a reference to the base locale before returning. This is less efficient than modifying "base" directly, but is simpler for an initial bug fix. Also, update the man page to clarify behaviour with respect to "base". PR: 249416 MFC after: 3 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D26522
2020-10-02 18:35:55 +00:00
.Dd October 2, 2020
mdoc: document title should be all caps.
2012-03-25 19:34:05 +00:00
.Dt NEWLOCALE 3
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
.Os
.Sh NAME
.Nm newlocale
Split sentences at period boundaries.
2011-12-02 11:55:09 +00:00
.Nd Creates a new locale
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
Small changes to locale-related man pages. Fix a missing .h and change the recommended include for the POSIX2008 functions from xlocale.h to locale.h. Including xlocale.h is for legacy / Darwin compatibility so should not be encouraged.
2015-04-24 10:17:55 +00:00
.In locale.h
mdoc: fix function type.
2012-04-07 09:26:21 +00:00
.Ft locale_t
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
.Fn newlocale "int mask" "const char * locale" "locale_t base"
.Sh DESCRIPTION
Split sentences at period boundaries.
2011-12-02 11:55:09 +00:00
Creates a new locale, inheriting some properties from an existing locale.
The
.Fa mask
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
defines the components that the new locale will have set to the locale with the
Split sentences at period boundaries.
2011-12-02 11:55:09 +00:00
name specified in the
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
.Fa locale
Split sentences at period boundaries.
2011-12-02 11:55:09 +00:00
parameter.
newlocale(3): Fix a memory leak. newlocale() optionally takes a "base" locale, from which components not specified in the mask are inherited. POSIX says that newlocale() may modify "base" and return it, or free "base" and return a newly allocated locale. We were not doing either, so applications which use newlocale() to modify an existing base locale end up leaking memory on FreeBSD. This diff fixes the leak by releasing a reference to the base locale before returning. This is less efficient than modifying "base" directly, but is simpler for an initial bug fix. Also, update the man page to clarify behaviour with respect to "base". PR: 249416 MFC after: 3 weeks Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D26522
2020-10-02 18:35:55 +00:00
Any components not specified in
.Fa mask
will be inherited from the locale referenced by
.Fa base ,
if
.Fa base
is not
.Dv NULL .
If the call is successful, the state of the locale referenced by
.Fa base
is unspecified, and it must not be accessed.
The special locale
.Dv LC_GLOBAL_LOCALE
may not be specified for
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
.Fa base .
The
.Fa mask
is either
General mdoc(7) and typo fixes. PR: 167734 Submitted by: Nobuyuki Koganemaru (kogane!jp.freebsd.org) MFC after: 3 days
2012-05-11 20:06:46 +00:00
.Fa LC_ALL_MASK ,
Split sentences at period boundaries.
2011-12-02 11:55:09 +00:00
indicating all possible locale components,
or the logical OR of some combination of the following:
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
.Bl -tag -width "LC_MESSAGES_MASK" -offset indent
.It LC_COLLATE_MASK
Split sentences at period boundaries.
2011-12-02 11:55:09 +00:00
The locale for string collation routines.
This controls alphabetic ordering in
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
.Xr strcoll 3
General mdoc(7) and typo fixes. PR: 167734 Submitted by: Nobuyuki Koganemaru (kogane!jp.freebsd.org) MFC after: 3 days
2012-05-11 20:06:46 +00:00
and
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
.Xr strxfrm 3 .
.It LC_CTYPE_MASK
The locale for the
.Xr ctype 3
and
.Xr multibyte 3
Split sentences at period boundaries.
2011-12-02 11:55:09 +00:00
functions.
This controls recognition of upper and lower case, alphabetic or
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
non-alphabetic characters, and so on.
.It LC_MESSAGES_MASK
Set a locale for message catalogs, see
.Xr catopen 3
function.
.It LC_MONETARY_MASK
Set a locale for formatting monetary values; this affects
the
.Xr localeconv 3
function.
.It LC_NUMERIC_MASK
Split sentences at period boundaries.
2011-12-02 11:55:09 +00:00
Set a locale for formatting numbers.
This controls the formatting of decimal points in input and output of floating
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
point numbers in functions such as
.Xr printf 3
and
.Xr scanf 3 ,
as well as values returned by
.Xr localeconv 3 .
.It LC_TIME_MASK
Set a locale for formatting dates and times using the
.Xr strftime 3
function.
.El
This function uses the same rules for loading locale components as
.Xr setlocale 3 .
.Sh RETURN VALUES
Returns a new, valid,
.Fa locale_t
Split sentences at period boundaries.
2011-12-02 11:55:09 +00:00
or NULL if an error occurs.
You must free the returned locale with
Implement xlocale APIs from Darwin, mainly for use by libc++. This adds a load of _l suffixed versions of various standard library functions that use the global locale, making them take an explicit locale parameter. Also adds support for per-thread locales. This work was funded by the FreeBSD Foundation. Please test any code you have that uses the C standard locale functions! Reviewed by: das (gdtoa changes) Approved by: dim (mentor)
2011-11-20 14:45:42 +00:00
.Xr freelocale 3 .
.Sh SEE ALSO
.Xr duplocale 3 ,
.Xr freelocale 3 ,
.Xr localeconv 3 ,
.Xr querylocale 3 ,
.Xr uselocale 3 ,
.Xr xlocale 3
.Sh STANDARDS
Remove an extra comma.
2013-05-03 12:45:45 +00:00
This function conforms to
Also, add a missing period.
2013-05-03 13:27:13 +00:00
.St -p1003.1-2008 .
Reference in New Issue Copy Permalink