README: Update links
[man-pages.git] / man3 / nl_langinfo.3
blobd50b0f91b81ed2bd9473d24d562fd688d9c46708
1 '\" t
2 .\" Copyright (c) 2001 Markus Kuhn <mkuhn@acm.org>
3 .\" and Copyright (c) 2015 Sam Varshavchik <mrsam@courier-mta.com>
4 .\" and Copyright (c) 2015 Michael Kerrisk <mtk.manpages@gmail.com>
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 (date) "Linux man-pages (unreleased)"
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>
24 .BI "char *nl_langinfo(nl_item " item );
25 .BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale );
26 .fi
28 .RS -4
29 Feature Test Macro Requirements for glibc (see
30 .BR feature_test_macros (7)):
31 .RE
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.
60 Examples for the locale elements that can be specified in \fIitem\fP
61 using the constants defined in \fI<langinfo.h>\fP are:
62 .TP
63 .BR CODESET \ (LC_CTYPE)
64 Return a string with the name of the character encoding used in the
65 selected locale, such as "UTF-8", "ISO-8859-1", or "ANSI_X3.4-1968"
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,
70 try "locale \-m" (see
71 .BR locale (1)).
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)
76 to represent time and date in a locale-specific way
77 .RB ( %c
78 conversion specification).
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)
83 to represent a date in a locale-specific way
84 .RB ( %x
85 conversion specification).
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)
90 to represent a time in a locale-specific way
91 .RB ( %X
92 conversion specification).
93 .TP
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.)
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.)
110 .BR T_FMT_AMPM \ (LC_TIME)
111 Return a string that can be used as a format string for
112 .BR strftime (3)
113 to represent a time in a.m. or p.m. notation in a locale-specific way
114 .RB ( %r
115 conversion specification).
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:
123 .IR direction : offset : start_date : end_date : era_name : era_format
126 according to the definitions below:
128 .TP 12
129 .I direction
130 Either a
131 .RB \[dq] + "\[dq] or a \[dq]" - \[dq]
132 character.
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.
142 .I offset
143 The epoch year of the
144 .IR start_date .
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.
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).
162 .I era_name
163 The name of the era, corresponding to the
164 .B %EC
165 .BR strftime (3)
166 conversion specification.
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.
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.
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).
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).
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).
201 .BR DAY_ "{1\[en]7} (LC_TIME)"
202 Return name of the \fIn\fP-th day of the week.
203 [Warning: this follows
204 the US convention DAY_1 = Sunday, not the international convention
205 (ISO 8601) that Monday is the first day of the week.]
206 (Used in
207 .B %A
208 .BR strftime (3)
209 conversion specification.)
211 .BR ABDAY_ "{1\[en]7} (LC_TIME)"
212 Return abbreviated name of the \fIn\fP-th day of the week.
213 (Used in
214 .B %a
215 .BR strftime (3)
216 conversion specification.)
218 .BR MON_ "{1\[en]12} (LC_TIME)"
219 Return name of the \fIn\fP-th month.
220 (Used in
221 .B %B
222 .BR strftime (3)
223 conversion specification.)
225 .BR ABMON_ "{1\[en]12} (LC_TIME)"
226 Return abbreviated name of the \fIn\fP-th month.
227 (Used in
228 .B %b
229 .BR strftime (3)
230 conversion specification.)
232 .BR RADIXCHAR \ (LC_NUMERIC)
233 Return radix character (decimal dot, decimal comma, etc.).
235 .BR THOUSEP \ (LC_NUMERIC)
236 Return separator character for thousands (groups of three digits).
238 .BR YESEXPR \ (LC_MESSAGES)
239 Return a regular expression that can be used with the
240 .BR regex (3)
241 function to recognize a positive response to a yes/no question.
243 .BR NOEXPR \ (LC_MESSAGES)
244 Return a regular expression that can be used with the
245 .BR regex (3)
246 function to recognize a negative response to a yes/no question.
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.
253 The above list covers just some examples of items that can be requested.
254 For a more detailed list, consult
255 .IR "The GNU C Library Reference Manual" .
256 .SH RETURN VALUE
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.
262 If no locale has been selected by
263 .BR setlocale (3)
264 for the appropriate category,
265 .BR nl_langinfo ()
266 return a pointer to the corresponding string in the "C" locale.
267 The same is true of
268 .BR nl_langinfo_l ()
270 .I locale
271 specifies a locale where
272 .I langinfo
273 data is not defined.
275 If \fIitem\fP is not valid, a pointer to an empty string is returned.
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 (),
283 .BR setlocale (3).
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)
291 .BR newlocale (3).
293 POSIX specifies that the application may not modify
294 the string returned by these functions.
295 .SH ATTRIBUTES
296 For an explanation of the terms used in this section, see
297 .BR attributes (7).
299 allbox;
300 lbx lb lb
301 l l l.
302 Interface       Attribute       Value
306 .BR nl_langinfo ()
307 T}      Thread safety   MT-Safe locale
309 .SH STANDARDS
310 POSIX.1-2008.
311 .SH HISTORY
312 POSIX.1-2001, SUSv2.
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
319 .B LC_GLOBAL_LOCALE
320 or is not a valid locale object handle.
321 .SH EXAMPLES
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.
326 .\" SRC BEGIN (nl_langinfo.c)
328 #include <langinfo.h>
329 #include <locale.h>
330 #include <stdio.h>
331 #include <stdlib.h>
334 main(void)
336     setlocale(LC_CTYPE, "");
337     setlocale(LC_NUMERIC, "");
339     printf("%s\en", nl_langinfo(CODESET));
340     printf("%s\en", nl_langinfo(RADIXCHAR));
342     exit(EXIT_SUCCESS);
345 .\" SRC END
346 .SH SEE ALSO
347 .BR locale (1),
348 .BR localeconv (3),
349 .BR setlocale (3),
350 .BR charsets (7),
351 .BR locale (7)
353 The GNU C Library Reference Manual