lib/libc/locale/nl_langinfo.3

   1 .\" Copyright (c) 2001 Alexey Zelkin <phantom@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd December 14, 2020
  26 .Dt NL_LANGINFO 3
  27 .Os
  28 .Sh NAME
  29 .Nm nl_langinfo
  30 .Nd language information
  31 .Sh LIBRARY
  32 .Lb libc
  33 .Sh SYNOPSIS
  34 .In langinfo.h
  35 .Ft char *
  36 .Fn nl_langinfo "nl_item item"
  37 .Ft char *
  38 .Fn nl_langinfo_l "nl_item item" "locale_t loc"
  39 .Sh DESCRIPTION
  40 The
  41 .Fn nl_langinfo
  42 function returns a pointer to a string containing information relevant to
  43 the particular language or cultural area defined in the program or thread's
  44 locale, or in the case of
  45 .Fn nl_langinfo_l ,
  46 the locale passed as the second argument.
  47 .Pp
  48 Calls to
  49 .Fn setlocale
  50 with a category corresponding to the category of
  51 .Fa item ,
  52 or to the
  53 category
  54 .Dv LC_ALL ,
  55 may overwrite the buffer pointed to by the return value.
  56 .Pp
  57 The manifest constant names and values of
  58 .Fa item
  59 are defined in
  60 .In langinfo.h .
  61 .Pp
  62 The following standard constants are recognized:
  63 .Bl -column "Constant" "Category"
  64 .It Sy Constant Ta Sy Category Ta Sy Description
  65 .It Dv CODESET Ta Dv LC_CTYPE Ta codeset name
  66 .It Dv D_T_FMT Ta Dv LC_TIME Ta string for formatting date and time
  67 .It Dv D_FMT Ta Dv LC_TIME Ta date format string
  68 .It Dv T_FMT Ta Dv LC_TIME Ta time format string
  69 .It Dv T_FMT_AMPM Ta Dv LC_TIME Ta a.m. or p.m. time format string
  70 .It Dv AM_STR Ta Dv LC_TIME Ta ante-meridiem affix
  71 .It Dv PM_STR Ta Dv LC_TIME Ta post-meridiem affix
  72 .It Dv DAY_1 Ta Dv LC_TIME Ta name of the first day of the week
  73 .It Dv DAY_2 Ta Dv LC_TIME Ta name of the second day of the week
  74 .It Dv DAY_3 Ta Dv LC_TIME Ta name of the third day of the week
  75 .It Dv DAY_4 Ta Dv LC_TIME Ta name of the fourth day of the week
  76 .It Dv DAY_5 Ta Dv LC_TIME Ta name of the fifth day of the week
  77 .It Dv DAY_6 Ta Dv LC_TIME Ta name of the sixth day of the week
  78 .It Dv DAY_7 Ta Dv LC_TIME Ta name of the seventh day of the week
  79 .It Dv ABDAY_1 Ta Dv LC_TIME Ta abbreviated name of the first day of the week
  80 .It Dv ABDAY_2 Ta Dv LC_TIME Ta abbreviated name of the second day of the week
  81 .It Dv ABDAY_3 Ta Dv LC_TIME Ta abbreviated name of the third day of the week
  82 .It Dv ABDAY_4 Ta Dv LC_TIME Ta abbreviated name of the fourth day of the week
  83 .It Dv ABDAY_5 Ta Dv LC_TIME Ta abbreviated name of the fifth day of the week
  84 .It Dv ABDAY_6 Ta Dv LC_TIME Ta abbreviated name of the sixth day of the week
  85 .It Dv ABDAY_7 Ta Dv LC_TIME Ta abbreviated name of the seventh day of the week
  86 .It Dv MON_1 Ta Dv LC_TIME Ta name of the first month of the year
  87 .It Dv MON_2 Ta Dv LC_TIME Ta name of the second month
  88 .It Dv MON_3 Ta Dv LC_TIME Ta name of the third month
  89 .It Dv MON_4 Ta Dv LC_TIME Ta name of the fourth month
  90 .It Dv MON_5 Ta Dv LC_TIME Ta name of the fifth month
  91 .It Dv MON_6 Ta Dv LC_TIME Ta name of the sixth month
  92 .It Dv MON_7 Ta Dv LC_TIME Ta name of the seventh month
  93 .It Dv MON_8 Ta Dv LC_TIME Ta name of the eighth month
  94 .It Dv MON_9 Ta Dv LC_TIME Ta name of the ninth month
  95 .It Dv MON_10 Ta Dv LC_TIME Ta name of the tenth month
  96 .It Dv MON_11 Ta Dv LC_TIME Ta name of the eleventh month
  97 .It Dv MON_12 Ta Dv LC_TIME Ta name of the twelfth month
  98 .It Dv ABMON_1 Ta Dv LC_TIME Ta abbreviated name of the first month
  99 .It Dv ABMON_2 Ta Dv LC_TIME Ta abbreviated name of the second month
 100 .It Dv ABMON_3 Ta Dv LC_TIME Ta abbreviated name of the third month
 101 .It Dv ABMON_4 Ta Dv LC_TIME Ta abbreviated name of the fourth month
 102 .It Dv ABMON_5 Ta Dv LC_TIME Ta abbreviated name of the fifth month
 103 .It Dv ABMON_6 Ta Dv LC_TIME Ta abbreviated name of the sixth month
 104 .It Dv ABMON_7 Ta Dv LC_TIME Ta abbreviated name of the seventh month
 105 .It Dv ABMON_8 Ta Dv LC_TIME Ta abbreviated name of the eighth month
 106 .It Dv ABMON_9 Ta Dv LC_TIME Ta abbreviated name of the ninth month
 107 .It Dv ABMON_10 Ta Dv LC_TIME Ta abbreviated name of the tenth month
 108 .It Dv ABMON_11 Ta Dv LC_TIME Ta abbreviated name of the eleventh month
 109 .It Dv ABMON_12 Ta Dv LC_TIME Ta abbreviated name of the twelfth month
 110 .It Dv ERA Ta Dv LC_TIME Ta era description segments
 111 .It Dv ERA_D_FMT Ta Dv LC_TIME Ta era date format string
 112 .It Dv ERA_D_T_FMT Ta Dv LC_TIME Ta era date and time format string
 113 .It Dv ERA_T_FMT Ta Dv LC_TIME Ta era time format string
 114 .It Dv ALT_DIGITS Ta Dv LC_TIME Ta alternative symbols for digits
 115 .It Dv RADIXCHAR Ta Dv LC_NUMERIC Ta radix character
 116 .It Dv THOUSEP Ta Dv LC_NUMERIC Ta separator for thousands
 117 .It Dv YESEXPR Ta Dv LC_MESSAGES Ta affirmative response extended regular
 118 expression
 119 .It Dv NOEXPR Ta Dv LC_MESSAGES Ta negative response extended regular expression
 120 .It Dv CRNCYSTR Ta Dv LC_MONETARY Ta local currency symbol, preceded by '-' if the
 121 symbol should appear before the value, '+' if the symbol should appear after the
 122 value, or '.' if the symbol should replace the radix character; if the local
 123 currency symbol is the empty string, implementations may return the empty string
 124 .Pq Qq
 125 .El
 126 .Pp
 127 The following non-standard
 128 .Fx
 129 extensions are recognized:
 130 .Bl -column "Constant" "Category"
 131 .It Sy Constant Ta Sy Category Ta Sy Description
 132 .It Dv D_MD_ORDER Ta Dv LC_TIME Ta month/day order
 133 .It Dv ALTMON_1 Ta Dv LC_TIME Ta standalone name of the first month
 134 .It Dv ALTMON_2 Ta Dv LC_TIME Ta standalone name of the second month
 135 .It Dv ALTMON_3 Ta Dv LC_TIME Ta standalone name of the third month
 136 .It Dv ALTMON_4 Ta Dv LC_TIME Ta standalone name of the fourth month
 137 .It Dv ALTMON_5 Ta Dv LC_TIME Ta standalone name of the fifth month
 138 .It Dv ALTMON_6 Ta Dv LC_TIME Ta standalone name of the sixth month
 139 .It Dv ALTMON_7 Ta Dv LC_TIME Ta standalone name of the seventh month
 140 .It Dv ALTMON_8 Ta Dv LC_TIME Ta standalone name of the eighth month
 141 .It Dv ALTMON_9 Ta Dv LC_TIME Ta standalone name of the ninth month
 142 .It Dv ALTMON_10 Ta Dv LC_TIME Ta standalone name of the tenth month
 143 .It Dv ALTMON_11 Ta Dv LC_TIME Ta standalone name of the eleventh month
 144 .It Dv ALTMON_12 Ta Dv LC_TIME Ta standalone name of the twelfth month
 145 .It Dv YESSTR Ta Dv LC_MESSAGES Ta affirmative response string
 146 .It Dv NOSTR Ta Dv LC_MESSAGES Ta negative response string
 147 .El
 148 .Sh RETURN VALUES
 149 In a locale where langinfo data is not defined,
 150 .Fn nl_langinfo
 151 returns a pointer to the corresponding string in the POSIX locale.
 152 .Fn nl_langinfo_l
 153 returns the same values as
 154 .Fn nl_langinfo .
 155 In all locales,
 156 .Fn nl_langinfo
 157 returns a pointer to an empty string if
 158 .Fa item
 159 contains an invalid setting.
 160 .Sh EXAMPLES
 161 For example:
 162 .Pp
 163 .Dl nl_langinfo(ABDAY_1)
 164 .Pp
 165 would return a pointer to the string
 166 .Qq Li Dom
 167 if the identified language was
 168 Portuguese, and
 169 .Qq Li Sun
 170 if the identified language was English.
 171 .Sh SEE ALSO
 172 .Xr setlocale 3
 173 .Sh STANDARDS
 174 The
 175 .Fn nl_langinfo
 176 function conforms to
 177 .St -susv2 .
 178 The
 179 .Fn nl_langinfo_l
 180 function conforms to
 181 .St -p1003.1-2008 .
 182 .Sh HISTORY
 183 The
 184 .Fn nl_langinfo
 185 function first appeared in
 186 .Fx 4.6 .