man/, share/mk/: Move man*/ to man/

[thirdparty/man-pages.git] / man3 / duplocale.3

diff --git a/man3/duplocale.3 b/man3/duplocale.3
deleted file mode 100644 (file)
index 246af79..0000000
--- a/man3/duplocale.3
+++ /dev/null
@@ -1,168 +0,0 @@
-.\" 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)