mirror of https://github.com/mkerrisk/man-pages
372 lines
8.3 KiB
Groff
372 lines
8.3 KiB
Groff
'\" t -*- coding: UTF-8 -*-
|
|
.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH NEWLOCALE 3 2014-03-12 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
newlocale, freelocale \- create, modify, and free a locale object
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <locale.h>
|
|
|
|
.BI "locale_t newlocale(int " category_mask ", const char *" locale ",
|
|
.BI " locale_t " base );
|
|
|
|
.BI "void freelocale(locale_t " locobj );
|
|
.fi
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.BR newlocale (),
|
|
.BR freelocale ():
|
|
.PD 0
|
|
.RS 4
|
|
.TP
|
|
Since glibc 2.10:
|
|
_XOPEN_SOURCE\ >=\ 700
|
|
.TP
|
|
Before glibc 2.10:
|
|
_GNU_SOURCE
|
|
.RE
|
|
.PD
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR newlocale ()
|
|
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
|
|
.IR base :
|
|
.IP * 3
|
|
If
|
|
.I base
|
|
is
|
|
.IR "(locale_t)\ 0" ,
|
|
a new object is created.
|
|
.IP *
|
|
If
|
|
.I base
|
|
refers to valid existing locale object
|
|
(i.e., an object returned by a previous call to
|
|
.BR newlocale ()
|
|
or
|
|
.BR duplocale (3)),
|
|
then that object is modified by the call.
|
|
If the call is successful, the contents of
|
|
.I base
|
|
are unspecified (in particular, the object referred to by
|
|
.I base
|
|
may be freed, and a new object created).
|
|
Therefore, the caller should ensure that it stops using
|
|
.I base
|
|
before the call to
|
|
.BR newlocale (),
|
|
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
|
|
remain valid and unchanged.
|
|
.PP
|
|
If
|
|
.I base
|
|
is the special locale object
|
|
.BR LC_GLOBAL_LOCALE
|
|
(see
|
|
.BR duplocale (3)),
|
|
or is not
|
|
.IR "(locale_t)\ 0"
|
|
and is not a valid locale object handle,
|
|
the behavior is undefined.
|
|
|
|
The
|
|
.I category_mask
|
|
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
|
|
.BR LC_CTYPE_MASK ,
|
|
.BR LC_COLLATE_MASK ,
|
|
.BR LC_MESSAGES_MASK ,
|
|
.BR LC_MONETARY_MASK ,
|
|
.BR LC_NUMERIC_MASK ,
|
|
and
|
|
.BR LC_TIME_MASK .
|
|
|
|
For each category specified in
|
|
.IR category_mask ,
|
|
the locale data from
|
|
.I locale
|
|
will be used in the object returned by
|
|
.BR newlocale ().
|
|
If a new locale object is being created,
|
|
data for all categories not specified in
|
|
.IR category_mask
|
|
is taken from the default ("POSIX") locale.
|
|
|
|
The following preset values of
|
|
.I locale
|
|
are defined for all categories that can be specified in
|
|
.IR category_mask :
|
|
.TP
|
|
"POSIX"
|
|
A minimal locale environment for C language programs.
|
|
.TP
|
|
"C"
|
|
Equivalent to "POSIX".
|
|
.TP
|
|
""
|
|
An implementation-defined native environment
|
|
corresponding to the values of the
|
|
.BR LC_*
|
|
and
|
|
.B LANG
|
|
environment variables (see
|
|
.BR locale (7)).
|
|
.SS freelocale()
|
|
The
|
|
.BR freelocale ()
|
|
function deallocates the resources associated with
|
|
.IR locobj ,
|
|
a locale object previously returned by a call to
|
|
.BR newlocale ()
|
|
or
|
|
.BR duplocale (3).
|
|
If
|
|
.I locobj
|
|
is
|
|
.BR LC_GLOBAL_LOCALE
|
|
or is not valid locale object handle, the results are undefined.
|
|
|
|
Once a locale object has been freed,
|
|
the program should make no further use of it.
|
|
.SH RETURN VALUE
|
|
On success,
|
|
.BR newlocale ()
|
|
returns a handle that can be used in calls to
|
|
.BR duplocale (3),
|
|
.BR freelocale (),
|
|
and other functions that take a
|
|
.I locale_t
|
|
argument.
|
|
On error,
|
|
.BR newlocale ()
|
|
returns
|
|
.IR "(locale_t)\ 0",
|
|
and sets
|
|
.I errno
|
|
to indicate the cause of the error.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EINVAL
|
|
One or more bits in
|
|
.I category_mask
|
|
do not correspond to a valid locale category.
|
|
.TP
|
|
.B EINVAL
|
|
.I locale
|
|
is NULL.
|
|
.TP
|
|
.B ENOENT
|
|
.I locale
|
|
is not a string pointer referring to a valid locale.
|
|
.TP
|
|
.B ENOMEM
|
|
Insufficient memory to create a locale object.
|
|
.SH VERSIONS
|
|
The
|
|
.BR newlocale ()
|
|
and
|
|
.BR freelocale ()
|
|
functions first appeared in version 2.3 of the GNU C library.
|
|
.SH CONFORMING TO
|
|
POSIX.1-2008.
|
|
.SH NOTES
|
|
Each locale object created by
|
|
.BR newlocale ()
|
|
should be deallocated using
|
|
.BR freelocale (3).
|
|
.SH EXAMPLE
|
|
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
|
|
category in a locale object created using
|
|
.BR newlocale ().
|
|
The second command-line argument is optional;
|
|
if it is present, it is used to set the
|
|
.B LC_TIME
|
|
category of the locale object.
|
|
|
|
Having created and initialized the locale object,
|
|
the program then applies it using
|
|
.BR uselocale (3),
|
|
and then tests the effect of the locale changes by:
|
|
.IP 1. 3
|
|
Displaying a floating-point number with a fractional part.
|
|
This output will be affected by the
|
|
.B LC_NUMERIC
|
|
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.
|
|
.IP 2.
|
|
Displaying the date.
|
|
The format and language of the output will be affected by the
|
|
.B LC_TIME
|
|
setting.
|
|
|
|
.PP
|
|
The following shell sessions show some example runs of this program.
|
|
|
|
Set the
|
|
.B LC_NUMERIC
|
|
category to
|
|
.IR fr_FR
|
|
(French):
|
|
.in +4n
|
|
.nf
|
|
|
|
$ \fB./a.out fr_FR\fP
|
|
123456,789
|
|
Fri Mar 7 00:25:08 2014
|
|
.fi
|
|
.in
|
|
|
|
Set the
|
|
.B LC_NUMERIC
|
|
category to
|
|
.IR fr_FR
|
|
(French),
|
|
and the
|
|
.B LC_TIME
|
|
category to
|
|
.IR it_IT
|
|
(Italian):
|
|
.in +4n
|
|
.nf
|
|
|
|
$ \fB./a.out fr_FR it_IT\fP
|
|
123456,789
|
|
ven 07 mar 2014 00:26:01 CET
|
|
.fi
|
|
.in
|
|
|
|
Specify the
|
|
.B LC_TIME
|
|
setting as an empty string,
|
|
which causes the value to be taken from environment variable settings
|
|
(which, here, specify
|
|
.IR mi_NZ ,
|
|
New Zealand Māori):
|
|
.in +4n
|
|
.nf
|
|
|
|
$ LC_ALL=mi_NZ ./a.out fr_FR ""
|
|
123456,789
|
|
Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CET
|
|
.fi
|
|
.SS Program source
|
|
.nf
|
|
#define _XOPEN_SOURCE 700
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <locale.h>
|
|
#include <time.h>
|
|
|
|
#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
|
|
} while (0)
|
|
|
|
int
|
|
main(int argc, char *argv[])
|
|
{
|
|
char buf[100];
|
|
time_t t;
|
|
size_t s;
|
|
struct tm *tm;
|
|
locale_t loc, nloc;
|
|
|
|
if (argc < 2) {
|
|
fprintf(stderr, "Usage: %s locale1 [locale2]\\n", argv[0]);
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
/* Create a new locale object, taking the LC_NUMERIC settings
|
|
from the locale specified in argv[1] */
|
|
|
|
loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0);
|
|
if (loc == (locale_t) 0)
|
|
errExit("newlocale");
|
|
|
|
/* If a second command\-line argument was specified, modify the
|
|
locale object to take the LC_TIME settings from the locale
|
|
specified in argv[2]. We assign the result of this newlocale()
|
|
call to 'nloc' rather than 'loc', since in some cases, we might
|
|
want to preserve 'loc' if this call fails. */
|
|
|
|
if (argc > 2) {
|
|
nloc = newlocale(LC_TIME_MASK, argv[2], loc);
|
|
if (nloc == (locale_t) 0)
|
|
errExit("newlocale");
|
|
loc = nloc;
|
|
}
|
|
|
|
/* Apply the newly created locale to this thread */
|
|
|
|
uselocale(loc);
|
|
|
|
/* Test effect of LC_NUMERIC */
|
|
|
|
printf("%8.3f\\n", 123456.789);
|
|
|
|
/* Test effect of LC_TIME */
|
|
|
|
t = time(NULL);
|
|
tm = localtime(&t);
|
|
if (tm == NULL)
|
|
errExit("time");
|
|
|
|
s = strftime(buf, sizeof(buf), "%c", tm);
|
|
if (s == 0)
|
|
errExit("strftime");
|
|
|
|
printf("%s\\n", buf);
|
|
|
|
/* Free the locale object */
|
|
|
|
freelocale(loc);
|
|
|
|
exit(EXIT_SUCCESS);
|
|
}
|
|
.fi
|
|
.SH SEE ALSO
|
|
.BR locale (1),
|
|
.BR duplocale (3),
|
|
.BR setlocale (3),
|
|
.BR uselocale (3),
|
|
.BR locale (5),
|
|
.BR locale (7)
|