| .\" Copyright (c) 2001 Markus Kuhn <mkuhn@acm.org> |
| .\" and Copyright (c) 2015 Sam Varshavchik <mrsam@courier-mta.com> |
| .\" and Copyright (c) 2015 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" %%%LICENSE_END |
| .\" |
| .\" References consulted: |
| .\" GNU glibc-2 manual |
| .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html |
| .\" |
| .\" Corrected prototype, 2002-10-18, aeb |
| .\" |
| .TH NL_LANGINFO 3 2021-03-22 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| nl_langinfo, nl_langinfo_l \- query language and locale information |
| .SH SYNOPSIS |
| .nf |
| .B #include <langinfo.h> |
| .PP |
| .BI "char *nl_langinfo(nl_item " item ); |
| .BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale ); |
| .fi |
| .PP |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .BR nl_langinfo_l (): |
| .nf |
| Since glibc 2.24: |
| _POSIX_C_SOURCE >= 200809L |
| Glibc 2.23 and earlier: |
| _POSIX_C_SOURCE >= 200112L |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR nl_langinfo () |
| and |
| .BR nl_langinfo_l () |
| functions provide access to locale information |
| in a more flexible way than |
| .BR localeconv (3). |
| .BR nl_langinfo () |
| returns a string which is the value corresponding to |
| \fIitem\fP in the program's current global |
| locale. |
| .BR nl_langinfo_l () |
| returns a string which is the value corresponding to \fIitem\fP |
| for the locale identified by the locale object \fIlocale\fP, |
| which was previously created by |
| .BR newlocale (3). |
| Individual and additional elements of the locale categories can |
| be queried. |
| .PP |
| Examples for the locale elements that can be specified in \fIitem\fP |
| using the constants defined in \fI<langinfo.h>\fP are: |
| .TP |
| .BR CODESET \ (LC_CTYPE) |
| Return a string with the name of the character encoding used in the |
| selected locale, such as "UTF-8", "ISO-8859-1", or "ANSI_X3.4-1968" |
| (better known as US-ASCII). |
| This is the same string that you get with |
| "locale charmap". |
| For a list of character encoding names, |
| try "locale \-m" (see |
| .BR locale (1)). |
| .TP |
| .BR D_T_FMT \ (LC_TIME) |
| Return a string that can be used as a format string for |
| .BR strftime (3) |
| to represent time and date in a locale-specific way |
| .RB ( %c |
| conversion specification). |
| .TP |
| .BR D_FMT \ (LC_TIME) |
| Return a string that can be used as a format string for |
| .BR strftime (3) |
| to represent a date in a locale-specific way |
| .RB ( %x |
| conversion specification). |
| .TP |
| .BR T_FMT \ (LC_TIME) |
| Return a string that can be used as a format string for |
| .BR strftime (3) |
| to represent a time in a locale-specific way |
| .RB ( %X |
| conversion specification). |
| .TP |
| .BR AM_STR \ (LC_TIME) |
| Return a string that represents affix for ante meridiem (before noon, "AM") |
| time. |
| (Used in |
| .B %p |
| .BR strftime (3) |
| conversion specification.) |
| .TP |
| .BR PM_STR \ (LC_TIME) |
| Return a string that represents affix for post meridiem (before midnight, "PM") |
| time. |
| (Used in |
| .B %p |
| .BR strftime (3) |
| conversion specification.) |
| .TP |
| .BR T_FMT_AMPM \ (LC_TIME) |
| Return a string that can be used as a format string for |
| .BR strftime (3) |
| to represent a time in a.m. or p.m. notation a locale-specific way |
| .RB ( %r |
| conversion specification). |
| .TP |
| .BR ERA \ (LC_TIME) |
| Return era description, which contains information about how years are counted |
| and displayed for each era in a locale. |
| Each era description segment shall have the format: |
| .RS |
| .IP |
| .IR direction : offset : start_date : end_date : era_name : era_format |
| .RE |
| .IP |
| according to the definitions below: |
| .RS |
| .TP 12 |
| .I direction |
| Either a |
| .RB \[dq] + "\[dq] or a \[dq]" - \[dq] |
| character. |
| The |
| .RB \[dq] + \[dq] |
| means that years increase from the |
| .I start_date |
| towards the |
| .IR end_date , |
| .RB \[dq] - \[dq] |
| means the opposite. |
| .TP |
| .I offset |
| The epoch year of the |
| .IR start_date . |
| .TP |
| .I start_date |
| A date in the form |
| .IR yyyy / mm / dd , |
| where |
| .IR yyyy ", " mm ", and " dd |
| are the year, month, and day numbers respectively of the start of the era. |
| .TP |
| .I end_date |
| The ending date of the era, in the same format as the |
| .IR start_date , |
| or one of the two special values |
| .RB \[dq] -* \[dq] |
| (minus infinity) or |
| .RB \[dq] +* \[dq] |
| (plus infinity). |
| .TP |
| .I era_name |
| The name of the era, corresponding to the |
| .B %EC |
| .BR strftime (3) |
| conversion specification. |
| .TP |
| .I era_format |
| The format of the year in the era, corresponding to the |
| .B %EY |
| .BR strftime (3) |
| conversion specification. |
| .RE |
| .IP |
| Era description segments are separated by semicolons. |
| Most locales do not define this value. |
| Examples of locales that do define this value are the Japanese and Thai |
| locales. |
| .TP |
| .BR ERA_D_T_FMT \ (LC_TIME) |
| Return a string that can be used as a format string for |
| .BR strftime (3) |
| for alternative representation of time and date in a locale-specific way |
| .RB ( %Ec |
| conversion specification). |
| .TP |
| .BR ERA_D_FMT \ (LC_TIME) |
| Return a string that can be used as a format string for |
| .BR strftime (3) |
| for alternative representation of a date in a locale-specific way |
| .RB ( %Ex |
| conversion specification). |
| .TP |
| .BR ERA_T_FMT \ (LC_TIME) |
| Return a string that can be used as a format string for |
| .BR strftime (3) |
| for alternative representation of a time in a locale-specific way |
| .RB ( %EX |
| conversion specification). |
| .TP |
| .BR DAY_ "{1\(en7} (LC_TIME)" |
| Return name of the \fIn\fP-th day of the week. [Warning: this follows |
| the US convention DAY_1 = Sunday, not the international convention |
| (ISO 8601) that Monday is the first day of the week.] |
| (Used in |
| .B %A |
| .BR strftime (3) |
| conversion specification.) |
| .TP |
| .BR ABDAY_ "{1\(en7} (LC_TIME)" |
| Return abbreviated name of the \fIn\fP-th day of the week. |
| (Used in |
| .B %a |
| .BR strftime (3) |
| conversion specification.) |
| .TP |
| .BR MON_ "{1\(en12} (LC_TIME)" |
| Return name of the \fIn\fP-th month. |
| (Used in |
| .B %B |
| .BR strftime (3) |
| conversion specification.) |
| .TP |
| .BR ABMON_ "{1\(en12} (LC_TIME)" |
| Return abbreviated name of the \fIn\fP-th month. |
| (Used in |
| .B %b |
| .BR strftime (3) |
| conversion specification.) |
| .TP |
| .BR RADIXCHAR \ (LC_NUMERIC) |
| Return radix character (decimal dot, decimal comma, etc.). |
| .TP |
| .BR THOUSEP \ (LC_NUMERIC) |
| Return separator character for thousands (groups of three digits). |
| .TP |
| .BR YESEXPR \ (LC_MESSAGES) |
| Return a regular expression that can be used with the |
| .BR regex (3) |
| function to recognize a positive response to a yes/no question. |
| .TP |
| .BR NOEXPR \ (LC_MESSAGES) |
| Return a regular expression that can be used with the |
| .BR regex (3) |
| function to recognize a negative response to a yes/no question. |
| .TP |
| .BR CRNCYSTR \ (LC_MONETARY) |
| Return the currency symbol, preceded by "\-" if the symbol should |
| appear before the value, "+" if the symbol should appear after the |
| value, or "." if the symbol should replace the radix character. |
| .PP |
| The above list covers just some examples of items that can be requested. |
| For a more detailed list, consult |
| .IR "The GNU C Library Reference Manual" . |
| .SH RETURN VALUE |
| On success, these functions return a pointer to a string which |
| is the value corresponding to |
| .I item |
| in the specified locale. |
| .PP |
| If no locale has been selected by |
| .BR setlocale (3) |
| for the appropriate category, |
| .BR nl_langinfo () |
| return a pointer to the corresponding string in the "C" locale. |
| The same is true of |
| .BR nl_langinfo_l () |
| if |
| .I locale |
| specifies a locale where |
| .I langinfo |
| data is not defined. |
| .PP |
| If \fIitem\fP is not valid, a pointer to an empty string is returned. |
| .PP |
| The pointer returned by these functions may point to static data that |
| may be overwritten, or the pointer itself may be invalidated, |
| by a subsequent call to |
| .BR nl_langinfo (), |
| .BR nl_langinfo_l (), |
| or |
| .BR setlocale (3). |
| The same statements apply to |
| .BR nl_langinfo_l () |
| if the locale object referred to by |
| .I locale |
| is freed or modified by |
| .BR freelocale (3) |
| or |
| .BR newlocale (3). |
| .PP |
| POSIX specifies that the application may not modify |
| the string returned by these functions. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lbx lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR nl_langinfo () |
| T} Thread safety MT-Safe locale |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .SH CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, SUSv2. |
| .SH NOTES |
| The behavior of |
| .BR nl_langinfo_l () |
| is undefined if |
| .I locale |
| is the special locale object |
| .BR LC_GLOBAL_LOCALE |
| or is not a valid locale object handle. |
| .SH EXAMPLES |
| The following program sets the character type and the numeric locale |
| according to the environment and queries the terminal character set and |
| the radix character. |
| .PP |
| .EX |
| #include <langinfo.h> |
| #include <locale.h> |
| #include <stdio.h> |
| #include <stdlib.h> |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| setlocale(LC_CTYPE, ""); |
| setlocale(LC_NUMERIC, ""); |
| |
| printf("%s\en", nl_langinfo(CODESET)); |
| printf("%s\en", nl_langinfo(RADIXCHAR)); |
| |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .SH SEE ALSO |
| .BR locale (1), |
| .BR localeconv (3), |
| .BR setlocale (3), |
| .BR charsets (7), |
| .BR locale (7) |
| .PP |
| The GNU C Library Reference Manual |