DUPLOCALE(3)               POSIX Programmer's Manual              DUPLOCALE(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       duplocale -- duplicate a locale object

SSYYNNOOPPSSIISS
       #include <locale.h>

       locale_t duplocale(locale_t _l_o_c_o_b_j);

DDEESSCCRRIIPPTTIIOONN
       The _d_u_p_l_o_c_a_l_e() function shall create a duplicate copy of the locale
       object referenced by the _l_o_c_o_b_j argument.

       If the _l_o_c_o_b_j argument is LC_GLOBAL_LOCALE, _d_u_p_l_o_c_a_l_e() shall create a
       new locale object containing a copy of the global locale determined by
       the _s_e_t_l_o_c_a_l_e() function.

       The behavior is undefined if the _l_o_c_o_b_j argument is not a valid locale
       object handle.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, the _d_u_p_l_o_c_a_l_e() function shall return a
       handle for a new locale object. Otherwise, _d_u_p_l_o_c_a_l_e() shall return
       (llooccaallee__tt)0 and set _e_r_r_n_o to indicate the error.

EERRRROORRSS
       The _d_u_p_l_o_c_a_l_e() function shall fail if:

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

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   CCoonnssttrruuccttiinngg aann AAlltteerreedd VVeerrssiioonn ooff aann EExxiissttiinngg LLooccaallee OObbjjeecctt
       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 _L_C___T_I_M_E category
       data in the locale object with that from the named locale.

           ##iinncclluuddee <<llooccaallee..hh>>
           ......

           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; }
           }

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The use of the _d_u_p_l_o_c_a_l_e() 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 _n_e_w_l_o_c_a_l_e()
       following the _d_u_p_l_o_c_a_l_e() call.

       As with the _n_e_w_l_o_c_a_l_e() function, handles for locale objects created by
       the _d_u_p_l_o_c_a_l_e() function should be released by a corresponding call to
       _f_r_e_e_l_o_c_a_l_e().

       The _d_u_p_l_o_c_a_l_e() function can also be used in conjunction with
       _u_s_e_l_o_c_a_l_e((llooccaallee__tt)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 _i_s_a_l_n_u_m___l() results in undefined
       behavior, but applications can convert it into a usable locale object
       by using _d_u_p_l_o_c_a_l_e().

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _f_r_e_e_l_o_c_a_l_e(), _n_e_w_l_o_c_a_l_e(), _u_s_e_l_o_c_a_l_e()

       The Base Definitions volume of POSIX.1-2008, <<llooccaallee..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                         DUPLOCALE(3)
