Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

duplocale (3C)

Name

duplocale - duplicate a locale object

Synopsis

#include <locale.h>
locale_t duplocale(locale_t locobj);

Description

The duplocale() function creates a duplicate copy of the locale object referenced by the locobj argument.

If the locobj argument is LC_GLOBAL_LOCALE, duplocale() creates 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 Values

Upon successful completion, the duplocale() function returns a handle for a new locale object. Otherwise, duplocale() returns (locale_t)0 and set errno to indicate the error.

Errors

The duplocale() function will fail if:

[ENOMEM]

There is not enough memory available to create the locale object or load the locale data.

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() function.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe
Standard

See Also

freelocale(3C), newlocale(3C), uselocale(3C), attributes(7), standards(7)