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 .\" $FreeBSD$
  26 .\"
  27 .Dd December 14, 2020
  28 .Dt NL_LANGINFO 3
  29 .Os
  30 .Sh NAME
  31 .Nm nl_langinfo
  32 .Nd language information
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In langinfo.h
  37 .Ft char *
  38 .Fn nl_langinfo "nl_item item"
  39 .Ft char *
  40 .Fn nl_langinfo_l "nl_item item" "locale_t loc"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn nl_langinfo
  44 function returns a pointer to a string containing information relevant to
  45 the particular language or cultural area defined in the program or thread's
  46 locale, or in the case of
  47 .Fn nl_langinfo_l ,
  48 the locale passed as the second argument.
  49 .Pp
  50 Calls to
  51 .Fn setlocale
  52 with a category corresponding to the category of
  53 .Fa item ,
  54 or to the
  55 category
  56 .Dv LC_ALL ,
  57 may overwrite the buffer pointed to by the return value.
  58 .Pp
  59 The manifest constant names and values of
  60 .Fa item
  61 are defined in
  62 .In langinfo.h .
  63 .Pp
  64 The following standard constants are recognized:
  65 .Bl -column "Constant" "Category"
  66 .It Sy Constant Ta Sy Category Ta Sy Description
  67 .It Dv CODESET Ta Dv LC_CTYPE Ta codeset name
  68 .It Dv D_T_FMT Ta Dv LC_TIME Ta string for formatting date and time
  69 .It Dv D_FMT Ta Dv LC_TIME Ta date format string
  70 .It Dv T_FMT Ta Dv LC_TIME Ta time format string
  71 .It Dv T_FMT_AMPM Ta Dv LC_TIME Ta a.m. or p.m. time format string
  72 .It Dv AM_STR Ta Dv LC_TIME Ta ante-meridiem affix
  73 .It Dv PM_STR Ta Dv LC_TIME Ta post-meridiem affix
  74 .It Dv DAY_1 Ta Dv LC_TIME Ta name of the first day of the week
  75 .It Dv DAY_2 Ta Dv LC_TIME Ta name of the second day of the week
  76 .It Dv DAY_3 Ta Dv LC_TIME Ta name of the third day of the week
  77 .It Dv DAY_4 Ta Dv LC_TIME Ta name of the fourth day of the week
  78 .It Dv DAY_5 Ta Dv LC_TIME Ta name of the fifth day of the week
  79 .It Dv DAY_6 Ta Dv LC_TIME Ta name of the sixth day of the week
  80 .It Dv DAY_7 Ta Dv LC_TIME Ta name of the seventh day of the week
  81 .It Dv ABDAY_1 Ta Dv LC_TIME Ta abbreviated name of the first day of the week
  82 .It Dv ABDAY_2 Ta Dv LC_TIME Ta abbreviated name of the second day of the week
  83 .It Dv ABDAY_3 Ta Dv LC_TIME Ta abbreviated name of the third day of the week
  84 .It Dv ABDAY_4 Ta Dv LC_TIME Ta abbreviated name of the fourth day of the week
  85 .It Dv ABDAY_5 Ta Dv LC_TIME Ta abbreviated name of the fifth day of the week
  86 .It Dv ABDAY_6 Ta Dv LC_TIME Ta abbreviated name of the sixth day of the week
  87 .It Dv ABDAY_7 Ta Dv LC_TIME Ta abbreviated name of the seventh day of the week
  88 .It Dv MON_1 Ta Dv LC_TIME Ta name of the first month of the year
  89 .It Dv MON_2 Ta Dv LC_TIME Ta name of the second month
  90 .It Dv MON_3 Ta Dv LC_TIME Ta name of the third month
  91 .It Dv MON_4 Ta Dv LC_TIME Ta name of the fourth month
  92 .It Dv MON_5 Ta Dv LC_TIME Ta name of the fifth month
  93 .It Dv MON_6 Ta Dv LC_TIME Ta name of the sixth month
  94 .It Dv MON_7 Ta Dv LC_TIME Ta name of the seventh month
  95 .It Dv MON_8 Ta Dv LC_TIME Ta name of the eighth month
  96 .It Dv MON_9 Ta Dv LC_TIME Ta name of the ninth month
  97 .It Dv MON_10 Ta Dv LC_TIME Ta name of the tenth month
  98 .It Dv MON_11 Ta Dv LC_TIME Ta name of the eleventh month
  99 .It Dv MON_12 Ta Dv LC_TIME Ta name of the twelfth month
 100 .It Dv ABMON_1 Ta Dv LC_TIME Ta abbreviated name of the first month
 101 .It Dv ABMON_2 Ta Dv LC_TIME Ta abbreviated name of the second month
 102 .It Dv ABMON_3 Ta Dv LC_TIME Ta abbreviated name of the third month
 103 .It Dv ABMON_4 Ta Dv LC_TIME Ta abbreviated name of the fourth month
 104 .It Dv ABMON_5 Ta Dv LC_TIME Ta abbreviated name of the fifth month
 105 .It Dv ABMON_6 Ta Dv LC_TIME Ta abbreviated name of the sixth month
 106 .It Dv ABMON_7 Ta Dv LC_TIME Ta abbreviated name of the seventh month
 107 .It Dv ABMON_8 Ta Dv LC_TIME Ta abbreviated name of the eighth month
 108 .It Dv ABMON_9 Ta Dv LC_TIME Ta abbreviated name of the ninth month
 109 .It Dv ABMON_10 Ta Dv LC_TIME Ta abbreviated name of the tenth month
 110 .It Dv ABMON_11 Ta Dv LC_TIME Ta abbreviated name of the eleventh month
 111 .It Dv ABMON_12 Ta Dv LC_TIME Ta abbreviated name of the twelfth month
 112 .It Dv ERA Ta Dv LC_TIME Ta era description segments
 113 .It Dv ERA_D_FMT Ta Dv LC_TIME Ta era date format string
 114 .It Dv ERA_D_T_FMT Ta Dv LC_TIME Ta era date and time format string
 115 .It Dv ERA_T_FMT Ta Dv LC_TIME Ta era time format string
 116 .It Dv ALT_DIGITS Ta Dv LC_TIME Ta alternative symbols for digits
 117 .It Dv RADIXCHAR Ta Dv LC_NUMERIC Ta radix character
 118 .It Dv THOUSEP Ta Dv LC_NUMERIC Ta separator for thousands
 119 .It Dv YESEXPR Ta Dv LC_MESSAGES Ta affirmative response extended regular
 120 expression
 121 .It Dv NOEXPR Ta Dv LC_MESSAGES Ta negative response extended regular expression
 122 .It Dv CRNCYSTR Ta Dv LC_MONETARY Ta local currency symbol, preceded by '-' if the
 123 symbol should appear before the value, '+' if the symbol should appear after the
 124 value, or '.' if the symbol should replace the radix character; if the local
 125 currency symbol is the empty string, implementations may return the empty string
 126 .Pq Qq
 127 .El
 128 .Pp
 129 The following non-standard
 130 .Fx
 131 extensions are recognized:
 132 .Bl -column "Constant" "Category"
 133 .It Sy Constant Ta Sy Category Ta Sy Description
 134 .It Dv D_MD_ORDER Ta Dv LC_TIME Ta month/day order
 135 .It Dv ALTMON_1 Ta Dv LC_TIME Ta standalone name of the first month
 136 .It Dv ALTMON_2 Ta Dv LC_TIME Ta standalone name of the second month
 137 .It Dv ALTMON_3 Ta Dv LC_TIME Ta standalone name of the third month
 138 .It Dv ALTMON_4 Ta Dv LC_TIME Ta standalone name of the fourth month
 139 .It Dv ALTMON_5 Ta Dv LC_TIME Ta standalone name of the fifth month
 140 .It Dv ALTMON_6 Ta Dv LC_TIME Ta standalone name of the sixth month
 141 .It Dv ALTMON_7 Ta Dv LC_TIME Ta standalone name of the seventh month
 142 .It Dv ALTMON_8 Ta Dv LC_TIME Ta standalone name of the eighth month
 143 .It Dv ALTMON_9 Ta Dv LC_TIME Ta standalone name of the ninth month
 144 .It Dv ALTMON_10 Ta Dv LC_TIME Ta standalone name of the tenth month
 145 .It Dv ALTMON_11 Ta Dv LC_TIME Ta standalone name of the eleventh month
 146 .It Dv ALTMON_12 Ta Dv LC_TIME Ta standalone name of the twelfth month
 147 .It Dv YESSTR Ta Dv LC_MESSAGES Ta affirmative response string
 148 .It Dv NOSTR Ta Dv LC_MESSAGES Ta negative response string
 149 .El
 150 .Sh RETURN VALUES
 151 In a locale where langinfo data is not defined,
 152 .Fn nl_langinfo
 153 returns a pointer to the corresponding string in the POSIX locale.
 154 .Fn nl_langinfo_l
 155 returns the same values as
 156 .Fn nl_langinfo .
 157 In all locales,
 158 .Fn nl_langinfo
 159 returns a pointer to an empty string if
 160 .Fa item
 161 contains an invalid setting.
 162 .Sh EXAMPLES
 163 For example:
 164 .Pp
 165 .Dl nl_langinfo(ABDAY_1)
 166 .Pp
 167 would return a pointer to the string
 168 .Qq Li Dom
 169 if the identified language was
 170 Portuguese, and
 171 .Qq Li Sun
 172 if the identified language was English.
 173 .Sh SEE ALSO
 174 .Xr setlocale 3
 175 .Sh STANDARDS
 176 The
 177 .Fn nl_langinfo
 178 function conforms to
 179 .St -susv2 .
 180 The
 181 .Fn nl_langinfo_l
 182 function conforms to
 183 .St -p1003.1-2008 .
 184 .Sh HISTORY
 185 The
 186 .Fn nl_langinfo
 187 function first appeared in
 188 .Fx 4.6 .