Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 168 insertions, 0 deletions

diff --git a/man/man3/duplocale.3 b/man/man3/duplocale.3
new file mode 100644
index 0000000..6ef42bb
--- /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 2024-05-02 "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)