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