diff options
Diffstat (limited to 'man/man3/duplocale.3')
| -rw-r--r-- | man/man3/duplocale.3 | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/man/man3/duplocale.3 b/man/man3/duplocale.3 new file mode 100644 index 000000000..246af79e9 --- /dev/null +++ b/man/man3/duplocale.3 @@ -0,0 +1,168 @@ +.\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH duplocale 3 (date) "Linux man-pages (unreleased)" +.SH NAME +duplocale \- duplicate a locale object +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <locale.h> +.P +.BI "locale_t duplocale(locale_t " locobj ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR duplocale (): +.nf + Since glibc 2.10: + _XOPEN_SOURCE >= 700 + Before glibc 2.10: + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR duplocale () +function creates a duplicate of the locale object referred to by +.IR locobj . +.P +If +.I locobj +is +.BR LC_GLOBAL_LOCALE , +.BR duplocale () +creates a locale object containing a copy of the global locale +determined by +.BR setlocale (3). +.SH RETURN VALUE +On success, +.BR duplocale () +returns a handle for the new locale object. +On error, it returns +.IR "(locale_t)\ 0", +and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +Insufficient memory to create the duplicate locale object. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +glibc 2.3. +.SH NOTES +Duplicating a locale can serve the following purposes: +.IP \[bu] 3 +To create a copy of a locale object in which one of more categories +are to be modified (using +.BR newlocale (3)). +.IP \[bu] +To obtain a handle for the current locale which can used in +other functions that employ a locale handle, such as +.BR toupper_l (3). +This is done by applying +.BR duplocale () +to the value returned by the following call: +.IP +.in +4n +.EX +loc = uselocale((locale_t) 0); +.EE +.in +.IP +This technique is necessary, because the above +.BR uselocale (3) +call may return the value +.BR LC_GLOBAL_LOCALE , +which results in undefined behavior if passed to functions such as +.BR toupper_l (3). +Calling +.BR duplocale () +can be used to ensure that the +.B LC_GLOBAL_LOCALE +value is converted into a usable locale object. +See EXAMPLES, below. +.P +Each locale object created by +.BR duplocale () +should be deallocated using +.BR freelocale (3). +.SH EXAMPLES +The program below uses +.BR uselocale (3) +and +.BR duplocale () +to obtain a handle for the current locale which is then passed to +.BR toupper_l (3). +The program takes one command-line argument, +a string of characters that is converted to uppercase and +displayed on standard output. +An example of its use is the following: +.P +.in +4n +.EX +$ \fB./a.out abc\fP +ABC +.EE +.in +.SS Program source +\& +.\" SRC BEGIN (duplocale.c) +.EX +#define _XOPEN_SOURCE 700 +#include <ctype.h> +#include <locale.h> +#include <stdio.h> +#include <stdlib.h> +\& +#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e + } while (0) +\& +int +main(int argc, char *argv[]) +{ + locale_t loc, nloc; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s string\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + /* This sequence is necessary, because uselocale() might return + the value LC_GLOBAL_LOCALE, which can\[aq]t be passed as an + argument to toupper_l(). */ +\& + loc = uselocale((locale_t) 0); + if (loc == (locale_t) 0) + errExit("uselocale"); +\& + nloc = duplocale(loc); + if (nloc == (locale_t) 0) + errExit("duplocale"); +\& + for (char *p = argv[1]; *p; p++) + putchar(toupper_l(*p, nloc)); +\& + printf("\en"); +\& + freelocale(nloc); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR freelocale (3), +.BR newlocale (3), +.BR setlocale (3), +.BR uselocale (3), +.BR locale (5), +.BR locale (7) |