Movatterモバイル変換

SYNOPSIS top

#include <locale.h>locale_t newlocale(intcategory_mask, const char *locale,locale_tbase);void freelocale(locale_tlocobj); Feature Test Macro Requirements for glibc (seefeature_test_macros(7)):newlocale(),freelocale(): Since glibc 2.10: _XOPEN_SOURCE >= 700 Before glibc 2.10: _GNU_SOURCE

DESCRIPTION top

Thenewlocale() function creates a new locale object, or modifies an existing object, returning a reference to the new or modified object as the function result. Whether the call creates a new object or modifies an existing object is determined by the value ofbase: • Ifbase is(locale_t) 0, a new object is created. • Ifbase refers to valid existing locale object (i.e., an object returned by a previous call tonewlocale() orduplocale(3)), then that object is modified by the call. If the call is successful, the contents ofbase are unspecified (in particular, the object referred to bybase may be freed, and a new object created). Therefore, the caller should ensure that it stops usingbase before the call tonewlocale(), and should subsequently refer to the modified object via the reference returned as the function result. If the call fails, the contents ofbase remain valid and unchanged. Ifbase is the special locale objectLC_GLOBAL_LOCALE(seeduplocale(3)), or is not(locale_t) 0 and is not a valid locale object handle, the behavior is undefined. Thecategory_mask argument is a bit mask that specifies the locale categories that are to be set in a newly created locale object or modified in an existing object. The mask is constructed by a bitwise OR of the constantsLC_ADDRESS_MASK,LC_CTYPE_MASK,LC_COLLATE_MASK,LC_IDENTIFICATION_MASK,LC_MEASUREMENT_MASK,LC_MESSAGES_MASK,LC_MONETARY_MASK,LC_NUMERIC_MASK,LC_NAME_MASK,LC_PAPER_MASK,LC_TELEPHONE_MASK, andLC_TIME_MASK. Alternatively, the mask can be specified asLC_ALL_MASK, which is equivalent to ORing all of the preceding constants. For each category specified incategory_mask, the locale data fromlocale will be used in the object returned bynewlocale(). If a new locale object is being created, data for all categories not specified incategory_mask is taken from the default ("POSIX") locale. The following preset values oflocale are defined for all categories that can be specified incategory_mask: "POSIX" A minimal locale environment for C language programs. "C" Equivalent to "POSIX". "" An implementation-defined native environment corresponding to the values of theLC_*andLANGenvironment variables (seelocale(7)).freelocale() Thefreelocale() function deallocates the resources associated withlocobj, a locale object previously returned by a call tonewlocale() orduplocale(3). Iflocobj isLC_GLOBAL_LOCALEor is not valid locale object handle, the results are undefined. Once a locale object has been freed, the program should make no further use of it.

On success,newlocale() returns a handle that can be used in calls toduplocale(3),freelocale(), and other functions that take alocale_t argument. On error,newlocale() returns(locale_t) 0, and setserrno to indicate the error.

EINVALOne or more bits incategory_mask do not correspond to a valid locale category.EINVALlocale is NULL.ENOENTlocale is not a string pointer referring to a valid locale.ENOMEMInsufficient memory to create a locale object.

EXAMPLES top

The program below takes up to two command-line arguments, which each identify locales. The first argument is required, and is used to set theLC_NUMERICcategory in a locale object created usingnewlocale(). The second command-line argument is optional; if it is present, it is used to set theLC_TIMEcategory of the locale object. Having created and initialized the locale object, the program then applies it usinguselocale(3), and then tests the effect of the locale changes by: (1) Displaying a floating-point number with a fractional part. This output will be affected by theLC_NUMERICsetting. In many European-language locales, the fractional part of the number is separated from the integer part using a comma, rather than a period. (2) Displaying the date. The format and language of the output will be affected by theLC_TIMEsetting. The following shell sessions show some example runs of this program. Set theLC_NUMERICcategory tofr_FR (French): $./a.out fr_FR; 123456,789 Fri Mar 7 00:25:08 2014 Set theLC_NUMERICcategory tofr_FR (French), and theLC_TIME category toit_IT (Italian): $./a.out fr_FR it_IT; 123456,789 ven 07 mar 2014 00:26:01 CET Specify theLC_TIMEsetting as an empty string, which causes the value to be taken from environment variable settings (which, here, specifymi_NZ, New Zealand Māori): $ LC_ALL=mi_NZ ./a.out fr_FR "" 123456,789 Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CETProgram source #define _XOPEN_SOURCE 700 #include <locale.h> #include <stdio.h> #include <stdlib.h> #include <time.h> #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \ } while (0) int main(int argc, char *argv[]) { char buf[100]; time_t t; size_t s; struct tm *tm; locale_t loc, nloc; if (argc < 2) { fprintf(stderr, "Usage: %s locale1 [locale2]\n", argv[0]); exit(EXIT_FAILURE); } /* Create a new locale object, taking the LC_NUMERIC settings from the locale specified in argv[1]. */ loc = newlocale(LC_NUMERIC_MASK, argv[1], (locale_t) 0); if (loc == (locale_t) 0) errExit("newlocale"); /* If a second command-line argument was specified, modify the locale object to take the LC_TIME settings from the locale specified in argv[2]. We assign the result of this newlocale() call to 'nloc' rather than 'loc', since in some cases, we might want to preserve 'loc' if this call fails. */ if (argc > 2) { nloc = newlocale(LC_TIME_MASK, argv[2], loc); if (nloc == (locale_t) 0) errExit("newlocale"); loc = nloc; } /* Apply the newly created locale to this thread. */ uselocale(loc); /* Test effect of LC_NUMERIC. */ printf("%8.3f\n", 123456.789); /* Test effect of LC_TIME. */ t = time(NULL); tm = localtime(&t); if (tm == NULL) errExit("time"); s = strftime(buf, sizeof(buf), "%c", tm); if (s == 0) errExit("strftime"); printf("%s\n", buf); /* Free the locale object. */ uselocale(LC_GLOBAL_LOCALE); /* So 'loc' is no longer in use */ freelocale(loc); exit(EXIT_SUCCESS); }

COLOPHON top

This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17newlocale(3)