Debian Codegraph @

upstream/debian-unstable/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.18"
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 .BR setlocale (3)
56 needs to be executed with proper arguments before.
57 .P
58 Examples for the locale elements that can be specified in
59 .I item
60 using the constants defined in
61 .I <langinfo.h>
62 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
115 in a locale-specific way
116 .RB ( %r
117 conversion specification).
118 .TP
119 .BR ERA \ (LC_TIME)
120 Return era description, which contains information about how years are counted
121 and displayed for each era in a locale.
122 Each era description segment shall have the format:
123 .RS
124 .IP
125 .IR direction : offset : start_date : end_date : era_name : era_format
126 .RE
127 .IP
128 according to the definitions below:
129 .RS
130 .TP 12
131 .I direction
132 Either a
133 .RB \[dq] + "\[dq] or a \[dq]" - \[dq]
134 character.
135 The
136 .RB \[dq] + \[dq]
137 means that years increase from the
138 .I start_date
139 towards the
140 .IR end_date ,
141 .RB \[dq] - \[dq]
142 means the opposite.
143 .TP
144 .I offset
145 The epoch year of the
146 .IR start_date .
147 .TP
148 .I start_date
149 A date in the form
150 .IR yyyy / mm / dd ,
151 where
152 .IR yyyy ", " mm ", and " dd
153 are the year, month, and day numbers respectively of the start of the era.
154 .TP
155 .I end_date
156 The ending date of the era, in the same format as the
157 .IR start_date ,
158 or one of the two special values
159 .RB \[dq] -* \[dq]
160 (minus infinity) or
161 .RB \[dq] +* \[dq]
162 (plus infinity).
163 .TP
164 .I era_name
165 The name of the era, corresponding to the
166 .B %EC
167 .BR strftime (3)
168 conversion specification.
169 .TP
170 .I era_format
171 The format of the year in the era, corresponding to the
172 .B %EY
173 .BR strftime (3)
174 conversion specification.
175 .RE
176 .IP
177 Era description segments are separated by semicolons.
178 Most locales do not define this value.
179 Examples of locales that do define this value are the Japanese and Thai
180 locales.
181 .TP
182 .BR ERA_D_T_FMT \ (LC_TIME)
183 Return a string that can be used as a format string for
184 .BR strftime (3)
185 for alternative representation of time and date in a locale-specific way
186 .RB ( %Ec
187 conversion specification).
188 .TP
189 .BR ERA_D_FMT \ (LC_TIME)
190 Return a string that can be used as a format string for
191 .BR strftime (3)
192 for alternative representation of a date in a locale-specific way
193 .RB ( %Ex
194 conversion specification).
195 .TP
196 .BR ERA_T_FMT \ (LC_TIME)
197 Return a string that can be used as a format string for
198 .BR strftime (3)
199 for alternative representation of a time in a locale-specific way
200 .RB ( %EX
201 conversion specification).
202 .TP
203 .BR DAY_ "{1\[en]7} (LC_TIME)"
204 Return name of the
205 .IR n -th
206 day of the week.
207 [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.]
210 (Used in
211 .B %A
212 .BR strftime (3)
213 conversion specification.)
214 .TP
215 .BR ABDAY_ "{1\[en]7} (LC_TIME)"
216 Return abbreviated name of the
217 .IR n -th
218 day of the week.
219 (Used in
220 .B %a
221 .BR strftime (3)
222 conversion specification.)
223 .TP
224 .BR MON_ "{1\[en]12} (LC_TIME)"
225 Return name of the
226 .IR n -th
227 month.
228 (Used in
229 .B %B
230 .BR strftime (3)
231 conversion specification.)
232 .TP
233 .BR ABMON_ "{1\[en]12} (LC_TIME)"
234 Return abbreviated name of the
235 .IR n -th
236 month.
237 (Used in
238 .B %b
239 .BR strftime (3)
240 conversion specification.)
241 .TP
242 .BR RADIXCHAR \ (LC_NUMERIC)
243 Return radix character (decimal dot, decimal comma, etc.).
244 .TP
245 .BR THOUSEP \ (LC_NUMERIC)
246 Return separator character for thousands (groups of three digits).
247 .TP
248 .BR YESEXPR \ (LC_MESSAGES)
249 Return a regular expression that can be used with the
250 .BR regex (3)
251 function to recognize a positive response to a yes/no question.
252 .TP
253 .BR NOEXPR \ (LC_MESSAGES)
254 Return a regular expression that can be used with the
255 .BR regex (3)
256 function to recognize a negative response to a yes/no question.
257 .TP
258 .BR CRNCYSTR \ (LC_MONETARY)
259 Return the currency symbol, preceded by "\-" if the symbol should
260 appear before the value, "+" if the symbol should appear after the
261 value, or "." if the symbol should replace the radix character.
262 .P
263 The above list covers just some examples of items that can be requested.
264 For a more detailed list, consult
265 .IR "The GNU C Library Reference Manual" .
266 .SH RETURN VALUE
267 On success, these functions return a pointer to a string which
268 is the value corresponding to
269 .I item
270 in the specified locale.
271 .P
272 If no locale has been selected by
273 .BR setlocale (3)
274 for the appropriate category,
275 .BR nl_langinfo ()
276 return a pointer to the corresponding string in the "C" locale.
277 The same is true of
278 .BR nl_langinfo_l ()
279 if
280 .I locale
281 specifies a locale where
282 .I langinfo
283 data is not defined.
284 .P
285 If
286 .I item
287 is not valid, a pointer to an empty string is returned.
288 .P
289 The pointer returned by these functions may point to static data that
290 may be overwritten, or the pointer itself may be invalidated,
291 by a subsequent call to
292 .BR nl_langinfo (),
293 .BR nl_langinfo_l (),
294 or
295 .BR setlocale (3).
296 The same statements apply to
297 .BR nl_langinfo_l ()
298 if the locale object referred to by
299 .I locale
300 is freed or modified by
301 .BR freelocale (3)
302 or
303 .BR newlocale (3).
304 .P
305 POSIX specifies that the application may not modify
306 the string returned by these functions.
307 .SH ATTRIBUTES
308 For an explanation of the terms used in this section, see
309 .BR attributes (7).
310 .TS
311 allbox;
312 lbx lb lb
313 l l l.
314 Interface Attribute Value
315 T{
316 .na
317 .nh
318 .BR nl_langinfo ()
319 T} Thread safety MT-Safe locale
320 .TE
321 .SH STANDARDS
322 POSIX.1-2008.
323 .SH HISTORY
324 POSIX.1-2001, SUSv2.
325 .SH NOTES
326 The behavior of
327 .BR nl_langinfo_l ()
328 is undefined if
329 .I locale
330 is the special locale object
331 .B LC_GLOBAL_LOCALE
332 or is not a valid locale object handle.
333 .SH EXAMPLES
334 The following program sets the character type and the numeric locale
335 according to the environment and queries the terminal character set and
336 the radix character.
337 .P
338 .\" SRC BEGIN (nl_langinfo.c)
339 .EX
340 #include <langinfo.h>
341 #include <locale.h>
342 #include <stdio.h>
343 #include <stdlib.h>
344 \&
345 int
346 main(void)
347 {
348 setlocale(LC_CTYPE, "");
349 setlocale(LC_NUMERIC, "");
350 \&
351 printf("%s\[rs]n", nl_langinfo(CODESET));
352 printf("%s\[rs]n", nl_langinfo(RADIXCHAR));
353 \&
354 exit(EXIT_SUCCESS);
355 }
356 .EE
357 .\" SRC END
358 .SH SEE ALSO
359 .BR locale (1),
360 .BR localeconv (3),
361 .BR setlocale (3),
362 .BR charsets (7),
363 .BR locale (7)
364 .P
365 The GNU C Library Reference Manual