duplocale.3p (4243B)
- '\" 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 .