]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 2001 Markus Kuhn <mkuhn@acm.org> |
80bf84f6 MK |
2 | .\" and Copyright (c) 2015 Sam Varshavchik <mrsam@courier-mta.com> |
3 | .\" and Copyright (c) 2015 Michael Kerrisk <mtk.manpages@gmail.com> | |
fea681da | 4 | .\" |
89e3ffe9 | 5 | .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) |
fea681da MK |
6 | .\" This is free documentation; you can redistribute it and/or |
7 | .\" modify it under the terms of the GNU General Public License as | |
8 | .\" published by the Free Software Foundation; either version 2 of | |
9 | .\" the License, or (at your option) any later version. | |
8f8359d8 | 10 | .\" %%%LICENSE_END |
fea681da MK |
11 | .\" |
12 | .\" References consulted: | |
13 | .\" GNU glibc-2 manual | |
008f1ecc | 14 | .\" OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html |
fea681da MK |
15 | .\" |
16 | .\" Corrected prototype, 2002-10-18, aeb | |
17 | .\" | |
e8426ca2 | 18 | .TH NL_LANGINFO 3 2020-04-11 "GNU" "Linux Programmer's Manual" |
fea681da | 19 | .SH NAME |
665d98c5 | 20 | nl_langinfo, nl_langinfo_l \- query language and locale information |
fea681da MK |
21 | .SH SYNOPSIS |
22 | .nf | |
23 | .B #include <langinfo.h> | |
68e4db0a | 24 | .PP |
fea681da | 25 | .BI "char *nl_langinfo(nl_item " item ); |
68e4db0a | 26 | .PP |
665d98c5 | 27 | .BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale ); |
fea681da | 28 | .fi |
68e4db0a | 29 | .PP |
4c931ba3 MK |
30 | .in -4n |
31 | Feature Test Macro Requirements for glibc (see | |
32 | .BR feature_test_macros (7)): | |
33 | .in | |
68e4db0a | 34 | .PP |
4c931ba3 MK |
35 | .ad l |
36 | .BR nl_langinfo_l (): | |
37 | .RS 4 | |
38 | Since glibc 2.24: | |
39 | _POSIX_C_SOURCE\ >=\ 200809L | |
40 | .br | |
41 | Glibc 2.23 and earlier: | |
42 | _POSIX_C_SOURCE\ >=\ 200112L | |
43 | .RE | |
44 | .ad b | |
fea681da | 45 | .SH DESCRIPTION |
60a90ecd MK |
46 | The |
47 | .BR nl_langinfo () | |
665d98c5 SV |
48 | and |
49 | .BR nl_langinfo_l () | |
50 | functions provide access to locale information | |
fea681da | 51 | in a more flexible way than |
83a366e0 | 52 | .BR localeconv (3). |
6614e292 | 53 | .BR nl_langinfo () |
1f741719 MK |
54 | returns a string which is the value corresponding to |
55 | \fIitem\fP in the program's current global | |
665d98c5 | 56 | locale. |
5afb9373 | 57 | .BR nl_langinfo_l () |
1f741719 MK |
58 | returns a string which is the value corresponding to \fIitem\fP |
59 | for the locale identified by the locale object \fIlocale\fP, | |
83a366e0 | 60 | which was previously created by |
665d98c5 | 61 | .BR newlocale (1). |
c13182ef | 62 | Individual and additional elements of the locale categories can |
fea681da MK |
63 | be queried. |
64 | .PP | |
65 | Examples for the locale elements that can be specified in \fIitem\fP | |
c84371c6 | 66 | using the constants defined in \fI<langinfo.h>\fP are: |
fea681da MK |
67 | .TP |
68 | .BR CODESET \ (LC_CTYPE) | |
69 | Return a string with the name of the character encoding used in the | |
70 | selected locale, such as "UTF-8", "ISO-8859-1", or "ANSI_X3.4-1968" | |
c13182ef MK |
71 | (better known as US-ASCII). |
72 | This is the same string that you get with | |
73 | "locale charmap". | |
74 | For a list of character encoding names, | |
9ab7f611 BR |
75 | try "locale \-m" (see |
76 | .BR locale (1)). | |
fea681da MK |
77 | .TP |
78 | .BR D_T_FMT \ (LC_TIME) | |
79 | Return a string that can be used as a format string for | |
80 | .BR strftime (3) | |
6c21e49f ES |
81 | to represent time and date in a locale-specific way |
82 | .RB ( %c | |
83 | conversion specification). | |
fea681da MK |
84 | .TP |
85 | .BR D_FMT \ (LC_TIME) | |
86 | Return a string that can be used as a format string for | |
87 | .BR strftime (3) | |
6c21e49f ES |
88 | to represent a date in a locale-specific way |
89 | .RB ( %x | |
90 | conversion specification). | |
fea681da MK |
91 | .TP |
92 | .BR T_FMT \ (LC_TIME) | |
93 | Return a string that can be used as a format string for | |
94 | .BR strftime (3) | |
6c21e49f ES |
95 | to represent a time in a locale-specific way |
96 | .RB ( %X | |
97 | conversion specification). | |
fea681da | 98 | .TP |
6602e55a ES |
99 | .BR AM_STR \ (LC_TIME) |
100 | Return a string that represents affix for ante meridiem (before noon, "AM") | |
101 | time. | |
102 | (Used in | |
103 | .B %p | |
104 | .BR strftime (3) | |
105 | conversion specification.) | |
106 | .TP | |
107 | .BR PM_STR \ (LC_TIME) | |
108 | Return a string that represents affix for post meridiem (before midnight, "PM") | |
109 | time. | |
110 | (Used in | |
111 | .B %p | |
112 | .BR strftime (3) | |
113 | conversion specification.) | |
114 | .TP | |
115 | .BR T_FMT_AMPM \ (LC_TIME) | |
116 | Return a string that can be used as a format string for | |
117 | .BR strftime (3) | |
118 | to represent a time in a.m. or p.m. notation a locale-specific way | |
119 | .RB ( %r | |
120 | conversion specification). | |
121 | .TP | |
2969f2cc | 122 | .BR ERA \ (LC_TIME) |
b18f9423 | 123 | Return era description, which contains information about how years are counted |
2969f2cc ES |
124 | and displayed for each era in a locale. |
125 | Each era description segment shall have the format: | |
126 | .RS | |
127 | .IP | |
128 | .IR direction : offset : start_date : end_date : era_name : era_format | |
129 | .RE | |
130 | .IP | |
131 | according to the definitions below: | |
132 | .RS | |
133 | .TP 12 | |
134 | .I direction | |
135 | Either a | |
136 | .RB \[dq] + "\[dq] or a \[dq]" - \[dq] | |
137 | character. | |
138 | The | |
139 | .RB \[dq] + \[dq] | |
140 | means that years increase from the | |
141 | .I start_date | |
142 | towards the | |
143 | .IR end_date , | |
144 | .RB \[dq] - \[dq] | |
145 | means the opposite. | |
146 | .TP | |
147 | .I offset | |
148 | The epoch year of the | |
149 | .IR start_date . | |
150 | .TP | |
151 | .I start_date | |
152 | A date in the form | |
153 | .IR yyyy / mm / dd , | |
154 | where | |
155 | .IR yyyy ", " mm ", and " dd | |
156 | are the year, month, and day numbers respectively of the start of the era. | |
157 | .TP | |
158 | .I end_date | |
159 | The ending date of the era, in the same format as the | |
160 | .IR start_date , | |
161 | or one of the two special values | |
162 | .RB \[dq] -* \[dq] | |
163 | (minus infinity) or | |
164 | .RB \[dq] +* \[dq] | |
165 | (plus infinity). | |
166 | .TP | |
167 | .I era_name | |
168 | The name of the era, corresponding to the | |
169 | .B %EC | |
170 | .BR strftime (3) | |
171 | conversion specification. | |
172 | .TP | |
173 | .I era_format | |
174 | The format of the year in the era, corresponding to the | |
175 | .B %EY | |
176 | .BR strftime (3) | |
177 | conversion specification. | |
178 | .RE | |
179 | .IP | |
180 | Era description segments are separated by semicolons. | |
181 | Most locales do not define this value. | |
b18f9423 | 182 | Examples of locales that do define this value are the Japanese and Thai |
2969f2cc ES |
183 | locales. |
184 | .TP | |
185 | .BR ERA_D_T_FMT \ (LC_TIME) | |
186 | Return a string that can be used as a format string for | |
187 | .BR strftime (3) | |
188 | for alternative representation of time and date in a locale-specific way | |
189 | .RB ( %Ec | |
190 | conversion specification). | |
191 | .TP | |
192 | .BR ERA_D_FMT \ (LC_TIME) | |
193 | Return a string that can be used as a format string for | |
194 | .BR strftime (3) | |
195 | for alternative representation of a date in a locale-specific way | |
196 | .RB ( %Ex | |
197 | conversion specification). | |
198 | .TP | |
199 | .BR ERA_T_FMT \ (LC_TIME) | |
200 | Return a string that can be used as a format string for | |
201 | .BR strftime (3) | |
202 | for alternative representation of a time in a locale-specific way | |
203 | .RB ( %EX | |
204 | conversion specification). | |
205 | .TP | |
fea681da MK |
206 | .BR DAY_ "{1\(en7} (LC_TIME)" |
207 | Return name of the \fIn\fP-th day of the week. [Warning: this follows | |
208 | the US convention DAY_1 = Sunday, not the international convention | |
209 | (ISO 8601) that Monday is the first day of the week.] | |
6c21e49f ES |
210 | (Used in |
211 | .B %A | |
212 | .BR strftime (3) | |
213 | conversion specification.) | |
fea681da MK |
214 | .TP |
215 | .BR ABDAY_ "{1\(en7} (LC_TIME)" | |
216 | Return abbreviated name of the \fIn\fP-th day of the week. | |
6c21e49f ES |
217 | (Used in |
218 | .B %a | |
219 | .BR strftime (3) | |
220 | conversion specification.) | |
fea681da MK |
221 | .TP |
222 | .BR MON_ "{1\(en12} (LC_TIME)" | |
223 | Return name of the \fIn\fP-th month. | |
6c21e49f ES |
224 | (Used in |
225 | .B %B | |
226 | .BR strftime (3) | |
227 | conversion specification.) | |
fea681da MK |
228 | .TP |
229 | .BR ABMON_ "{1\(en12} (LC_TIME)" | |
230 | Return abbreviated name of the \fIn\fP-th month. | |
6c21e49f ES |
231 | (Used in |
232 | .B %b | |
233 | .BR strftime (3) | |
234 | conversion specification.) | |
fea681da MK |
235 | .TP |
236 | .BR RADIXCHAR \ (LC_NUMERIC) | |
237 | Return radix character (decimal dot, decimal comma, etc.). | |
fea681da MK |
238 | .TP |
239 | .BR THOUSEP \ (LC_NUMERIC) | |
240 | Return separator character for thousands (groups of three digits). | |
fea681da | 241 | .TP |
c13182ef MK |
242 | .BR YESEXPR \ (LC_MESSAGES) |
243 | Return a regular expression that can be used with the | |
fea681da MK |
244 | .BR regex (3) |
245 | function to recognize a positive response to a yes/no question. | |
fea681da | 246 | .TP |
c13182ef MK |
247 | .BR NOEXPR \ (LC_MESSAGES) |
248 | Return a regular expression that can be used with the | |
fea681da MK |
249 | .BR regex (3) |
250 | function to recognize a negative response to a yes/no question. | |
fea681da MK |
251 | .TP |
252 | .BR CRNCYSTR \ (LC_MONETARY) | |
253 | Return the currency symbol, preceded by "\-" if the symbol should | |
254 | appear before the value, "+" if the symbol should appear after the | |
255 | value, or "." if the symbol should replace the radix character. | |
256 | .PP | |
c13182ef | 257 | The above list covers just some examples of items that can be requested. |
64dd3207 | 258 | For a more detailed list, consult |
fea681da | 259 | .IR "The GNU C Library Reference Manual" . |
47297adb | 260 | .SH RETURN VALUE |
7003ff6a MK |
261 | On success, these functions return a pointer to a string which |
262 | is the value corresponding to | |
263 | .I item | |
264 | in the specified locale. | |
847e0d88 | 265 | .PP |
7b937140 | 266 | If no locale has been selected by |
0b80cf56 | 267 | .BR setlocale (3) |
7b937140 | 268 | for the appropriate category, |
60a90ecd | 269 | .BR nl_langinfo () |
29f6f82c MK |
270 | return a pointer to the corresponding string in the "C" locale. |
271 | The same is true of | |
665d98c5 | 272 | .BR nl_langinfo_l () |
29f6f82c MK |
273 | if |
274 | .I locale | |
275 | specifies a locale where | |
276 | .I langinfo | |
277 | data is not defined. | |
fea681da MK |
278 | .PP |
279 | If \fIitem\fP is not valid, a pointer to an empty string is returned. | |
280 | .PP | |
cc331dfc MK |
281 | The pointer returned by these functions may point to static data that |
282 | may be overwritten, or the pointer itself may be invalidated, | |
283 | by a subsequent call to | |
284 | .BR nl_langinfo (), | |
285 | .BR nl_langinfo_l (), | |
60a90ecd | 286 | or |
3a72373c | 287 | .BR setlocale (3). |
cc331dfc MK |
288 | The same statements apply to |
289 | .BR nl_langinfo_l () | |
290 | if the locale object referred to by | |
291 | .I locale | |
292 | is freed or modified by | |
293 | .BR freelocale (3) | |
294 | or | |
295 | .BR newlocale (3). | |
847e0d88 | 296 | .PP |
75b3623d MK |
297 | POSIX specifies that the application may not modify |
298 | the string returned by these functions. | |
52aacd78 PH |
299 | .SH ATTRIBUTES |
300 | For an explanation of the terms used in this section, see | |
301 | .BR attributes (7). | |
302 | .TS | |
303 | allbox; | |
304 | lb lb lb | |
305 | l l l. | |
306 | Interface Attribute Value | |
307 | T{ | |
308 | .BR nl_langinfo () | |
309 | T} Thread safety MT-Safe locale | |
310 | .TE | |
47297adb | 311 | .SH CONFORMING TO |
5b36c0e4 | 312 | POSIX.1-2001, POSIX.1-2008, SUSv2. |
872e754b MK |
313 | .SH NOTES |
314 | The behavior of | |
315 | .BR nl_langinfo_l () | |
316 | is undefined if | |
317 | .I locale | |
318 | is the special locale object | |
319 | .BR LC_GLOBAL_LOCALE | |
320 | or is not a valid locale object handle. | |
a14af333 | 321 | .SH EXAMPLES |
dbe0246b MM |
322 | The following program sets the character type and the numeric locale |
323 | according to the environment and queries the terminal character set and | |
324 | the radix character. | |
dd3568a1 | 325 | .PP |
207050fa | 326 | .EX |
7f3e079f MH |
327 | #include <langinfo.h> |
328 | #include <locale.h> | |
329 | #include <stdio.h> | |
330 | #include <stdlib.h> | |
331 | ||
332 | int | |
333 | main(int argc, char *argv[]) | |
334 | { | |
68f4e1fd | 335 | setlocale(LC_CTYPE, ""); |
dbe0246b | 336 | setlocale(LC_NUMERIC, ""); |
c607c3a6 | 337 | |
d1a71985 MK |
338 | printf("%s\en", nl_langinfo(CODESET)); |
339 | printf("%s\en", nl_langinfo(RADIXCHAR)); | |
c607c3a6 | 340 | |
7f3e079f MH |
341 | exit(EXIT_SUCCESS); |
342 | } | |
207050fa | 343 | .EE |
47297adb | 344 | .SH SEE ALSO |
fea681da MK |
345 | .BR locale (1), |
346 | .BR localeconv (3), | |
347 | .BR setlocale (3), | |
348 | .BR charsets (7), | |
883b0fef | 349 | .BR locale (7) |
207050fa | 350 | .PP |
fea681da | 351 | The GNU C Library Reference Manual |