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  2015-07-31 "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 .SH DESCRIPTION
  30 The
  31 .BR nl_langinfo ()
  32 and
  33 .BR nl_langinfo_l ()
  34 functions provide access to locale information
  35 in a more flexible way than
  36 .BR localeconv (3).
  37 .BR nl_langinfo()
  38 returns a string which is the value corresponding to
  39 \fIitem\fP in the program's current global
  40 locale.
  41 .BR nl_langinfo()
  42 returns a string which is the value corresponding to \fIitem\fP
  43 for the locale identified by the locale object \fIlocale\fP,
  44 which was previously created by
  45 .BR newlocale (1).
  46 Individual and additional elements of the locale categories can
  47 be queried.
  48 .PP
  49 Examples for the locale elements that can be specified in \fIitem\fP
  50 using the constants defined in \fI<langinfo.h>\fP are:
  51 .TP
  52 .BR CODESET \ (LC_CTYPE)
  53 Return a string with the name of the character encoding used in the
  54 selected locale, such as "UTF-8", "ISO-8859-1", or "ANSI_X3.4-1968"
  55 (better known as US-ASCII).
  56 This is the same string that you get with
  57 "locale charmap".
  58 For a list of character encoding names,
  59 try "locale \-m", cf.\&
  60 .BR locale (1).
  61 .TP
  62 .BR D_T_FMT \ (LC_TIME)
  63 Return a string that can be used as a format string for
  64 .BR strftime (3)
  65 to represent time and date in a locale-specific way.
  66 .TP
  67 .BR D_FMT \ (LC_TIME)
  68 Return a string that can be used as a format string for
  69 .BR strftime (3)
  70 to represent a date in a locale-specific way.
  71 .TP
  72 .BR T_FMT \ (LC_TIME)
  73 Return a string that can be used as a format string for
  74 .BR strftime (3)
  75 to represent a time in a locale-specific way.
  76 .TP
  77 .BR DAY_ "{1\(en7} (LC_TIME)"
  78 Return name of the \fIn\fP-th day of the week. [Warning: this follows
  79 the US convention DAY_1 = Sunday, not the international convention
  80 (ISO 8601) that Monday is the first day of the week.]
  81 .TP
  82 .BR ABDAY_ "{1\(en7} (LC_TIME)"
  83 Return abbreviated name of the \fIn\fP-th day of the week.
  84 .TP
  85 .BR MON_ "{1\(en12} (LC_TIME)"
  86 Return name of the \fIn\fP-th month.
  87 .TP
  88 .BR ABMON_ "{1\(en12} (LC_TIME)"
  89 Return abbreviated name of the \fIn\fP-th month.
  90 .TP
  91 .BR RADIXCHAR \ (LC_NUMERIC)
  92 Return radix character (decimal dot, decimal comma, etc.).
  93 .TP
  94 .BR THOUSEP \ (LC_NUMERIC)
  95 Return separator character for thousands (groups of three digits).
  96 .TP
  97 .BR YESEXPR \ (LC_MESSAGES)
  98 Return a regular expression that can be used with the
  99 .BR regex (3)
 100 function to recognize a positive response to a yes/no question.
 101 .TP
 102 .BR NOEXPR \ (LC_MESSAGES)
 103 Return a regular expression that can be used with the
 104 .BR regex (3)
 105 function to recognize a negative response to a yes/no question.
 106 .TP
 107 .BR CRNCYSTR \ (LC_MONETARY)
 108 Return the currency symbol, preceded by "\-" if the symbol should
 109 appear before the value, "+" if the symbol should appear after the
 110 value, or "." if the symbol should replace the radix character.
 111 .PP
 112 The above list covers just some examples of items that can be requested.
 113 For a more detailed list, consult
 114 .IR "The GNU C Library Reference Manual" .
 115 .SH RETURN VALUE
 116 On success, these functions return a pointer to a string which
 117 is the value corresponding to
 118 .I item
 119 in the specified locale.
 120
 121 If no locale has been selected by
 122 .BR setlocale (3)
 123 for the appropriate category,
 124 .BR nl_langinfo ()
 125 return a pointer to the corresponding string in the "C" locale.
 126 The same is true of
 127 .BR nl_langinfo_l ()
 128 if
 129 .I locale
 130 specifies a locale where
 131 .I langinfo
 132 data is not defined.
 133 .PP
 134 If \fIitem\fP is not valid, a pointer to an empty string is returned.
 135 .PP
 136 The pointer returned by these functions may point to static data that
 137 may be overwritten, or the pointer itself may be invalidated,
 138 by a subsequent call to
 139 .BR nl_langinfo (),
 140 .BR nl_langinfo_l (),
 141 or
 142 .BR setlocale (3).
 143 The same statements apply to
 144 .BR nl_langinfo_l ()
 145 if the locale object referred to by
 146 .I locale
 147 is freed or modified by
 148 .BR freelocale (3)
 149 or
 150 .BR newlocale (3).
 151
 152 POSIX specifies that the application may not modify
 153 the string returned by these functions.
 154 .SH ATTRIBUTES
 155 For an explanation of the terms used in this section, see
 156 .BR attributes (7).
 157 .TS
 158 allbox;
 159 lb lb lb
 160 l l l.
 161 Interface       Attribute       Value
 162 T{
 163 .BR nl_langinfo ()
 164 T}      Thread safety   MT-Safe locale
 165 .TE
 166 .SH CONFORMING TO
 167 POSIX.1-2001, POSIX.1-2008, SUSv2.
 168 .SH NOTES
 169 The behavior of
 170 .BR nl_langinfo_l ()
 171 is undefined if
 172 .I locale
 173 is the special locale object
 174 .BR LC_GLOBAL_LOCALE
 175 or is not a valid locale object handle.
 176 .SH EXAMPLE
 177 The following program sets the character type and the numeric locale
 178 according to the environment and queries the terminal character set and
 179 the radix character.
 180 .LP
 181 .nf
 182 #include <langinfo.h>
 183 #include <locale.h>
 184 #include <stdio.h>
 185 #include <stdlib.h>
 186
 187 int
 188 main(int argc, char *argv[])
 189 {
 190     setlocale(LC_CTYPE, "");
 191     setlocale(LC_NUMERIC, "");
 192
 193     printf("%s\\n", nl_langinfo(CODESET));
 194     printf("%s\\n", nl_langinfo(RADIXCHAR));
 195
 196     exit(EXIT_SUCCESS);
 197 }
 198 .fi
 199 .SH SEE ALSO
 200 .BR locale (1),
 201 .BR localeconv (3),
 202 .BR setlocale (3),
 203 .BR charsets (7),
 204 .BR locale (7)
 205 .br
 206 The GNU C Library Reference Manual