| 1 | SETLOCALE(3) BSD Programmer's Manual SETLOCALE(3) |
| 2 | |
| 3 | N\bNA\bAM\bME\bE |
| 4 | s\bse\bet\btl\blo\boc\bca\bal\ble\be, l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv - natural language formatting for C |
| 5 | |
| 6 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS |
| 7 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<l\blo\boc\bca\bal\ble\be.\b.h\bh>\b> |
| 8 | |
| 9 | _\bc_\bh_\ba_\br _\b* |
| 10 | s\bse\bet\btl\blo\boc\bca\bal\ble\be(_\bi_\bn_\bt _\bc_\ba_\bt_\be_\bg_\bo_\br_\by, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bl_\bo_\bc_\ba_\bl_\be); |
| 11 | |
| 12 | _\bs_\bt_\br_\bu_\bc_\bt _\bl_\bc_\bo_\bn_\bv _\b* |
| 13 | l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv(_\bv_\bo_\bi_\bd); |
| 14 | |
| 15 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN |
| 16 | The s\bse\bet\btl\blo\boc\bca\bal\ble\be() function sets the C library's notion of natural language |
| 17 | formatting style for particular sets of routines. Each such style is |
| 18 | called a `locale' and is invoked using an appropriate name passed as a C |
| 19 | string. The l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() routine returns the current locale's parameters |
| 20 | for formatting numbers. |
| 21 | |
| 22 | The s\bse\bet\btl\blo\boc\bca\bal\ble\be() function recognizes several categories of routines. |
| 23 | These are the categories and the sets of routines they select: |
| 24 | |
| 25 | LC_ALL Set the entire locale generically. |
| 26 | |
| 27 | LC_COLLATE Set a locale for string collation routines. This controls |
| 28 | alphabetic ordering in s\bst\btr\brc\bco\bol\bll\bl() and s\bst\btr\brx\bxf\bfr\brm\bm(). |
| 29 | |
| 30 | LC_CTYPE Set a locale for the ctype(3), mbrune(3), multibyte(3) and |
| 31 | rune(3) functions. This controls recognition of upper and |
| 32 | lower case, alphabetic or non-alphabetic characters, and so |
| 33 | on. The real work is done by the s\bse\bet\btr\bru\bun\bne\bel\blo\boc\bca\bal\ble\be() function. |
| 34 | |
| 35 | LC_MONETARY Set a locale for formatting monetary values; this affects |
| 36 | the l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() function. |
| 37 | |
| 38 | LC_NUMERIC Set a locale for formatting numbers. This controls the for- |
| 39 | matting of decimal points in input and output of floating |
| 40 | point numbers in functions such as p\bpr\bri\bin\bnt\btf\bf() and s\bsc\bca\ban\bnf\bf(), as |
| 41 | well as values returned by l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv(). |
| 42 | |
| 43 | LC_TIME Set a locale for formatting dates and times using the |
| 44 | s\bst\btr\brf\bft\bti\bim\bme\be() function. |
| 45 | |
| 46 | Only three locales are defined by default, the empty string "" which de- |
| 47 | notes the native environment, and the "C" and locales, which denote the C |
| 48 | language environment. A _\bl_\bo_\bc_\ba_\bl_\be argument of NULL causes s\bse\bet\btl\blo\boc\bca\bal\ble\be() to |
| 49 | return the current locale. By default, C programs start in the "C" lo- |
| 50 | cale. The only function in the library that sets the locale is |
| 51 | s\bse\bet\btl\blo\boc\bca\bal\ble\be(); the locale is never changed as a side effect of some other |
| 52 | routine. |
| 53 | |
| 54 | The l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() function returns a pointer to a structure which provides |
| 55 | parameters for formatting numbers, especially currency values: |
| 56 | |
| 57 | struct lconv { |
| 58 | char *decimal_point; |
| 59 | char *thousands_sep; |
| 60 | char *grouping; |
| 61 | char *int_curr_symbol; |
| 62 | char *currency_symbol; |
| 63 | char *mon_decimal_point; |
| 64 | char *mon_thousands_sep; |
| 65 | char *mon_grouping; |
| 66 | char *positive_sign; |
| 67 | char *negative_sign; |
| 68 | char int_frac_digits; |
| 69 | char frac_digits; |
| 70 | char p_cs_precedes; |
| 71 | char p_sep_by_space; |
| 72 | char n_cs_precedes; |
| 73 | char n_sep_by_space; |
| 74 | char p_sign_posn; |
| 75 | char n_sign_posn; |
| 76 | }; |
| 77 | |
| 78 | The individual fields have the following meanings: |
| 79 | |
| 80 | _\bd_\be_\bc_\bi_\bm_\ba_\bl_\b__\bp_\bo_\bi_\bn_\bt The decimal point character, except for currency val- |
| 81 | ues. |
| 82 | |
| 83 | _\bt_\bh_\bo_\bu_\bs_\ba_\bn_\bd_\bs_\b__\bs_\be_\bp The separator between groups of digits before the dec- |
| 84 | imal point, except for currency values. |
| 85 | |
| 86 | _\bg_\br_\bo_\bu_\bp_\bi_\bn_\bg The sizes of the groups of digits, except for currency |
| 87 | values. This is a pointer to a vector of integers, |
| 88 | each of size _\bc_\bh_\ba_\br, representing group size from low |
| 89 | order digit groups to high order (right to left). The |
| 90 | list may be terminated with 0 or CHAR_MAX. If the list |
| 91 | is terminated with 0, the last group size before the 0 |
| 92 | is repeated to account for all the digits. If the |
| 93 | list is terminated with CHAR_MAX, no more grouping is |
| 94 | performed. |
| 95 | |
| 96 | _\bi_\bn_\bt_\b__\bc_\bu_\br_\br_\b__\bs_\by_\bm_\bb_\bo_\bl The standardized international currency symbol. |
| 97 | |
| 98 | _\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl The local currency symbol. |
| 99 | |
| 100 | _\bm_\bo_\bn_\b__\bd_\be_\bc_\bi_\bm_\ba_\bl_\b__\bp_\bo_\bi_\bn_\bt The decimal point character for currency values. |
| 101 | |
| 102 | _\bm_\bo_\bn_\b__\bt_\bh_\bo_\bu_\bs_\ba_\bn_\bd_\bs_\b__\bs_\be_\bp The separator for digit groups in currency values. |
| 103 | |
| 104 | _\bm_\bo_\bn_\b__\bg_\br_\bo_\bu_\bp_\bi_\bn_\bg Like _\bg_\br_\bo_\bu_\bp_\bi_\bn_\bg but for currency values. |
| 105 | |
| 106 | _\bp_\bo_\bs_\bi_\bt_\bi_\bv_\be_\b__\bs_\bi_\bg_\bn The character used to denote nonnegative currency val- |
| 107 | ues, usually the empty string. |
| 108 | |
| 109 | _\bn_\be_\bg_\ba_\bt_\bi_\bv_\be_\b__\bs_\bi_\bg_\bn The character used to denote negative currency values, |
| 110 | usually a minus sign. |
| 111 | |
| 112 | _\bi_\bn_\bt_\b__\bf_\br_\ba_\bc_\b__\bd_\bi_\bg_\bi_\bt_\bs The number of digits after the decimal point in an in- |
| 113 | ternational-style currency value. |
| 114 | |
| 115 | _\bf_\br_\ba_\bc_\b__\bd_\bi_\bg_\bi_\bt_\bs The number of digits after the decimal point in the |
| 116 | local style for currency values. |
| 117 | |
| 118 | _\bp_\b__\bc_\bs_\b__\bp_\br_\be_\bc_\be_\bd_\be_\bs 1 if the currency symbol precedes the currency value |
| 119 | for nonnegative values, 0 if it follows. |
| 120 | |
| 121 | _\bp_\b__\bs_\be_\bp_\b__\bb_\by_\b__\bs_\bp_\ba_\bc_\be 1 if a space is inserted between the currency symbol |
| 122 | and the currency value for nonnegative values, 0 oth- |
| 123 | erwise. |
| 124 | |
| 125 | _\bn_\b__\bc_\bs_\b__\bp_\br_\be_\bc_\be_\bd_\be_\bs Like _\bp_\b__\bc_\bs_\b__\bp_\br_\be_\bc_\be_\bd_\be_\bs but for negative values. |
| 126 | |
| 127 | _\bn_\b__\bs_\be_\bp_\b__\bb_\by_\b__\bs_\bp_\ba_\bc_\be Like _\bp_\b__\bs_\be_\bp_\b__\bb_\by_\b__\bs_\bp_\ba_\bc_\be but for negative values. |
| 128 | |
| 129 | _\bp_\b__\bs_\bi_\bg_\bn_\b__\bp_\bo_\bs_\bn The location of the _\bp_\bo_\bs_\bi_\bt_\bi_\bv_\be_\b__\bs_\bi_\bg_\bn with respect to a |
| 130 | nonnegative quantity and the _\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl, coded as |
| 131 | |
| 132 | follows: |
| 133 | 0 Parentheses around the entire string. |
| 134 | 1 Before the string. |
| 135 | 2 After the string. |
| 136 | 3 Just before _\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl. |
| 137 | 4 Just after _\bc_\bu_\br_\br_\be_\bn_\bc_\by_\b__\bs_\by_\bm_\bb_\bo_\bl. |
| 138 | |
| 139 | _\bn_\b__\bs_\bi_\bg_\bn_\b__\bp_\bo_\bs_\bn Like _\bp_\b__\bs_\bi_\bg_\bn_\b__\bp_\bo_\bs_\bn but for negative currency values. |
| 140 | |
| 141 | Unless mentioned above, an empty string as a value for a field indicates |
| 142 | a zero length result or a value that is not in the current locale. A |
| 143 | CHAR_MAX result similarly denotes an unavailable value. |
| 144 | |
| 145 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS |
| 146 | The s\bse\bet\btl\blo\boc\bca\bal\ble\be() function returns NULL and fails to change the locale if |
| 147 | the given combination of _\bc_\ba_\bt_\be_\bg_\bo_\br_\by and _\bl_\bo_\bc_\ba_\bl_\be makes no sense. The |
| 148 | l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() function returns a pointer to a static object which may be |
| 149 | altered by later calls to s\bse\bet\btl\blo\boc\bca\bal\ble\be() or l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv(). |
| 150 | |
| 151 | F\bFI\bIL\bLE\bES\bS |
| 152 | $PATH_LOCALE/_\bl_\bo_\bc_\ba_\bl_\be/_\bc_\ba_\bt_\be_\bg_\bo_\br_\by |
| 153 | /usr/share/locale/_\bl_\bo_\bc_\ba_\bl_\be/_\bc_\ba_\bt_\be_\bg_\bo_\br_\by locale file for the locale _\bl_\bo_\bc_\ba_\bl_\be and |
| 154 | the category _\bc_\ba_\bt_\be_\bg_\bo_\br_\by. |
| 155 | |
| 156 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO |
| 157 | euc(4), mbrune(3), multibyte(3), rune(3), strcoll(3), strxfrm(3), |
| 158 | utf2(4) |
| 159 | |
| 160 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS |
| 161 | The s\bse\bet\btl\blo\boc\bca\bal\ble\be() and l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() functions conform to ANSI C X3.159-1989 |
| 162 | (``ANSI C ''). |
| 163 | |
| 164 | H\bHI\bIS\bST\bTO\bOR\bRY\bY |
| 165 | The s\bse\bet\btl\blo\boc\bca\bal\ble\be() and l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv() functions first appeared in 4.4BSD. |
| 166 | |
| 167 | B\bBU\bUG\bGS\bS |
| 168 | The current implementation supports only the "C" and "POSIX" locales for |
| 169 | all but the LC_CTYPE locale. |
| 170 | |
| 171 | In spite of the gnarly currency support in l\blo\boc\bca\bal\ble\bec\bco\bon\bnv\bv(), the standards |
| 172 | don't include any functions for generalized currency formatting. |
| 173 | |
| 174 | LC_COLLATE does not make sense for many languages. Use of LC_MONETARY |
| 175 | could lead to misleading results until we have a real time currency con- |
| 176 | version function. LC_NUMERIC and LC_TIME are personal choices and should |
| 177 | not be wrapped up with the other categories. |
| 178 | |
| 179 | 4.4BSD June 9, 1993 3 |