The Open Group Base Specifications Issue 7
IEEE Std 1003.1, 2013 Edition
Copyright © 2001-2013 The IEEE and The Open Group

#### NAME

> nl_langinfo, nl_langinfo_l - language information

#### SYNOPSIS

> ``#include <langinfo.h>
> char *nl_langinfo(nl_item` item`);
> char *nl_langinfo_l(nl_item` item`, locale_t` locale`);
> ``

#### DESCRIPTION

> The nl_langinfo() and nl_langinfo_l() functions shall return a pointer to a string containing information relevant to the particular language or cultural area defined in the current locale, or in the locale represented by locale, respectively (see <langinfo.h>). The manifest constant names and values of item are defined in <langinfo.h>. For example:

>     nl_langinfo(ABDAY_1)

> would return a pointer to the string `"Dom"` if the identified language was Portuguese, and `"Sun"` if the identified language was English.

>     nl_langinfo_l(ABDAY_1, loc)

> would return a pointer to the string `"Dom"` if the identified language of the locale represented by loc was Portuguese, and `"Sun"` if the identified language of the locale represented by loc was English.

> The nl_langinfo() function need not be thread-safe.

> The behavior is undefined if the locale argument to nl_langinfo_l() is the special locale object LC_GLOBAL_LOCALE or is not a valid locale object handle.

#### RETURN VALUE

> In a locale where langinfo data is not defined, these functions shall return a pointer to the corresponding string in the POSIX locale. In all locales, these functions shall return a pointer to an empty string if item contains an invalid setting.

> The application shall not modify the string returned. The pointer returned by nl_langinfo() might be invalidated or the string content might be overwritten by a subsequent call to nl_langinfo() in any thread or to nl_langinfo_l() in the same thread or the initial thread, by subsequent calls to setlocale() with a category corresponding to the category of item (see <langinfo.h>) or the category LC_ALL, or by subsequent calls to uselocale() which change the category corresponding to the category of item. The pointer returned by nl_langinfo_l() might be invalidated or the string content might be overwritten by a subsequent call to nl_langinfo_l() in the same thread or to nl_langinfo() in any thread, or by subsequent calls to freelocale() or newlocale() which free or modify the locale object that was passed to nl_langinfo_l().

#### ERRORS

> No errors are defined.

The following sections are informative.

#### EXAMPLES

> ##### Getting Date and Time Formatting Information

> The following example returns a pointer to a string containing date and time formatting information, as defined in the LC_TIME category of the current locale.

>     #include <time.h>
>     #include <langinfo.h>
>     ...
>     strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm);
>     ...

#### APPLICATION USAGE

> The array pointed to by the return value should not be modified by the program, but may be modified by further calls to these functions.

#### RATIONALE

> The possible interactions between internal data used by nl_langinfo() and nl_langinfo_l() are complicated by the fact that nl_langinfo_l() must be thread-safe but nl_langinfo() need not be. The various implementation choices are:

> 1. nl_langinfo_l() and nl_langinfo() use separate buffers, or at least one of them does not use an internal string buffer. In this case there are no interactions.

> 2. nl_langinfo_l() and nl_langinfo() share an internal per-thread buffer. There can be interactions, but only in the same thread.

> 3. nl_langinfo_l() uses an internal per-thread buffer, and nl_langinfo() uses (in all threads) the same buffer that nl_langinfo_l() uses in the initial thread. There can be interactions, but only when nl_langinfo_l() is called in the initial thread.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> setlocale, uselocale

> XBD Locale, <langinfo.h>, <locale.h>, <nl_types.h>

#### CHANGE HISTORY

> First released in Issue 2.

#### Issue 5

> The last paragraph of the DESCRIPTION is moved from the APPLICATION USAGE section.

> A note indicating that this function need not be reentrant is added to the DESCRIPTION.

#### Issue 7

> Austin Group Interpretation 1003.1-2001 #156 is applied.

> The nl_langinfo() function is moved from the XSI option to the Base.

> The nl_langinfo_l() function is added from The Open Group Technical Standard, 2006, Extended API Set Part 4.

> POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0412 [302], XSH/TC1-2008/0413 [75], XSH/TC1-2008/0414 [283], XSH/TC1-2008/0415 [75,402], XSH/TC1-2008/0416 [283], and XSH/TC1-2008/0417 [402] are applied.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2013 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]