Debian Codegraph @

upstream/debian-trixie/man3/nl_langinfo.3

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