summaryrefslogtreecommitdiffstats
path: root/man3/newlocale.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/newlocale.3')
-rw-r--r--man3/newlocale.3356
1 files changed, 0 insertions, 356 deletions
diff --git a/man3/newlocale.3 b/man3/newlocale.3
deleted file mode 100644
index 4bbaf14..0000000
--- a/man3/newlocale.3
+++ /dev/null
@@ -1,356 +0,0 @@
-.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.TH newlocale 3 2023-10-31 "Linux man-pages 6.7"
-.SH NAME
-newlocale, freelocale \- create, modify, and free a locale object
-.SH LIBRARY
-Standard C library
-.RI ( libc ", " \-lc )
-.SH SYNOPSIS
-.nf
-.B #include <locale.h>
-.P
-.BI "locale_t newlocale(int " category_mask ", const char *" locale ,
-.BI " locale_t " base );
-.BI "void freelocale(locale_t " locobj );
-.fi
-.P
-.RS -4
-Feature Test Macro Requirements for glibc (see
-.BR feature_test_macros (7)):
-.RE
-.P
-.BR newlocale (),
-.BR freelocale ():
-.nf
- Since glibc 2.10:
- _XOPEN_SOURCE >= 700
- Before glibc 2.10:
- _GNU_SOURCE
-.fi
-.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 \[bu] 3
-If
-.I base
-is
-.IR "(locale_t)\ 0" ,
-a new object is created.
-.IP \[bu]
-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.
-.P
-If
-.I base
-is the special locale object
-.B LC_GLOBAL_LOCALE
-(see
-.BR duplocale (3)),
-or is not
-.I (locale_t)\ 0
-and is not a valid locale object handle,
-the behavior is undefined.
-.P
-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_ADDRESS_MASK ,
-.BR LC_CTYPE_MASK ,
-.BR LC_COLLATE_MASK ,
-.BR LC_IDENTIFICATION_MASK ,
-.BR LC_MEASUREMENT_MASK ,
-.BR LC_MESSAGES_MASK ,
-.BR LC_MONETARY_MASK ,
-.BR LC_NUMERIC_MASK ,
-.BR LC_NAME_MASK ,
-.BR LC_PAPER_MASK ,
-.BR LC_TELEPHONE_MASK ,
-and
-.BR LC_TIME_MASK .
-Alternatively, the mask can be specified as
-.BR LC_ALL_MASK ,
-which is equivalent to ORing all of the preceding constants.
-.P
-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
-.I category_mask
-is taken from the default ("POSIX") locale.
-.P
-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
-.B 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
-.B LC_GLOBAL_LOCALE
-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.
-.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 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 STANDARDS
-POSIX.1-2008.
-.SH HISTORY
-glibc 2.3.
-.SH NOTES
-Each locale object created by
-.BR newlocale ()
-should be deallocated using
-.BR freelocale ().
-.SH EXAMPLES
-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.
-.P
-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) 5
-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.
-.P
-The following shell sessions show some example runs of this program.
-.P
-Set the
-.B LC_NUMERIC
-category to
-.I fr_FR
-(French):
-.P
-.in +4n
-.EX
-$ \fB./a.out fr_FR\fP
-123456,789
-Fri Mar 7 00:25:08 2014
-.EE
-.in
-.P
-Set the
-.B LC_NUMERIC
-category to
-.I fr_FR
-(French),
-and the
-.B LC_TIME
-category to
-.I it_IT
-(Italian):
-.P
-.in +4n
-.EX
-$ \fB./a.out fr_FR it_IT\fP
-123456,789
-ven 07 mar 2014 00:26:01 CET
-.EE
-.in
-.P
-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):
-.P
-.in +4n
-.EX
-$ LC_ALL=mi_NZ ./a.out fr_FR ""
-123456,789
-Te Paraire, te 07 o Poutū\-te\-rangi, 2014 00:38:44 CET
-.EE
-.in
-.SS Program source
-.\" SRC BEGIN (newlocale.c)
-.EX
-#define _XOPEN_SOURCE 700
-#include <locale.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <time.h>
-\&
-#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
- } 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]\en", 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 \[aq]nloc\[aq] rather than \[aq]loc\[aq], since in some cases, we might
- want to preserve \[aq]loc\[aq] 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\en", 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\en", buf);
-\&
- /* Free the locale object. */
-\&
- uselocale(LC_GLOBAL_LOCALE); /* So \[aq]loc\[aq] is no longer in use */
- freelocale(loc);
-\&
- exit(EXIT_SUCCESS);
-}
-.EE
-.\" SRC END
-.SH SEE ALSO
-.BR locale (1),
-.BR duplocale (3),
-.BR setlocale (3),
-.BR uselocale (3),
-.BR locale (5),
-.BR locale (7)