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