NAME

duplocale — duplicate a locale object

SYNOPSIS

[CX] #include <locale.h>

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() 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() following the duplocale() call.

As with the newlocale() function, handles for locale objects created by the duplocale() function should be released by a corresponding call to freelocale().

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() 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, newlocale, uselocale

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.

POSIX.1-2008, Technical Corrigendum 2, XSH/TC2-2008/0084 [753] is applied.