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  2017-07-13 "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 .sp
  25 .BI "char *nl_langinfo(nl_item " item );
  26 .sp
  27 .BI "char *nl_langinfo_l(nl_item " item ", locale_t " locale );
  28 .fi
  29 .sp
  30 .in -4n
  31 Feature Test Macro Requirements for glibc (see
  32 .BR feature_test_macros (7)):
  33 .in
  34 .sp
  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()
  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", cf.\&
  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 .TP
  83 .BR D_FMT \ (LC_TIME)
  84 Return a string that can be used as a format string for
  85 .BR strftime (3)
  86 to represent a date in a locale-specific way.
  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 .TP
  93 .BR DAY_ "{1\(en7} (LC_TIME)"
  94 Return name of the \fIn\fP-th day of the week. [Warning: this follows
  95 the US convention DAY_1 = Sunday, not the international convention
  96 (ISO 8601) that Monday is the first day of the week.]
  97 .TP
  98 .BR ABDAY_ "{1\(en7} (LC_TIME)"
  99 Return abbreviated name of the \fIn\fP-th day of the week.
 100 .TP
 101 .BR MON_ "{1\(en12} (LC_TIME)"
 102 Return name of the \fIn\fP-th month.
 103 .TP
 104 .BR ABMON_ "{1\(en12} (LC_TIME)"
 105 Return abbreviated name of the \fIn\fP-th month.
 106 .TP
 107 .BR RADIXCHAR \ (LC_NUMERIC)
 108 Return radix character (decimal dot, decimal comma, etc.).
 109 .TP
 110 .BR THOUSEP \ (LC_NUMERIC)
 111 Return separator character for thousands (groups of three digits).
 112 .TP
 113 .BR YESEXPR \ (LC_MESSAGES)
 114 Return a regular expression that can be used with the
 115 .BR regex (3)
 116 function to recognize a positive response to a yes/no question.
 117 .TP
 118 .BR NOEXPR \ (LC_MESSAGES)
 119 Return a regular expression that can be used with the
 120 .BR regex (3)
 121 function to recognize a negative response to a yes/no question.
 122 .TP
 123 .BR CRNCYSTR \ (LC_MONETARY)
 124 Return the currency symbol, preceded by "\-" if the symbol should
 125 appear before the value, "+" if the symbol should appear after the
 126 value, or "." if the symbol should replace the radix character.
 127 .PP
 128 The above list covers just some examples of items that can be requested.
 129 For a more detailed list, consult
 130 .IR "The GNU C Library Reference Manual" .
 131 .SH RETURN VALUE
 132 On success, these functions return a pointer to a string which
 133 is the value corresponding to
 134 .I item
 135 in the specified locale.
 136
 137 If no locale has been selected by
 138 .BR setlocale (3)
 139 for the appropriate category,
 140 .BR nl_langinfo ()
 141 return a pointer to the corresponding string in the "C" locale.
 142 The same is true of
 143 .BR nl_langinfo_l ()
 144 if
 145 .I locale
 146 specifies a locale where
 147 .I langinfo
 148 data is not defined.
 149 .PP
 150 If \fIitem\fP is not valid, a pointer to an empty string is returned.
 151 .PP
 152 The pointer returned by these functions may point to static data that
 153 may be overwritten, or the pointer itself may be invalidated,
 154 by a subsequent call to
 155 .BR nl_langinfo (),
 156 .BR nl_langinfo_l (),
 157 or
 158 .BR setlocale (3).
 159 The same statements apply to
 160 .BR nl_langinfo_l ()
 161 if the locale object referred to by
 162 .I locale
 163 is freed or modified by
 164 .BR freelocale (3)
 165 or
 166 .BR newlocale (3).
 167
 168 POSIX specifies that the application may not modify
 169 the string returned by these functions.
 170 .SH ATTRIBUTES
 171 For an explanation of the terms used in this section, see
 172 .BR attributes (7).
 173 .TS
 174 allbox;
 175 lb lb lb
 176 l l l.
 177 Interface       Attribute       Value
 178 T{
 179 .BR nl_langinfo ()
 180 T}      Thread safety   MT-Safe locale
 181 .TE
 182 .SH CONFORMING TO
 183 POSIX.1-2001, POSIX.1-2008, SUSv2.
 184 .SH NOTES
 185 The behavior of
 186 .BR nl_langinfo_l ()
 187 is undefined if
 188 .I locale
 189 is the special locale object
 190 .BR LC_GLOBAL_LOCALE
 191 or is not a valid locale object handle.
 192 .SH EXAMPLE
 193 The following program sets the character type and the numeric locale
 194 according to the environment and queries the terminal character set and
 195 the radix character.
 196 .LP
 197 .nf
 198 #include <langinfo.h>
 199 #include <locale.h>
 200 #include <stdio.h>
 201 #include <stdlib.h>
 202
 203 int
 204 main(int argc, char *argv[])
 205 {
 206     setlocale(LC_CTYPE, "");
 207     setlocale(LC_NUMERIC, "");
 208
 209     printf("%s\\n", nl_langinfo(CODESET));
 210     printf("%s\\n", nl_langinfo(RADIXCHAR));
 211
 212     exit(EXIT_SUCCESS);
 213 }
 214 .fi
 215 .SH SEE ALSO
 216 .BR locale (1),
 217 .BR localeconv (3),
 218 .BR setlocale (3),
 219 .BR charsets (7),
 220 .BR locale (7)
 221 .br
 222 The GNU C Library Reference Manual