man-pages/man3/newlocale.3.html
2021-03-31 01:06:50 +01:00

537 lines
13 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of NEWLOCALE</TITLE>
</HEAD><BODY>
<H1>NEWLOCALE</H1>
Section: Linux Programmer's Manual (3)<BR>Updated: 2019-03-06<BR><A HREF="#index">Index</A>
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>
newlocale, freelocale - create, modify, and free a locale object
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>
<PRE>
<B>#include &lt;<A HREF="file:///usr/include/locale.h">locale.h</A>&gt;</B>
<B>locale_t newlocale(int </B><I>category_mask</I><B>, const char *</B><I>locale</I><B>,</B>
<B> locale_t </B><I>base</I><B>);</B>
<B>void freelocale(locale_t </B><I>locobj</I><B>);</B>
</PRE>
<P>
Feature Test Macro Requirements for glibc (see
<B><A HREF="/cgi-bin/man/man2html?7+feature_test_macros">feature_test_macros</A></B>(7)):
<P>
<B>newlocale</B>(),
<B>freelocale</B>():
<DL COMPACT><DT id="1"><DD>
<DL COMPACT>
<DT id="2">Since glibc 2.10:<DD>
_XOPEN_SOURCE&nbsp;&gt;=&nbsp;700
<DT id="3">Before glibc 2.10:<DD>
_GNU_SOURCE
</DL>
</DL>
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>
The
<B>newlocale</B>()
function creates a new locale object, or modifies an existing object,
returning a reference to the new or modified object as the function result.
Whether the call creates a new object or modifies an existing object
is determined by the value of
<I>base</I>:
<DL COMPACT>
<DT id="4">*<DD>
If
<I>base</I>
is
<I>(locale_t)&nbsp;0</I>,
a new object is created.
<DT id="5">*<DD>
If
<I>base</I>
refers to valid existing locale object
(i.e., an object returned by a previous call to
<B>newlocale</B>()
or
<B><A HREF="/cgi-bin/man/man2html?3+duplocale">duplocale</A></B>(3)),
then that object is modified by the call.
If the call is successful, the contents of
<I>base</I>
are unspecified (in particular, the object referred to by
<I>base</I>
may be freed, and a new object created).
Therefore, the caller should ensure that it stops using
<I>base</I>
before the call to
<B>newlocale</B>(),
and should subsequently refer to the modified object via the
reference returned as the function result.
If the call fails, the contents of
<I>base</I>
remain valid and unchanged.
</DL>
<P>
If
<I>base</I>
is the special locale object
<B>LC_GLOBAL_LOCALE</B>
(see
<B><A HREF="/cgi-bin/man/man2html?3+duplocale">duplocale</A></B>(3)),
or is not
<I>(locale_t)&nbsp;0</I>
and is not a valid locale object handle,
the behavior is undefined.
<P>
The
<I>category_mask</I>
argument is a bit mask that specifies the locale categories
that are to be set in a newly created locale object
or modified in an existing object.
The mask is constructed by a bitwise OR of the constants
<B>LC_ADDRESS_MASK</B>,
<B>LC_CTYPE_MASK</B>,
<B>LC_COLLATE_MASK</B>,
<B>LC_IDENTIFICATION_MASK</B>,
<B>LC_MEASUREMENT_MASK</B>,
<B>LC_MESSAGES_MASK</B>,
<B>LC_MONETARY_MASK</B>,
<B>LC_NUMERIC_MASK</B>,
<B>LC_NAME_MASK</B>,
<B>LC_PAPER_MASK</B>,
<B>LC_TELEPHONE_MASK</B>,
and
<B>LC_TIME_MASK</B>.
Alternatively, the mask can be specified as
<B>LC_ALL_MASK</B>,
which is equivalent to ORing all of the preceding constants.
<P>
For each category specified in
<I>category_mask</I>,
the locale data from
<I>locale</I>
will be used in the object returned by
<B>newlocale</B>().
If a new locale object is being created,
data for all categories not specified in
<I>category_mask</I>
is taken from the default (&quot;POSIX&quot;) locale.
<P>
The following preset values of
<I>locale</I>
are defined for all categories that can be specified in
<I>category_mask</I>:
<DL COMPACT>
<DT id="6">&quot;POSIX&quot;<DD>
A minimal locale environment for C language programs.
<DT id="7">&quot;C&quot;<DD>
Equivalent to &quot;POSIX&quot;.
<DT id="8">&quot;&quot;<DD>
An implementation-defined native environment
corresponding to the values of the
<B>LC_*</B>
and
<B>LANG</B>
environment variables (see
<B><A HREF="/cgi-bin/man/man2html?7+locale">locale</A></B>(7)).
</DL>
<A NAME="lbAE">&nbsp;</A>
<H3>freelocale()</H3>
The
<B>freelocale</B>()
function deallocates the resources associated with
<I>locobj</I>,
a locale object previously returned by a call to
<B>newlocale</B>()
or
<B><A HREF="/cgi-bin/man/man2html?3+duplocale">duplocale</A></B>(3).
If
<I>locobj</I>
is
<B>LC_GLOBAL_LOCALE</B>
or is not valid locale object handle, the results are undefined.
<P>
Once a locale object has been freed,
the program should make no further use of it.
<A NAME="lbAF">&nbsp;</A>
<H2>RETURN VALUE</H2>
On success,
<B>newlocale</B>()
returns a handle that can be used in calls to
<B><A HREF="/cgi-bin/man/man2html?3+duplocale">duplocale</A></B>(3),
<B>freelocale</B>(),
and other functions that take a
<I>locale_t</I>
argument.
On error,
<B>newlocale</B>()
returns
<I>(locale_t)&nbsp;0,</I>
and sets
<I>errno</I>
to indicate the cause of the error.
<A NAME="lbAG">&nbsp;</A>
<H2>ERRORS</H2>
<DL COMPACT>
<DT id="9"><B>EINVAL</B>
<DD>
One or more bits in
<I>category_mask</I>
do not correspond to a valid locale category.
<DT id="10"><B>EINVAL</B>
<DD>
<I>locale</I>
is NULL.
<DT id="11"><B>ENOENT</B>
<DD>
<I>locale</I>
is not a string pointer referring to a valid locale.
<DT id="12"><B>ENOMEM</B>
<DD>
Insufficient memory to create a locale object.
</DL>
<A NAME="lbAH">&nbsp;</A>
<H2>VERSIONS</H2>
The
<B>newlocale</B>()
and
<B>freelocale</B>()
functions first appeared in version 2.3 of the GNU C library.
<A NAME="lbAI">&nbsp;</A>
<H2>CONFORMING TO</H2>
POSIX.1-2008.
<A NAME="lbAJ">&nbsp;</A>
<H2>NOTES</H2>
Each locale object created by
<B>newlocale</B>()
should be deallocated using
<B>freelocale</B>().
<A NAME="lbAK">&nbsp;</A>
<H2>EXAMPLE</H2>
The program below takes up to two command-line arguments,
which each identify locales.
The first argument is required, and is used to set the
<B>LC_NUMERIC</B>
category in a locale object created using
<B>newlocale</B>().
The second command-line argument is optional;
if it is present, it is used to set the
<B>LC_TIME</B>
category of the locale object.
<P>
Having created and initialized the locale object,
the program then applies it using
<B><A HREF="/cgi-bin/man/man2html?3+uselocale">uselocale</A></B>(3),
and then tests the effect of the locale changes by:
<DL COMPACT>
<DT id="13">1.<DD>
Displaying a floating-point number with a fractional part.
This output will be affected by the
<B>LC_NUMERIC</B>
setting.
In many European-language locales,
the fractional part of the number is separated from the integer part
using a comma, rather than a period.
<DT id="14">2.<DD>
Displaying the date.
The format and language of the output will be affected by the
<B>LC_TIME</B>
setting.
</DL>
<P>
The following shell sessions show some example runs of this program.
<P>
Set the
<B>LC_NUMERIC</B>
category to
<I>fr_FR</I>
(French):
<P>
$ <B>./a.out fr_FR</B>
123456,789
Fri Mar 7 00:25:08 2014
<P>
Set the
<B>LC_NUMERIC</B>
category to
<I>fr_FR</I>
(French),
and the
<B>LC_TIME</B>
category to
<I>it_IT</I>
(Italian):
<P>
$ <B>./a.out fr_FR it_IT</B>
123456,789
ven 07 mar 2014 00:26:01 CET
<P>
Specify the
<B>LC_TIME</B>
setting as an empty string,
which causes the value to be taken from environment variable settings
(which, here, specify
<I>mi_NZ</I>,
New Zealand Māori):
<P>
$ LC_ALL=mi_NZ ./a.out fr_FR &quot;&quot;
123456,789
Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CET
<A NAME="lbAL">&nbsp;</A>
<H3>Program source</H3>
#define _XOPEN_SOURCE 700
#include &lt;<A HREF="file:///usr/include/stdio.h">stdio.h</A>&gt;
#include &lt;<A HREF="file:///usr/include/stdlib.h">stdlib.h</A>&gt;
#include &lt;<A HREF="file:///usr/include/locale.h">locale.h</A>&gt;
#include &lt;<A HREF="file:///usr/include/time.h">time.h</A>&gt;
<P>
#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;while&nbsp;(0)
<P>
int
main(int argc, char *argv[])
{
<BR>&nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;buf[100];
<BR>&nbsp;&nbsp;&nbsp;&nbsp;time_t&nbsp;t;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;size_t&nbsp;s;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;struct&nbsp;tm&nbsp;*tm;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;locale_t&nbsp;loc,&nbsp;nloc;
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(argc&nbsp;&lt;&nbsp;2)&nbsp;{
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,&nbsp;&quot;Usage:&nbsp;%s&nbsp;locale1&nbsp;[locale2]\n&quot;,&nbsp;argv[0]);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(EXIT_FAILURE);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;}
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Create&nbsp;a&nbsp;new&nbsp;locale&nbsp;object,&nbsp;taking&nbsp;the&nbsp;LC_NUMERIC&nbsp;settings
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;from&nbsp;the&nbsp;locale&nbsp;specified&nbsp;in&nbsp;argv[1]&nbsp;*/
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;loc&nbsp;=&nbsp;newlocale(LC_NUMERIC_MASK,&nbsp;argv[1],&nbsp;(locale_t)&nbsp;0);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(loc&nbsp;==&nbsp;(locale_t)&nbsp;0)
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;errExit(&quot;newlocale&quot;);
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;If&nbsp;a&nbsp;second&nbsp;command-line&nbsp;argument&nbsp;was&nbsp;specified,&nbsp;modify&nbsp;the
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;locale&nbsp;object&nbsp;to&nbsp;take&nbsp;the&nbsp;LC_TIME&nbsp;settings&nbsp;from&nbsp;the&nbsp;locale
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;specified&nbsp;in&nbsp;argv[2].&nbsp;We&nbsp;assign&nbsp;the&nbsp;result&nbsp;of&nbsp;this&nbsp;newlocale()
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;call&nbsp;to&nbsp;'nloc'&nbsp;rather&nbsp;than&nbsp;'loc',&nbsp;since&nbsp;in&nbsp;some&nbsp;cases,&nbsp;we&nbsp;might
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;want&nbsp;to&nbsp;preserve&nbsp;'loc'&nbsp;if&nbsp;this&nbsp;call&nbsp;fails.&nbsp;*/
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(argc&nbsp;&gt;&nbsp;2)&nbsp;{
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;nloc&nbsp;=&nbsp;newlocale(LC_TIME_MASK,&nbsp;argv[2],&nbsp;loc);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(nloc&nbsp;==&nbsp;(locale_t)&nbsp;0)
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;errExit(&quot;newlocale&quot;);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;loc&nbsp;=&nbsp;nloc;
<BR>&nbsp;&nbsp;&nbsp;&nbsp;}
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Apply&nbsp;the&nbsp;newly&nbsp;created&nbsp;locale&nbsp;to&nbsp;this&nbsp;thread&nbsp;*/
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;uselocale(loc);
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Test&nbsp;effect&nbsp;of&nbsp;LC_NUMERIC&nbsp;*/
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;printf(&quot;%8.3f\n&quot;,&nbsp;123456.789);
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Test&nbsp;effect&nbsp;of&nbsp;LC_TIME&nbsp;*/
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;t&nbsp;=&nbsp;time(NULL);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;tm&nbsp;=&nbsp;localtime(&amp;t);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(tm&nbsp;==&nbsp;NULL)
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;errExit(&quot;time&quot;);
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;s&nbsp;=&nbsp;strftime(buf,&nbsp;sizeof(buf),&nbsp;&quot;%c&quot;,&nbsp;tm);
<BR>&nbsp;&nbsp;&nbsp;&nbsp;if&nbsp;(s&nbsp;==&nbsp;0)
<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;errExit(&quot;strftime&quot;);
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;printf(&quot;%s\n&quot;,&nbsp;buf);
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Free&nbsp;the&nbsp;locale&nbsp;object&nbsp;*/
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;freelocale(loc);
<P>
<BR>&nbsp;&nbsp;&nbsp;&nbsp;exit(EXIT_SUCCESS);
}
<A NAME="lbAM">&nbsp;</A>
<H2>SEE ALSO</H2>
<B><A HREF="/cgi-bin/man/man2html?1+locale">locale</A></B>(1),
<B><A HREF="/cgi-bin/man/man2html?3+duplocale">duplocale</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+setlocale">setlocale</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+uselocale">uselocale</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?5+locale">locale</A></B>(5),
<B><A HREF="/cgi-bin/man/man2html?7+locale">locale</A></B>(7)
<A NAME="lbAN">&nbsp;</A>
<H2>COLOPHON</H2>
This page is part of release 5.05 of the Linux
<I>man-pages</I>
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
<P>
<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT id="15"><A HREF="#lbAB">NAME</A><DD>
<DT id="16"><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT id="17"><A HREF="#lbAD">DESCRIPTION</A><DD>
<DL>
<DT id="18"><A HREF="#lbAE">freelocale()</A><DD>
</DL>
<DT id="19"><A HREF="#lbAF">RETURN VALUE</A><DD>
<DT id="20"><A HREF="#lbAG">ERRORS</A><DD>
<DT id="21"><A HREF="#lbAH">VERSIONS</A><DD>
<DT id="22"><A HREF="#lbAI">CONFORMING TO</A><DD>
<DT id="23"><A HREF="#lbAJ">NOTES</A><DD>
<DT id="24"><A HREF="#lbAK">EXAMPLE</A><DD>
<DL>
<DT id="25"><A HREF="#lbAL">Program source</A><DD>
</DL>
<DT id="26"><A HREF="#lbAM">SEE ALSO</A><DD>
<DT id="27"><A HREF="#lbAN">COLOPHON</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 00:05:49 GMT, March 31, 2021
</BODY>
</HTML>