# duplocale

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


## NAME



           duplocale — duplicate a locale object
    


## SYNOPSIS



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


* * *