NEWLOCALE(3)               POSIX Programmer's Manual              NEWLOCALE(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
       newlocale -- create or modify a locale object

SSYYNNOOPPSSIISS
       #include <locale.h>

       locale_t newlocale(int _c_a_t_e_g_o_r_y___m_a_s_k, const char *_l_o_c_a_l_e,
           locale_t _b_a_s_e);

DDEESSCCRRIIPPTTIIOONN
       The _n_e_w_l_o_c_a_l_e() function shall create a new locale object or modify an
       existing one.  If the _b_a_s_e argument is (llooccaallee__tt)0, a new locale object
       shall be created. It is unspecified whether the locale object pointed
       to by _b_a_s_e shall be modified, or freed and a new locale object created.

       The _c_a_t_e_g_o_r_y___m_a_s_k argument specifies the locale categories to be set or
       modified.  Values for _c_a_t_e_g_o_r_y___m_a_s_k shall be constructed by a bitwise-
       inclusive OR of the symbolic constants _L_C___C_T_Y_P_E___M_A_S_K, _L_C___N_U_M_E_R_I_C___M_A_S_K,
       _L_C___T_I_M_E___M_A_S_K, _L_C___C_O_L_L_A_T_E___M_A_S_K, _L_C___M_O_N_E_T_A_R_Y___M_A_S_K, and _L_C___M_E_S_S_A_G_E_S___M_A_S_K,
       or any of the implementation-defined mask values defined in _<_l_o_c_a_l_e_._h_>.

       For each category with the corresponding bit set in _c_a_t_e_g_o_r_y___m_a_s_k the
       data from the locale named by _l_o_c_a_l_e shall be used. In the case of
       modifying an existing locale object, the data from the locale named by
       _l_o_c_a_l_e shall replace the existing data within the locale object. If a
       completely new locale object is created, the data for all sections not
       requested by _c_a_t_e_g_o_r_y___m_a_s_k shall be taken from the default locale.

       The following preset values of _l_o_c_a_l_e are defined for all settings of
       _c_a_t_e_g_o_r_y___m_a_s_k:

       "POSIX"     Specifies the minimal environment for C-language
                   translation called the POSIX locale.

       "C"         Equivalent to ""PPOOSSIIXX"".

       ""          Specifies an implementation-defined native environment.
                   This corresponds to the value of the associated environment
                   variables, _L_C___* and _L_A_N_G; see the Base Definitions volume
                   of POSIX.1-2017, _C_h_a_p_t_e_r _7, _L_o_c_a_l_e and _C_h_a_p_t_e_r _8,
                   _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s.

       If the _b_a_s_e argument is not (llooccaallee__tt)0 and the _n_e_w_l_o_c_a_l_e() function
       call succeeds, the contents of _b_a_s_e are unspecified. Applications shall
       ensure that they stop using _b_a_s_e as a locale object before calling
       _n_e_w_l_o_c_a_l_e().  If the function call fails and the _b_a_s_e argument is not
       (llooccaallee__tt)0, the contents of _b_a_s_e shall remain valid and unchanged.

       The behavior is undefined if the _b_a_s_e argument is the special locale
       object LC_GLOBAL_LOCALE, or is not a valid locale object handle and is
       not (llooccaallee__tt)0.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, the _n_e_w_l_o_c_a_l_e() function shall return a
       handle which the caller may use on subsequent calls to _d_u_p_l_o_c_a_l_e(),
       _f_r_e_e_l_o_c_a_l_e(), and other functions taking a llooccaallee__tt argument.

       Upon failure, the _n_e_w_l_o_c_a_l_e() function shall return (llooccaallee__tt)0 and set
       _e_r_r_n_o to indicate the error.

EERRRROORRSS
       The _n_e_w_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.

       EEIINNVVAALL The _c_a_t_e_g_o_r_y___m_a_s_k contains a bit that does not correspond to a
              valid category.

       EENNOOEENNTT For any of the categories in _c_a_t_e_g_o_r_y___m_a_s_k, the locale data is
              not available.

       The _n_e_w_l_o_c_a_l_e() function may fail if:

       EEIINNVVAALL The _l_o_c_a_l_e argument is not a valid string pointer.

       _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 aa LLooccaallee OObbjjeecctt ffrroomm DDiiffffeerreenntt LLooccaalleess
       The following example shows the construction of a locale where the
       _L_C___C_T_Y_P_E category data comes from a locale _l_o_c_1 and the _L_C___T_I_M_E
       category data from a locale _l_o_c_2:


           #include <locale.h>
           ...
           locale_t loc, new_loc;

           /* Get the "loc1" data. */

           loc = newlocale (LC_CTYPE_MASK, "loc1", (locale_t)0);
           if (loc == (locale_t) 0)
               abort ();

           /* Get the "loc2" data. */

           new_loc = newlocale (LC_TIME_MASK, "loc2", loc);
           if (new_loc != (locale_t) 0)
               /* We don t abort if this fails. In this case this
                  simply used to unchanged locale object. */
               loc = new_loc;

           ...

   FFrreeeeiinngg uupp aa LLooccaallee OObbjjeecctt
       The following example shows a code fragment to free a locale object
       created by _n_e_w_l_o_c_a_l_e():


           #include <locale.h>
           ...

           /* Every locale object allocated with newlocale() should be
            * freed using freelocale():
            */

           locale_t loc;

           /* Get the locale. */

           loc = newlocale (LC_CTYPE_MASK | LC_TIME_MASK, "locname", (locale_t)0);

           /* ... Use the locale object ... */
           ...

           /* Free the locale object resources. */
           freelocale (loc);

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Handles for locale objects created by the _n_e_w_l_o_c_a_l_e() function should
       either be released by a corresponding call to _f_r_e_e_l_o_c_a_l_e(), or be used
       as a base locale to another _n_e_w_l_o_c_a_l_e() call.

       The special locale object LC_GLOBAL_LOCALE must not be passed for the
       _b_a_s_e argument, even when returned by the _u_s_e_l_o_c_a_l_e() function.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _d_u_p_l_o_c_a_l_e(), _f_r_e_e_l_o_c_a_l_e(), _u_s_e_l_o_c_a_l_e()

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _7, _L_o_c_a_l_e, _C_h_a_p_t_e_r
       _8, _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s, <<llooccaallee..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  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.opengroup.org/unix/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                  2017                         NEWLOCALE(3)
