NAME
duplocale —
duplicate a locale object
SYNOPSIS
locale_t duplocale(locale_t locobj);
DESCRIPTION
The duplocale () function shall create a
duplicate copy of the locale object referenced by the
locobj argument.
If the locobj argument is LC_GLOBAL_LOCALE,
duplocale () shall create a new locale object
containing a copy of the global locale determined by the
setlocale(3) function.
The behavior is undefined if the locobj argument is not a valid locale object handle.
RETURN VALUE
Upon successful completion, the duplocale
() function shall return a handle for a new locale object. Otherwise,
duplocale () shall return (
locale_t) 0 and set
errno to
indicate the error.
ERRORS
The duplocale () function shall fail
if:
- [ENOMEM]
- There is not enough memory available to create the locale object or load the locale data.
EXAMPLES
Constructing an Altered Version of an Existing Locale Object
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 LC_TIME category data in the locale object with that from the named locale.
#include <locale.h>
...
locale_t
with_changed_lc_time (locale_t obj, const char *name)
{
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; }
}
APPLICATION USAGE
The use of the duplocale () 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
newlocale(3) following the
duplocale () call.
As with the newlocale(3) function, handles for
locale objects created by the duplocale () function
should be released by a corresponding call to
freelocale(3).
The duplocale () function
can also be used in conjunction with
uselocale ((
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 isalnum_l(3) results
in undefined behavior, but applications can convert it into a usable locale
object by using duplocale ().
RATIONALE
None.
FUTURE DIRECTIONS
None.
SEE ALSO
freelocale(3), newlocale(3), uselocale(3)
XBD <locale.h>
CHANGE HISTORY
First released in Issue 7.
POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0077 [283,301], XSH/TC1-2008/0078 [283], and XSH/TC1-2008/0079 [301] are applied.