Debian Codegraph @

upstream/mageia-cauldron/man3/nl_langinfo.3

raw
1 '\" t
2 .\" Copyright 2001, Markus Kuhn <[email protected]>
3 .\" Copyright 2006, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: GPL-2.0-or-later
7 .\"
8 .TH nl_langinfo 3 2026-02-08 "Linux man-pages 6.17"
9 .SH NAME
10 nl_langinfo, nl_langinfo_l \- query language and locale information
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <langinfo.h>
17 .P
18 .BI "char *nl_langinfo(nl_item " item );
19 .BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale );
20 .fi
21 .P
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 .BR nl_langinfo_l ():
28 .nf
29 Since glibc 2.24:
30 _POSIX_C_SOURCE >= 200809L
31 glibc 2.23 and earlier:
32 _POSIX_C_SOURCE >= 200112L
33 .fi
34 .SH DESCRIPTION
35 The
36 .BR nl_langinfo ()
37 and
38 .BR nl_langinfo_l ()
39 functions provide access to locale information
40 in a more flexible way than
41 .BR localeconv (3).
42 .BR nl_langinfo ()
43 returns a string which is the value corresponding to
44 .I item
45 in the program's current global locale.
46 .BR nl_langinfo_l ()
47 returns a string which is the value corresponding to
48 .I item
49 for the locale identified by the locale object
50 .IR locale ,
51 which was previously created by
52 .BR newlocale (3).
53 Individual and additional elements of the locale categories can
54 be queried.
55 .P
56 Examples for the locale elements that can be specified in
57 .I item
58 using the constants defined in
59 .I <langinfo.h>
60 are:
61 .TP
62 .BR CODESET \ (LC_CTYPE)
63 Return a string with the name of the character encoding used in the
64 selected locale, such as "UTF\-8", "ISO\-8859\-1", or "ANSI_X3.4\-1968"
65 (better known as US-ASCII).
66 This is the same string that you get with
67 "locale charmap".
68 For a list of character encoding names,
69 try "locale \-m" (see
70 .BR locale (1)).
71 .TP
72 .BR D_T_FMT \ (LC_TIME)
73 Return a string that can be used as a format string for
74 .BR strftime (3)
75 to represent time and date in a locale-specific way
76 .RB ( %c
77 conversion specification).
78 .TP
79 .BR D_FMT \ (LC_TIME)
80 Return a string that can be used as a format string for
81 .BR strftime (3)
82 to represent a date in a locale-specific way
83 .RB ( %x
84 conversion specification).
85 .TP
86 .BR T_FMT \ (LC_TIME)
87 Return a string that can be used as a format string for
88 .BR strftime (3)
89 to represent a time in a locale-specific way
90 .RB ( %X
91 conversion specification).
92 .TP
93 .BR AM_STR \ (LC_TIME)
94 Return a string that represents affix for ante meridiem (before noon, "AM")
95 time.
96 (Used in
97 .B %p
98 .BR strftime (3)
99 conversion specification.)
100 .TP
101 .BR PM_STR \ (LC_TIME)
102 Return a string that represents affix for post meridiem (before midnight, "PM")
103 time.
104 (Used in
105 .B %p
106 .BR strftime (3)
107 conversion specification.)
108 .TP
109 .BR T_FMT_AMPM \ (LC_TIME)
110 Return a string that can be used as a format string for
111 .BR strftime (3)
112 to represent a time in a.m.\& or p.m.\& notation
113 in a locale-specific way
114 .RB ( %r
115 conversion specification).
116 .TP
117 .BR ERA \ (LC_TIME)
118 Return era description, which contains information about how years are counted
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.
177 Examples of locales that do define this value are the Japanese and Thai
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
201 .BR DAY_ "{1\[en]7} (LC_TIME)"
202 Return name of the
203 .IR n -th
204 day of the week.
205 [Warning: this follows
206 the US convention DAY_1 = Sunday, not the international convention
207 (ISO\~8601) that Monday is the first day of the week.]
208 (Used in
209 .B %A
210 .BR strftime (3)
211 conversion specification.)
212 .TP
213 .BR ABDAY_ "{1\[en]7} (LC_TIME)"
214 Return abbreviated name of the
215 .IR n -th
216 day of the week.
217 (Used in
218 .B %a
219 .BR strftime (3)
220 conversion specification.)
221 .TP
222 .BR MON_ "{1\[en]12} (LC_TIME)"
223 Return name of the
224 .IR n -th
225 month.
226 (Used in
227 .B %B
228 .BR strftime (3)
229 conversion specification.)
230 .TP
231 .BR ABMON_ "{1\[en]12} (LC_TIME)"
232 Return abbreviated name of the
233 .IR n -th
234 month.
235 (Used in
236 .B %b
237 .BR strftime (3)
238 conversion specification.)
239 .TP
240 .BR RADIXCHAR \ (LC_NUMERIC)
241 Return radix character (decimal dot, decimal comma, etc.).
242 .TP
243 .BR THOUSEP \ (LC_NUMERIC)
244 Return separator character for thousands (groups of three digits).
245 .TP
246 .BR YESEXPR \ (LC_MESSAGES)
247 Return a regular expression that can be used with the
248 .BR regex (3)
249 function to recognize a positive response to a yes/no question.
250 .TP
251 .BR NOEXPR \ (LC_MESSAGES)
252 Return a regular expression that can be used with the
253 .BR regex (3)
254 function to recognize a negative response to a yes/no question.
255 .TP
256 .BR CRNCYSTR \ (LC_MONETARY)
257 Return the currency symbol, preceded by "\-" if the symbol should
258 appear before the value, "+" if the symbol should appear after the
259 value, or "." if the symbol should replace the radix character.
260 .P
261 The above list covers just some examples of items that can be requested.
262 For a more detailed list, consult
263 .IR "The GNU C Library Reference Manual" .
264 .SH RETURN VALUE
265 On success, these functions return a pointer to a string which
266 is the value corresponding to
267 .I item
268 in the specified locale.
269 .P
270 If no locale has been selected by
271 .BR setlocale (3)
272 for the appropriate category,
273 .BR nl_langinfo ()
274 return a pointer to the corresponding string in the "C" locale.
275 The same is true of
276 .BR nl_langinfo_l ()
277 if
278 .I locale
279 specifies a locale where
280 .I langinfo
281 data is not defined.
282 .P
283 If
284 .I item
285 is not valid, a pointer to an empty string is returned.
286 .P
287 The pointer returned by these functions may point to static data that
288 may be overwritten, or the pointer itself may be invalidated,
289 by a subsequent call to
290 .BR nl_langinfo (),
291 .BR nl_langinfo_l (),
292 or
293 .BR setlocale (3).
294 The same statements apply to
295 .BR nl_langinfo_l ()
296 if the locale object referred to by
297 .I locale
298 is freed or modified by
299 .BR freelocale (3)
300 or
301 .BR newlocale (3).
302 .P
303 POSIX specifies that the application may not modify
304 the string returned by these functions.
305 .SH ATTRIBUTES
306 For an explanation of the terms used in this section, see
307 .BR attributes (7).
308 .TS
309 allbox;
310 lbx lb lb
311 l l l.
312 Interface Attribute Value
313 T{
314 .na
315 .nh
316 .BR nl_langinfo ()
317 T} Thread safety MT-Safe locale
318 .TE
319 .SH STANDARDS
320 POSIX.1-2008.
321 .SH HISTORY
322 POSIX.1-2001, SUSv2.
323 .SH NOTES
324 The behavior of
325 .BR nl_langinfo_l ()
326 is undefined if
327 .I locale
328 is the special locale object
329 .B LC_GLOBAL_LOCALE
330 or is not a valid locale object handle.
331 .SH EXAMPLES
332 The following program sets the character type and the numeric locale
333 according to the environment and queries the terminal character set and
334 the radix character.
335 .P
336 .\" SRC BEGIN (nl_langinfo.c)
337 .EX
338 #include <langinfo.h>
339 #include <locale.h>
340 #include <stdio.h>
341 #include <stdlib.h>
342 \&
343 int
344 main(void)
345 {
346 setlocale(LC_CTYPE, "");
347 setlocale(LC_NUMERIC, "");
348 \&
349 printf("%s\[rs]n", nl_langinfo(CODESET));
350 printf("%s\[rs]n", nl_langinfo(RADIXCHAR));
351 \&
352 exit(EXIT_SUCCESS);
353 }
354 .EE
355 .\" SRC END
356 .SH SEE ALSO
357 .BR locale (1),
358 .BR localeconv (3),
359 .BR setlocale (3),
360 .BR charsets (7),
361 .BR locale (7)
362 .P
363 The GNU C Library Reference Manual