diff options
Diffstat (limited to 'man3/newlocale.3')
| -rw-r--r-- | man3/newlocale.3 | 356 |
1 files changed, 0 insertions, 356 deletions
diff --git a/man3/newlocale.3 b/man3/newlocale.3 deleted file mode 100644 index 5d10e9a90..000000000 --- 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 (date) "Linux man-pages (unreleased)" -.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> -.PP -.BI "locale_t newlocale(int " category_mask ", const char *" locale , -.BI " locale_t " base ); -.BI "void freelocale(locale_t " locobj ); -.fi -.PP -.RS -4 -Feature Test Macro Requirements for glibc (see -.BR feature_test_macros (7)): -.RE -.PP -.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. -.PP -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. -.PP -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. -.PP -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. -.PP -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. -.PP -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. -.PP -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. -.PP -The following shell sessions show some example runs of this program. -.PP -Set the -.B LC_NUMERIC -category to -.I fr_FR -(French): -.PP -.in +4n -.EX -$ \fB./a.out fr_FR\fP -123456,789 -Fri Mar 7 00:25:08 2014 -.EE -.in -.PP -Set the -.B LC_NUMERIC -category to -.I fr_FR -(French), -and the -.B LC_TIME -category to -.I it_IT -(Italian): -.PP -.in +4n -.EX -$ \fB./a.out fr_FR it_IT\fP -123456,789 -ven 07 mar 2014 00:26:01 CET -.EE -.in -.PP -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): -.PP -.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) |