Linux程序员手册 第3部分
更新日期： 2020-06-09

名称

newlocale, freelocale - 创建、修改和释放一个locale对象

语法

#include <locale.h>

locale_t newlocale(int category_mask, const char *locale,
                   locale_t base);

void freelocale(locale_t locobj);

glibc的特性测试宏要求(参见feature_test_macros(7)):

newlocale (), freelocale ():

Since glibc 2.10:

_XOPEN_SOURCE > = 700

Before glibc 2.10:

_GNU_SOURCE

说明

函数的作用是:创建新的locale对象或修改现有对象，并返回对新对象或修改对象的引用作为函数结果。调用是否创建一个新对象或修改一个现有对象是由base的值决定的:

*

如果base为(locale_t) 0，则创建一个新对象。

*

如果base引用有效的已存在的locale对象(例如，以前调用newlocale()或duplocale(3)返回的对象)，那么该对象将被调用修改。如果调用成功，则不指定base的内容(特别是，可能释放由base引用的对象，并创建一个新对象)。因此，调用者应该确保在调用newlocale()之前停止使用base，然后通过作为函数结果返回的引用引用修改后的对象。如果调用失败，base的内容将保持有效并没有改变。

如果base是特殊的locale对象LC_GLOBAL_LOCALE(参见duplocale(3))，或者不是(locale_t) 0并且不是有效的locale对象句柄，则该行为是未定义的。

category_mask参数是一个位掩码，它指定在新创建的locale对象中设置或在现有对象中修改的locale类别。掩码是由常量LC_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和LC_TIME_MASK按位或构造的。或者，可以将掩码指定为LC_ALL_MASK，这相当于对前面的所有常量进行监控。

对于在category_mask中指定的每个类别，locale数据将在newlocale()返回的对象中使用。如果创建了一个新的locale对象，那么没有在category_mask中指定的所有类别的数据将从默认("POSIX")locale获取。

以下locale的预设值是为所有类别定义的，可以在category_mask中指定:

"POSIX"

C语言程序的最小语言环境。

"C"

相当于"POSIX"。

""

一个实现定义的本地环境，对应于LC_*和LANG环境变量的值(参见locale(7))。

freelocale()

自由ocale()函数释放与locobj相关的资源，locobj是一个locale对象，以前通过调用newlocale()或duplocale(3)返回。如果locobj是LC_GLOBAL_LOCALE或者不是有效的locale对象句柄，那么结果是未定义的。

一旦一个locale对象被释放，程序就不应该再使用它。

返回值

成功后，newlocale()返回一个句柄，该句柄可用于对duplocale(3)、freelocale()和其他具有locale_t参数的函数的调用。在出现错误时，newlocale()返回(locale_t) 0，并设置errno来指示错误的原因。

错误说明

EINVAL

category_mask中的一个或多个位不对应于有效的区域设置类别。

EINVAL

语言环境是NULL。

ENOENT

区域设置不是引用有效区域设置的字符串指针。

ENOMEM

内存不足，无法创建locale对象。

版本

newlocale()和freelocale()函数首次出现在版本2.3的GNU C库中。

遵循规范

posix . 1的授权- 2008。

备注

由newlocale()创建的每个locale对象都应该使用freelocale()来释放。

示例

下面的程序使用最多两个命令行参数，每个参数标识地区。第一个参数是必需的，用于在使用newlocale()创建的locale对象中设置LC_NUMERIC类别。第二个命令行参数是可选的;如果存在，则用于设置locale对象的LC_TIME类别。

创建并初始化locale对象后，程序使用uselocale(3)应用它，然后通过以下方法测试locale改变的效果:

1.

显示具有小数部分的浮点数。这个输出将受到LC_NUMERIC设置的影响。在许多欧洲语言环境中，数字的小数部分与整数部分使用逗号分隔，而不是使用句号。

2.

显示日期。输出的格式和语言将受到LC_TIME设置的影响。

下面的shell会话展示了这个程序的一些运行示例。

将LC_NUMERIC类别设置为fr_FR(法语):

$ ./a.out fr_FR
123456,789
Fri Mar  7 00:25:08 2014

将LC_NUMERIC类别设置为fr_FR(法语)，将LC_TIME类别设置为it_IT(意大利语):

$ ./a.out fr_FR it_IT
123456,789
ven 07 mar 2014 00:26:01 CET

指定LC_TIME设置为空字符串，这将导致从环境变量设置(这里指定mi_NZ, New Zealand MA& #129;ori)中获取值:

$ LC_ALL=mi_NZ ./a.out fr_FR ""
123456,789
Te Paraire, te 07 o Poutū-te-rangi, 2014 00:38:44 CET

Program source

#define _XOPEN_SOURCE 700
#include <stdio.h>
#include <stdlib.h>
#include <locale.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_HANDLE);    /* So 'loc' is no longer in use */
    freelocale(loc);

    exit(EXIT_SUCCESS);
}

另外参见

locale(1)， duplocale(3)， setlocale(3)， uselocale(3)， locale(5)， locale(7)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。