0001220: Add an API to query the name of a locale category of a locale object

Austin Group Defect Tracker

Aardvark Mark III

Viewing Issue Simple Details [ Jump to Notes ]

[ Issue History ] [ Print ]

Category

Severity

Type

Date Submitted

Last Update

0001220

[1003.1(2016)/Issue7+TC2] System Interfaces

Editorial

Omission

2018-12-20 13:46

Reporter

bhaible

View Status

public

Assigned To

Priority

normal

Resolution

Open

Status

New

Name

Bruno Haible

Organization

GNU

User Reference

Section

---

Page Number

---

Line Number

---

Interp Status

---

Final Accepted Text

Summary

0001220: Add an API to query the name of a locale category of a locale object

Description

The purpose of the locale API is to let information flow within an application; it's not primarily an interface to the kernel. The information producer is the code that sets the locale, either implicitly at program start, or through setlocale, or per-thread through uselocale. The information consumer is the code that produces different data depending on the locale. There are information consumers defined by this standard (such as mbrtowc, which uses the LC_CTYPE category of the current locale, or fprintf, which prints floating-point numbers using the LC_NUMERIC category of the current locale), and there are information consumers defined by the application. So far, information consumers defined by the application can only query the locale set at program start or through setlocale, through a call to setlocale(category,NULL). So far, information consumers defined by the application have no way to actually be implemented in a portable way, because such an API is not defined by this standard. Instead, different APIs are provided by different libc vendors.

The need for such an API is best proved by looking at the locale_t object of OpenBSD 6.2. It contains only the minimal information needed to fulfil this standard. A locale_t object for "en_US.UTF-8" and a locale_t object object for "de_DE.UTF-8" are indistinguishable; they are in fact the same pointer values. In such a system, an application has no way to produce locale dependent data (such as, a different decimal separator (LC_NUMERIC category) or different translations of a string (LC_MESSAGES category)). This proves that the API provided by this standard so far is insufficient for information consumers defined by the application.

I propose to add an API as shown below.

Rationale for this API:

Different systems have different APIs.

The API proposed here is the one considered for Solaris 12. See https://lists.gnu.org/archive/html/bug-gnulib/2015-01/msg00078.html [^] . Solaris 11.4 in fact has __getlocalename_l.

FreeBSD and macOS have querylocale(). The problem with this API is that its first argument is a mask; the application therefore first has to convert the category to a category_mask.

GNU libc, Cygwin, and musl libc have an API that is based on <langinfo.h>: nl_langinfo_l (NL_LOCALE_NAME (category), locobj).

Desired Action

NAME
     getlocalename_l - get name of locale object

SYNOPSIS
     #include <locale.h>
     const char * getlocalename_l (int category, locale_t locobj);

DESCRIPTION
     The getlocalename_l() function shall return the name of the locale locobj for the given category.

     The category argument must specify the category. The possible values include LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME, with the meaning defined in [reference to setlocale() description]. Otherwise, the behavior is undefined.

     The locobj argument must be a valid locale object handle and must not be equal to LC_GLOBAL_LOCALE. Otherwise, the behavior is undefined.

RETURN VALUE
     The getlocalename_l() function shall return the string associated with the specified category for the given locale. This string's lifetime ends when freelocale(locobj) gets invoked.

ERRORS
    No errors are defined.

EXAMPLES
    Determining the name of a category of the current per-thread locale

    The following example shows how to extract the name of a LC_NUMERIC category of the current per-thread locale.

    #include <locale.h>
    ...
    const char *name;
    locale_t loc = uselocale (NULL);
    if (loc == LC_GLOBAL_LOCALE)
      name = setlocale (LC_NUMERIC, NULL);
    else
      name = getlocalename_l (LC_NUMERIC, loc);

APPLICATION USAGE
    The special locale object handle LC_GLOBAL_LOCALE must not be passed for the locobj argument, even when returned by the uselocale() function.

SEE ALSO
    newlocale, freelocale, setlocale
    XBD Locale, <locale.h>

Issue History
Date Modified	Username	Field	Change
2018-12-20 13:46	bhaible	New Issue
2018-12-20 13:46	bhaible	Name	=> Bruno Haible
2018-12-20 13:46	bhaible	Organization	=> GNU
2018-12-20 13:46	bhaible	Section	=> ---
2018-12-20 13:46	bhaible	Page Number	=> ---
2018-12-20 13:46	bhaible	Line Number	=> ---

Relationships