<<< Previous | Home | Next >>>

The Open Group Base Specifications Issue 7
IEEE Std 1003.1-2008
Copyright © 2001-2008 The IEEE and The Open Group

#### 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.

#### 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.

> The duplocale() function may fail if:

> [EINVAL]
>   locobj is not a handle for a locale object.

The following sections are informative.

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

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> freelocale , newlocale , uselocale

> XBD <locale.h>

#### CHANGE HISTORY

> First released in Issue 7.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2008 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]

<<< Previous | Home | Next >>>