1 files changed, 152 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/duplocale.3p b/upstream/archlinux/man3p/duplocale.3p
new file mode 100644
index 00000000..b158a1a3
--- /dev/null
+++ b/upstream/archlinux/man3p/duplocale.3p
@@ -0,0 +1,152 @@
+'\" et
+.TH DUPLOCALE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+duplocale
+\(em duplicate a locale object
+.SH SYNOPSIS
+.LP
+.nf
+#include <locale.h>
+.P
+locale_t duplocale(locale_t \fIlocobj\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIduplocale\fR()
+function shall create a duplicate copy of the locale object referenced
+by the
+.IR locobj
+argument.
+.P
+If the
+.IR locobj
+argument is LC_GLOBAL_LOCALE,
+\fIduplocale\fR()
+shall create a new locale object containing a copy of the global locale
+determined by the
+\fIsetlocale\fR()
+function.
+.P
+The behavior is undefined if the
+.IR locobj
+argument is not a valid locale object handle.
+.SH "RETURN VALUE"
+Upon successful completion, the
+\fIduplocale\fR()
+function shall return a handle for a new locale object. Otherwise,
+\fIduplocale\fR()
+shall return (\c
+.BR locale_t )0
+and set
+.IR errno
+to indicate the error.
+.SH ERRORS
+The
+\fIduplocale\fR()
+function shall fail if:
+.TP
+.BR ENOMEM
+There is not enough memory available to create the locale object or
+load the locale data.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+.SS "Constructing an Altered Version of an Existing Locale Object"
+.P
+The following example shows a code fragment to create a slightly
+altered version of an existing locale object. The function takes a
+locale object and a locale name and it replaces the
+.IR LC_TIME
+category data in the locale object with that from the named locale.
+.sp
+.RS 4
+.nf
+
+#include <locale.h>
+\&...
+.P
+locale_t
+with_changed_lc_time (locale_t obj, const char *name)
+{
+.P
+    locale_t retval = duplocale (obj);
+    if (retval != (locale_t) 0)
+    {
+        locale_t changed = newlocale (LC_TIME_MASK, name, retval);
+        if (changed == (locale_t) 0)
+            /* An error occurred. Free all allocated resources. */
+            freelocale (retval);
+        retval = changed;
+    }
+    return retval;
+}
+.fi
+.P
+.RE
+.SH "APPLICATION USAGE"
+The use of the
+\fIduplocale\fR()
+function is recommended for situations where a locale object is being
+used in multiple places, and it is possible that the lifetime of the
+locale object might end before all uses are finished. Another reason to
+duplicate a locale object is if a slightly modified form is needed.
+This can be achieved by a call to
+\fInewlocale\fR()
+following the
+\fIduplocale\fR()
+call.
+.P
+As with the
+\fInewlocale\fR()
+function, handles for locale objects created by the
+\fIduplocale\fR()
+function should be released by a corresponding call to
+\fIfreelocale\fR().
+.P
+The
+\fIduplocale\fR()
+function can also be used in conjunction with
+.IR uselocale ((\c
+.BR locale_t )0).
+This returns the locale in effect for the calling thread, but can have
+the value LC_GLOBAL_LOCALE. Passing LC_GLOBAL_LOCALE to functions such as
+\fIisalnum_l\fR()
+results in undefined behavior, but applications can convert it into a
+usable locale object by using
+\fIduplocale\fR().
+.SH RATIONALE
+None.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIfreelocale\fR\^(\|)",
+.IR "\fInewlocale\fR\^(\|)",
+.IR "\fIuselocale\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<locale.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .