man3/nl_langinfo.3

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