# newlocale

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



           newlocale — create or modify a locale object
    


## SYNOPSIS



           #include <locale.h>
    
           locale_t newlocale(int _category_mask_ , const char *_locale_ ,
               locale_t _base_);
    


## DESCRIPTION



           The _newlocale_() function shall create a new locale object or
           modify an existing one.  If the _base_ argument is (**locale_t**)0, a
           new locale object shall be created. It is unspecified whether the
           locale object pointed to by _base_ shall be modified, or freed and a
           new locale object created.
    
           The _category_mask_ argument specifies the locale categories to be
           set or modified.  Values for _category_mask_ shall be constructed by
           a bitwise-inclusive OR of the symbolic constants _LC_CTYPE_MASK_ ,
           _LC_NUMERIC_MASK_ , _LC_TIME_MASK_ , _LC_COLLATE_MASK_ , _LC_MONETARY_MASK_ ,
           and _LC_MESSAGES_MASK_ , or any of the implementation-defined mask
           values defined in _< locale.h>_.
    
           For each category with the corresponding bit set in _category_mask_
           the data from the locale named by _locale_ shall be used. In the
           case of modifying an existing locale object, the data from the
           locale named by _locale_ 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 _category_mask_ shall be
           taken from the default locale.
    
           The following preset values of _locale_ are defined for all settings
           of _category_mask_ :
    
           "POSIX"     Specifies the minimal environment for C-language
                       translation called the POSIX locale.
    
           "C"         Equivalent to **"POSIX"**.
    
           ""          Specifies an implementation-defined native
                       environment. This corresponds to the value of the
                       associated environment variables, _LC_*_ and _LANG_ ; see
                       the Base Definitions volume of POSIX.1‐2017, _Chapter_
                       _7_ , _Locale_ and _Chapter 8_ , _Environment Variables_.
    
           If the _base_ argument is not (**locale_t**)0 and the _newlocale_()
           function call succeeds, the contents of _base_ are unspecified.
           Applications shall ensure that they stop using _base_ as a locale
           object before calling _newlocale_().  If the function call fails and
           the _base_ argument is not (**locale_t**)0, the contents of _base_ shall
           remain valid and unchanged.
    
           The behavior is undefined if the _base_ argument is the special
           locale object LC_GLOBAL_LOCALE, or is not a valid locale object
           handle and is not (**locale_t**)0.
    


## RETURN VALUE



           Upon successful completion, the _newlocale_() function shall return
           a handle which the caller may use on subsequent calls to
           _duplocale_(), _freelocale_(), and other functions taking a **locale_t**
           argument.
    
           Upon failure, the _newlocale_() function shall return (**locale_t**)0
           and set _errno_ to indicate the error.
    


## ERRORS



           The _newlocale_() function shall fail if:
    
           **ENOMEM** There is not enough memory available to create the locale
                  object or load the locale data.
    
           **EINVAL** The _category_mask_ contains a bit that does not correspond
                  to a valid category.
    
           **ENOENT** For any of the categories in _category_mask_ , the locale data
                  is not available.
    
           The _newlocale_() function may fail if:
    
           **EINVAL** The _locale_ argument is not a valid string pointer.
    
           _The following sections are informative._
    


## EXAMPLES



       **Constructing a Locale Object from Different Locales**
           The following example shows the construction of a locale where the
           _LC_CTYPE_ category data comes from a locale _loc1_ and the _LC_TIME_
           category data from a locale _loc2_ :
    
               #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;
    
               ...
    
       **Freeing up a Locale Object**
           The following example shows a code fragment to free a locale
           object created by _newlocale_():
    
               #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);
    


## APPLICATION USAGE



           Handles for locale objects created by the _newlocale_() function
           should either be released by a corresponding call to _freelocale_(),
           or be used as a base locale to another _newlocale_() call.
    
           The special locale object LC_GLOBAL_LOCALE must not be passed for
           the _base_ argument, even when returned by the _uselocale_() function.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *