/usr/share/doc/glibc-doc/html/libc_7.html is in glibc-doc 2.15-0ubuntu10.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- This file documents the GNU C library.
This is Edition 0.13, last updated 2011-07-19,
of The GNU C Library Reference Manual, for version
2.14 (Ubuntu EGLIBC 2.15-0ubuntu10) .
Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010, 2011 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software Needs Free Documentation"
and "GNU Lesser General Public License", the Front-Cover texts being
"A GNU Manual", and with the Back-Cover Texts as in (a) below. A
copy of the license is included in the section entitled "GNU Free
Documentation License".
(a) The FSF's Back-Cover Text is: "You have the freedom to
copy and modify this GNU manual. Buying copies from the FSF
supports it in developing GNU and promoting software freedom."
-->
<!-- Created on April 20, 2012 by texi2html 1.82
texi2html was written by:
Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>The GNU C Library: 7. Locales and Internationalization</title>
<meta name="description" content="The GNU C Library: 7. Locales and Internationalization">
<meta name="keywords" content="The GNU C Library: 7. Locales and Internationalization">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.82">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Locales"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="libc_6.html#iconv-module-interfaces" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Effects-of-Locale" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc_6.html#Character-Set-Handling" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Locales-and-Internationalization"></a>
<h1 class="chapter">7. Locales and Internationalization</h1>
<p>Different countries and cultures have varying conventions for how to
communicate. These conventions range from very simple ones, such as the
format for representing dates and times, to very complex ones, such as
the language spoken.
</p>
<a name="index-internationalization"></a>
<a name="index-locales"></a>
<p><em>Internationalization</em> of software means programming it to be able
to adapt to the user’s favorite conventions. In ISO C,
internationalization works by means of <em>locales</em>. Each locale
specifies a collection of conventions, one convention for each purpose.
The user chooses a set of conventions by specifying a locale (via
environment variables).
</p>
<p>All programs inherit the chosen locale as part of their environment.
Provided the programs are written to obey the choice of locale, they
will follow the conventions preferred by the user.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Effects-of-Locale">7.1 What Effects a Locale Has</a></td><td> </td><td align="left" valign="top"> Actions affected by the choice of
locale.
</td></tr>
<tr><td align="left" valign="top"><a href="#Choosing-Locale">7.2 Choosing a Locale</a></td><td> </td><td align="left" valign="top"> How the user specifies a locale.
</td></tr>
<tr><td align="left" valign="top"><a href="#Locale-Categories">7.3 Categories of Activities that Locales Affect</a></td><td> </td><td align="left" valign="top"> Different purposes for which you can
select a locale.
</td></tr>
<tr><td align="left" valign="top"><a href="#Setting-the-Locale">7.4 How Programs Set the Locale</a></td><td> </td><td align="left" valign="top"> How a program specifies the locale
with library functions.
</td></tr>
<tr><td align="left" valign="top"><a href="#Standard-Locales">7.5 Standard Locales</a></td><td> </td><td align="left" valign="top"> Locale names available on all systems.
</td></tr>
<tr><td align="left" valign="top"><a href="#Locale-Information">7.6 Accessing Locale Information</a></td><td> </td><td align="left" valign="top"> How to access the information for the locale.
</td></tr>
<tr><td align="left" valign="top"><a href="#Formatting-Numbers">7.7 A dedicated function to format numbers</a></td><td> </td><td align="left" valign="top"></td></tr>
<tr><td align="left" valign="top"><a href="#Yes_002dor_002dNo-Questions">7.8 Yes-or-No Questions</a></td><td> </td><td align="left" valign="top"> Check a Response against the locale.
</td></tr>
</table>
<hr size="6">
<a name="Effects-of-Locale"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Locales" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Choosing-Locale" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Locales" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="What-Effects-a-Locale-Has"></a>
<h2 class="section">7.1 What Effects a Locale Has</h2>
<p>Each locale specifies conventions for several purposes, including the
following:
</p>
<ul>
<li>
What multibyte character sequences are valid, and how they are
interpreted (see section <a href="libc_6.html#Character-Set-Handling">Character Set Handling</a>).
</li><li>
Classification of which characters in the local character set are
considered alphabetic, and upper- and lower-case conversion conventions
(see section <a href="libc_4.html#Character-Handling">Character Handling</a>).
</li><li>
The collating sequence for the local language and character set
(see section <a href="libc_5.html#Collation-Functions">Collation Functions</a>).
</li><li>
Formatting of numbers and currency amounts (see section <a href="#General-Numeric">Generic Numeric Formatting Parameters</a>).
</li><li>
Formatting of dates and times (see section <a href="libc_21.html#Formatting-Calendar-Time">Formatting Calendar Time</a>).
</li><li>
What language to use for output, including error messages
(see section <a href="libc_8.html#Message-Translation">Message Translation</a>).
</li><li>
What language to use for user answers to yes-or-no questions
(see section <a href="#Yes_002dor_002dNo-Questions">Yes-or-No Questions</a>).
</li><li>
What language to use for more complex user input.
(The C library doesn’t yet help you implement this.)
</li></ul>
<p>Some aspects of adapting to the specified locale are handled
automatically by the library subroutines. For example, all your program
needs to do in order to use the collating sequence of the chosen locale
is to use <code>strcoll</code> or <code>strxfrm</code> to compare strings.
</p>
<p>Other aspects of locales are beyond the comprehension of the library.
For example, the library can’t automatically translate your program’s
output messages into other languages. The only way you can support
output in the user’s favorite language is to program this more or less
by hand. The C library provides functions to handle translations for
multiple languages easily.
</p>
<p>This chapter discusses the mechanism by which you can modify the current
locale. The effects of the current locale on specific library functions
are discussed in more detail in the descriptions of those functions.
</p>
<hr size="6">
<a name="Choosing-Locale"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Effects-of-Locale" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Locale-Categories" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Locales" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Choosing-a-Locale"></a>
<h2 class="section">7.2 Choosing a Locale</h2>
<p>The simplest way for the user to choose a locale is to set the
environment variable <code>LANG</code>. This specifies a single locale to use
for all purposes. For example, a user could specify a hypothetical
locale named ‘<samp>espana-castellano</samp>’ to use the standard conventions of
most of Spain.
</p>
<p>The set of locales supported depends on the operating system you are
using, and so do their names. We can’t make any promises about what
locales will exist, except for one standard locale called ‘<samp>C</samp>’ or
‘<samp>POSIX</samp>’. Later we will describe how to construct locales.
</p>
<a name="index-combining-locales"></a>
<p>A user also has the option of specifying different locales for different
purposes—in effect, choosing a mixture of multiple locales.
</p>
<p>For example, the user might specify the locale ‘<samp>espana-castellano</samp>’
for most purposes, but specify the locale ‘<samp>usa-english</samp>’ for
currency formatting. This might make sense if the user is a
Spanish-speaking American, working in Spanish, but representing monetary
amounts in US dollars.
</p>
<p>Note that both locales ‘<samp>espana-castellano</samp>’ and ‘<samp>usa-english</samp>’,
like all locales, would include conventions for all of the purposes to
which locales apply. However, the user can choose to use each locale
for a particular subset of those purposes.
</p>
<hr size="6">
<a name="Locale-Categories"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Choosing-Locale" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Setting-the-Locale" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Locales" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Categories-of-Activities-that-Locales-Affect"></a>
<h2 class="section">7.3 Categories of Activities that Locales Affect</h2>
<a name="index-categories-for-locales"></a>
<a name="index-locale-categories"></a>
<p>The purposes that locales serve are grouped into <em>categories</em>, so
that a user or a program can choose the locale for each category
independently. Here is a table of categories; each name is both an
environment variable that a user can set, and a macro name that you can
use as an argument to <code>setlocale</code>.
</p>
<dl compact="compact">
<dt> <code>LC_COLLATE</code>
<a name="index-LC_005fCOLLATE"></a>
</dt>
<dd><p>This category applies to collation of strings (functions <code>strcoll</code>
and <code>strxfrm</code>); see <a href="libc_5.html#Collation-Functions">Collation Functions</a>.
</p>
</dd>
<dt> <code>LC_CTYPE</code>
<a name="index-LC_005fCTYPE"></a>
</dt>
<dd><p>This category applies to classification and conversion of characters,
and to multibyte and wide characters;
see <a href="libc_4.html#Character-Handling">Character Handling</a>, and <a href="libc_6.html#Character-Set-Handling">Character Set Handling</a>.
</p>
</dd>
<dt> <code>LC_MONETARY</code>
<a name="index-LC_005fMONETARY"></a>
</dt>
<dd><p>This category applies to formatting monetary values; see <a href="#General-Numeric">Generic Numeric Formatting Parameters</a>.
</p>
</dd>
<dt> <code>LC_NUMERIC</code>
<a name="index-LC_005fNUMERIC"></a>
</dt>
<dd><p>This category applies to formatting numeric values that are not
monetary; see <a href="#General-Numeric">Generic Numeric Formatting Parameters</a>.
</p>
</dd>
<dt> <code>LC_TIME</code>
<a name="index-LC_005fTIME"></a>
</dt>
<dd><p>This category applies to formatting date and time values; see
<a href="libc_21.html#Formatting-Calendar-Time">Formatting Calendar Time</a>.
</p>
</dd>
<dt> <code>LC_MESSAGES</code>
<a name="index-LC_005fMESSAGES"></a>
</dt>
<dd><p>This category applies to selecting the language used in the user
interface for message translation (see section <a href="libc_8.html#The-Uniforum-approach">The Uniforum approach to Message Translation</a>;
see section <a href="libc_8.html#Message-catalogs-a-la-X_002fOpen">X/Open Message Catalog Handling</a>) and contains regular expressions
for affirmative and negative responses.
</p>
</dd>
<dt> <code>LC_ALL</code>
<a name="index-LC_005fALL"></a>
</dt>
<dd><p>This is not an environment variable; it is only a macro that you can use
with <code>setlocale</code> to set a single locale for all purposes. Setting
this environment variable overwrites all selections by the other
<code>LC_*</code> variables or <code>LANG</code>.
</p>
</dd>
<dt> <code>LANG</code>
<a name="index-LANG"></a>
</dt>
<dd><p>If this environment variable is defined, its value specifies the locale
to use for all purposes except as overridden by the variables above.
</p></dd>
</dl>
<a name="index-LANGUAGE"></a>
<p>When developing the message translation functions it was felt that the
functionality provided by the variables above is not sufficient. For
example, it should be possible to specify more than one locale name.
Take a Swedish user who better speaks German than English, and a program
whose messages are output in English by default. It should be possible
to specify that the first choice of language is Swedish, the second
German, and if this also fails to use English. This is
possible with the variable <code>LANGUAGE</code>. For further description of
this GNU extension see <a href="libc_8.html#Using-gettextized-software">User influence on <code>gettext</code></a>.
</p>
<hr size="6">
<a name="Setting-the-Locale"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Locale-Categories" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Standard-Locales" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Locales" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="How-Programs-Set-the-Locale"></a>
<h2 class="section">7.4 How Programs Set the Locale</h2>
<p>A C program inherits its locale environment variables when it starts up.
This happens automatically. However, these variables do not
automatically control the locale used by the library functions, because
ISO C says that all programs start by default in the standard ‘<samp>C</samp>’
locale. To use the locales specified by the environment, you must call
<code>setlocale</code>. Call it as follows:
</p>
<table><tr><td> </td><td><pre class="smallexample">setlocale (LC_ALL, "");
</pre></td></tr></table>
<p>to select a locale based on the user choice of the appropriate
environment variables.
</p>
<a name="index-changing-the-locale"></a>
<a name="index-locale_002c-changing"></a>
<p>You can also use <code>setlocale</code> to specify a particular locale, for
general use or for a specific category.
</p>
<a name="index-locale_002eh"></a>
<p>The symbols in this section are defined in the header file ‘<tt>locale.h</tt>’.
</p>
<dl>
<dt><a name="index-setlocale"></a><u>Function:</u> char * <b>setlocale</b><i> (int <var>category</var>, const char *<var>locale</var>)</i></dt>
<dd><p>The function <code>setlocale</code> sets the current locale for category
<var>category</var> to <var>locale</var>. A list of all the locales the system
provides can be created by running
</p>
<a name="index-locale"></a>
<table><tr><td> </td><td><pre class="smallexample"> locale -a
</pre></td></tr></table>
<p>If <var>category</var> is <code>LC_ALL</code>, this specifies the locale for all
purposes. The other possible values of <var>category</var> specify an
single purpose (see section <a href="#Locale-Categories">Categories of Activities that Locales Affect</a>).
</p>
<p>You can also use this function to find out the current locale by passing
a null pointer as the <var>locale</var> argument. In this case,
<code>setlocale</code> returns a string that is the name of the locale
currently selected for category <var>category</var>.
</p>
<p>The string returned by <code>setlocale</code> can be overwritten by subsequent
calls, so you should make a copy of the string (see section <a href="libc_5.html#Copying-and-Concatenation">Copying and Concatenation</a>) if you want to save it past any further calls to
<code>setlocale</code>. (The standard library is guaranteed never to call
<code>setlocale</code> itself.)
</p>
<p>You should not modify the string returned by <code>setlocale</code>. It might
be the same string that was passed as an argument in a previous call to
<code>setlocale</code>. One requirement is that the <var>category</var> must be
the same in the call the string was returned and the one when the string
is passed in as <var>locale</var> parameter.
</p>
<p>When you read the current locale for category <code>LC_ALL</code>, the value
encodes the entire combination of selected locales for all categories.
In this case, the value is not just a single locale name. In fact, we
don’t make any promises about what it looks like. But if you specify
the same “locale name” with <code>LC_ALL</code> in a subsequent call to
<code>setlocale</code>, it restores the same combination of locale selections.
</p>
<p>To be sure you can use the returned string encoding the currently selected
locale at a later time, you must make a copy of the string. It is not
guaranteed that the returned pointer remains valid over time.
</p>
<p>When the <var>locale</var> argument is not a null pointer, the string returned
by <code>setlocale</code> reflects the newly-modified locale.
</p>
<p>If you specify an empty string for <var>locale</var>, this means to read the
appropriate environment variable and use its value to select the locale
for <var>category</var>.
</p>
<p>If a nonempty string is given for <var>locale</var>, then the locale of that
name is used if possible.
</p>
<p>If you specify an invalid locale name, <code>setlocale</code> returns a null
pointer and leaves the current locale unchanged.
</p></dd></dl>
<p>Here is an example showing how you might use <code>setlocale</code> to
temporarily switch to a new locale.
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <stddef.h>
#include <locale.h>
#include <stdlib.h>
#include <string.h>
void
with_other_locale (char *new_locale,
void (*subroutine) (int),
int argument)
{
char *old_locale, *saved_locale;
/* <span class="roman">Get the name of the current locale.</span> */
old_locale = setlocale (LC_ALL, NULL);
/* <span class="roman">Copy the name so it won't be clobbered by <code>setlocale</code>.</span> */
saved_locale = strdup (old_locale);
if (saved_locale == NULL)
fatal ("Out of memory");
/* <span class="roman">Now change the locale and do some stuff with it.</span> */
setlocale (LC_ALL, new_locale);
(*subroutine) (argument);
/* <span class="roman">Restore the original locale.</span> */
setlocale (LC_ALL, saved_locale);
free (saved_locale);
}
</pre></td></tr></table>
<p><strong>Portability Note:</strong> Some ISO C systems may define additional
locale categories, and future versions of the library will do so. For
portability, assume that any symbol beginning with ‘<samp>LC_</samp>’ might be
defined in ‘<tt>locale.h</tt>’.
</p>
<hr size="6">
<a name="Standard-Locales"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Setting-the-Locale" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Locale-Information" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Locales" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Standard-Locales-1"></a>
<h2 class="section">7.5 Standard Locales</h2>
<p>The only locale names you can count on finding on all operating systems
are these three standard ones:
</p>
<dl compact="compact">
<dt> <code>"C"</code></dt>
<dd><p>This is the standard C locale. The attributes and behavior it provides
are specified in the ISO C standard. When your program starts up, it
initially uses this locale by default.
</p>
</dd>
<dt> <code>"POSIX"</code></dt>
<dd><p>This is the standard POSIX locale. Currently, it is an alias for the
standard C locale.
</p>
</dd>
<dt> <code>""</code></dt>
<dd><p>The empty name says to select a locale based on environment variables.
See section <a href="#Locale-Categories">Categories of Activities that Locales Affect</a>.
</p></dd>
</dl>
<p>Defining and installing named locales is normally a responsibility of
the system administrator at your site (or the person who installed the
GNU C library). It is also possible for the user to create private
locales. All this will be discussed later when describing the tool to
do so.
</p>
<p>If your program needs to use something other than the ‘<samp>C</samp>’ locale,
it will be more portable if you use whatever locale the user specifies
with the environment, rather than trying to specify some non-standard
locale explicitly by name. Remember, different machines might have
different sets of locales installed.
</p>
<hr size="6">
<a name="Locale-Information"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Standard-Locales" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-Lame-Way-to-Locale-Data" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Locales" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Accessing-Locale-Information"></a>
<h2 class="section">7.6 Accessing Locale Information</h2>
<p>There are several ways to access locale information. The simplest
way is to let the C library itself do the work. Several of the
functions in this library implicitly access the locale data, and use
what information is provided by the currently selected locale. This is
how the locale model is meant to work normally.
</p>
<p>As an example take the <code>strftime</code> function, which is meant to nicely
format date and time information (see section <a href="libc_21.html#Formatting-Calendar-Time">Formatting Calendar Time</a>).
Part of the standard information contained in the <code>LC_TIME</code>
category is the names of the months. Instead of requiring the
programmer to take care of providing the translations the
<code>strftime</code> function does this all by itself. <code>%A</code>
in the format string is replaced by the appropriate weekday
name of the locale currently selected by <code>LC_TIME</code>. This is an
easy example, and wherever possible functions do things automatically
in this way.
</p>
<p>But there are quite often situations when there is simply no function
to perform the task, or it is simply not possible to do the work
automatically. For these cases it is necessary to access the
information in the locale directly. To do this the C library provides
two functions: <code>localeconv</code> and <code>nl_langinfo</code>. The former is
part of ISO C and therefore portable, but has a brain-damaged
interface. The second is part of the Unix interface and is portable in
as far as the system follows the Unix standards.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#The-Lame-Way-to-Locale-Data">7.6.1 <code>localeconv</code>: It is portable but …</a></td><td> </td><td align="left" valign="top"> ISO C’s <code>localeconv</code>.
</td></tr>
<tr><td align="left" valign="top"><a href="#The-Elegant-and-Fast-Way">7.6.2 Pinpoint Access to Locale Data</a></td><td> </td><td align="left" valign="top"> X/Open’s <code>nl_langinfo</code>.
</td></tr>
</table>
<hr size="6">
<a name="The-Lame-Way-to-Locale-Data"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Locale-Information" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#General-Numeric" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Locale-Information" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="localeconv_003a-It-is-portable-but-_2026"></a>
<h3 class="subsection">7.6.1 <code>localeconv</code>: It is portable but …</h3>
<p>Together with the <code>setlocale</code> function the ISO C people
invented the <code>localeconv</code> function. It is a masterpiece of poor
design. It is expensive to use, not extendable, and not generally
usable as it provides access to only <code>LC_MONETARY</code> and
<code>LC_NUMERIC</code> related information. Nevertheless, if it is
applicable to a given situation it should be used since it is very
portable. The function <code>strfmon</code> formats monetary amounts
according to the selected locale using this information.
<a name="index-locale_002eh-1"></a>
<a name="index-monetary-value-formatting"></a>
<a name="index-numeric-value-formatting"></a>
</p>
<dl>
<dt><a name="index-localeconv"></a><u>Function:</u> struct lconv * <b>localeconv</b><i> (void)</i></dt>
<dd><p>The <code>localeconv</code> function returns a pointer to a structure whose
components contain information about how numeric and monetary values
should be formatted in the current locale.
</p>
<p>You should not modify the structure or its contents. The structure might
be overwritten by subsequent calls to <code>localeconv</code>, or by calls to
<code>setlocale</code>, but no other function in the library overwrites this
value.
</p></dd></dl>
<dl>
<dt><a name="index-struct-lconv"></a><u>Data Type:</u> <b>struct lconv</b></dt>
<dd><p><code>localeconv</code>’s return value is of this data type. Its elements are
described in the following subsections.
</p></dd></dl>
<p>If a member of the structure <code>struct lconv</code> has type <code>char</code>,
and the value is <code>CHAR_MAX</code>, it means that the current locale has
no value for that parameter.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#General-Numeric">7.6.1.1 Generic Numeric Formatting Parameters</a></td><td> </td><td align="left" valign="top"> Parameters for formatting numbers and
currency amounts.
</td></tr>
<tr><td align="left" valign="top"><a href="#Currency-Symbol">7.6.1.2 Printing the Currency Symbol</a></td><td> </td><td align="left" valign="top"> How to print the symbol that identifies an
amount of money (e.g. ‘<samp>$</samp>’).
</td></tr>
<tr><td align="left" valign="top"><a href="#Sign-of-Money-Amount">7.6.1.3 Printing the Sign of a Monetary Amount</a></td><td> </td><td align="left" valign="top"> How to print the (positive or negative) sign
for a monetary amount, if one exists.
</td></tr>
</table>
<hr size="6">
<a name="General-Numeric"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#The-Lame-Way-to-Locale-Data" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Currency-Symbol" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-Lame-Way-to-Locale-Data" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Generic-Numeric-Formatting-Parameters"></a>
<h4 class="subsubsection">7.6.1.1 Generic Numeric Formatting Parameters</h4>
<p>These are the standard members of <code>struct lconv</code>; there may be
others.
</p>
<dl compact="compact">
<dt> <code>char *decimal_point</code></dt>
<dt> <code>char *mon_decimal_point</code></dt>
<dd><p>These are the decimal-point separators used in formatting non-monetary
and monetary quantities, respectively. In the ‘<samp>C</samp>’ locale, the
value of <code>decimal_point</code> is <code>"."</code>, and the value of
<code>mon_decimal_point</code> is <code>""</code>.
<a name="index-decimal_002dpoint-separator"></a>
</p>
</dd>
<dt> <code>char *thousands_sep</code></dt>
<dt> <code>char *mon_thousands_sep</code></dt>
<dd><p>These are the separators used to delimit groups of digits to the left of
the decimal point in formatting non-monetary and monetary quantities,
respectively. In the ‘<samp>C</samp>’ locale, both members have a value of
<code>""</code> (the empty string).
</p>
</dd>
<dt> <code>char *grouping</code></dt>
<dt> <code>char *mon_grouping</code></dt>
<dd><p>These are strings that specify how to group the digits to the left of
the decimal point. <code>grouping</code> applies to non-monetary quantities
and <code>mon_grouping</code> applies to monetary quantities. Use either
<code>thousands_sep</code> or <code>mon_thousands_sep</code> to separate the digit
groups.
<a name="index-grouping-of-digits"></a>
</p>
<p>Each member of these strings is to be interpreted as an integer value of
type <code>char</code>. Successive numbers (from left to right) give the
sizes of successive groups (from right to left, starting at the decimal
point.) The last member is either <code>0</code>, in which case the previous
member is used over and over again for all the remaining groups, or
<code>CHAR_MAX</code>, in which case there is no more grouping—or, put
another way, any remaining digits form one large group without
separators.
</p>
<p>For example, if <code>grouping</code> is <code>"\04\03\02"</code>, the correct
grouping for the number <code>123456787654321</code> is ‘<samp>12</samp>’, ‘<samp>34</samp>’,
‘<samp>56</samp>’, ‘<samp>78</samp>’, ‘<samp>765</samp>’, ‘<samp>4321</samp>’. This uses a group of 4
digits at the end, preceded by a group of 3 digits, preceded by groups
of 2 digits (as many as needed). With a separator of ‘<samp>,</samp>’, the
number would be printed as ‘<samp>12,34,56,78,765,4321</samp>’.
</p>
<p>A value of <code>"\03"</code> indicates repeated groups of three digits, as
normally used in the U.S.
</p>
<p>In the standard ‘<samp>C</samp>’ locale, both <code>grouping</code> and
<code>mon_grouping</code> have a value of <code>""</code>. This value specifies no
grouping at all.
</p>
</dd>
<dt> <code>char int_frac_digits</code></dt>
<dt> <code>char frac_digits</code></dt>
<dd><p>These are small integers indicating how many fractional digits (to the
right of the decimal point) should be displayed in a monetary value in
international and local formats, respectively. (Most often, both
members have the same value.)
</p>
<p>In the standard ‘<samp>C</samp>’ locale, both of these members have the value
<code>CHAR_MAX</code>, meaning “unspecified”. The ISO standard doesn’t say
what to do when you find this value; we recommend printing no
fractional digits. (This locale also specifies the empty string for
<code>mon_decimal_point</code>, so printing any fractional digits would be
confusing!)
</p></dd>
</dl>
<hr size="6">
<a name="Currency-Symbol"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#General-Numeric" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Sign-of-Money-Amount" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-Lame-Way-to-Locale-Data" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Printing-the-Currency-Symbol"></a>
<h4 class="subsubsection">7.6.1.2 Printing the Currency Symbol</h4>
<a name="index-currency-symbols"></a>
<p>These members of the <code>struct lconv</code> structure specify how to print
the symbol to identify a monetary value—the international analog of
‘<samp>$</samp>’ for US dollars.
</p>
<p>Each country has two standard currency symbols. The <em>local currency
symbol</em> is used commonly within the country, while the
<em>international currency symbol</em> is used internationally to refer to
that country’s currency when it is necessary to indicate the country
unambiguously.
</p>
<p>For example, many countries use the dollar as their monetary unit, and
when dealing with international currencies it’s important to specify
that one is dealing with (say) Canadian dollars instead of U.S. dollars
or Australian dollars. But when the context is known to be Canada,
there is no need to make this explicit—dollar amounts are implicitly
assumed to be in Canadian dollars.
</p>
<dl compact="compact">
<dt> <code>char *currency_symbol</code></dt>
<dd><p>The local currency symbol for the selected locale.
</p>
<p>In the standard ‘<samp>C</samp>’ locale, this member has a value of <code>""</code>
(the empty string), meaning “unspecified”. The ISO standard doesn’t
say what to do when you find this value; we recommend you simply print
the empty string as you would print any other string pointed to by this
variable.
</p>
</dd>
<dt> <code>char *int_curr_symbol</code></dt>
<dd><p>The international currency symbol for the selected locale.
</p>
<p>The value of <code>int_curr_symbol</code> should normally consist of a
three-letter abbreviation determined by the international standard
<cite>ISO 4217 Codes for the Representation of Currency and Funds</cite>,
followed by a one-character separator (often a space).
</p>
<p>In the standard ‘<samp>C</samp>’ locale, this member has a value of <code>""</code>
(the empty string), meaning “unspecified”. We recommend you simply print
the empty string as you would print any other string pointed to by this
variable.
</p>
</dd>
<dt> <code>char p_cs_precedes</code></dt>
<dt> <code>char n_cs_precedes</code></dt>
<dt> <code>char int_p_cs_precedes</code></dt>
<dt> <code>char int_n_cs_precedes</code></dt>
<dd><p>These members are <code>1</code> if the <code>currency_symbol</code> or
<code>int_curr_symbol</code> strings should precede the value of a monetary
amount, or <code>0</code> if the strings should follow the value. The
<code>p_cs_precedes</code> and <code>int_p_cs_precedes</code> members apply to
positive amounts (or zero), and the <code>n_cs_precedes</code> and
<code>int_n_cs_precedes</code> members apply to negative amounts.
</p>
<p>In the standard ‘<samp>C</samp>’ locale, all of these members have a value of
<code>CHAR_MAX</code>, meaning “unspecified”. The ISO standard doesn’t say
what to do when you find this value. We recommend printing the
currency symbol before the amount, which is right for most countries.
In other words, treat all nonzero values alike in these members.
</p>
<p>The members with the <code>int_</code> prefix apply to the
<code>int_curr_symbol</code> while the other two apply to
<code>currency_symbol</code>.
</p>
</dd>
<dt> <code>char p_sep_by_space</code></dt>
<dt> <code>char n_sep_by_space</code></dt>
<dt> <code>char int_p_sep_by_space</code></dt>
<dt> <code>char int_n_sep_by_space</code></dt>
<dd><p>These members are <code>1</code> if a space should appear between the
<code>currency_symbol</code> or <code>int_curr_symbol</code> strings and the
amount, or <code>0</code> if no space should appear. The
<code>p_sep_by_space</code> and <code>int_p_sep_by_space</code> members apply to
positive amounts (or zero), and the <code>n_sep_by_space</code> and
<code>int_n_sep_by_space</code> members apply to negative amounts.
</p>
<p>In the standard ‘<samp>C</samp>’ locale, all of these members have a value of
<code>CHAR_MAX</code>, meaning “unspecified”. The ISO standard doesn’t say
what you should do when you find this value; we suggest you treat it as
1 (print a space). In other words, treat all nonzero values alike in
these members.
</p>
<p>The members with the <code>int_</code> prefix apply to the
<code>int_curr_symbol</code> while the other two apply to
<code>currency_symbol</code>. There is one specialty with the
<code>int_curr_symbol</code>, though. Since all legal values contain a space
at the end the string one either printf this space (if the currency
symbol must appear in front and must be separated) or one has to avoid
printing this character at all (especially when at the end of the
string).
</p></dd>
</dl>
<hr size="6">
<a name="Sign-of-Money-Amount"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Currency-Symbol" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#The-Elegant-and-Fast-Way" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#The-Lame-Way-to-Locale-Data" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Printing-the-Sign-of-a-Monetary-Amount"></a>
<h4 class="subsubsection">7.6.1.3 Printing the Sign of a Monetary Amount</h4>
<p>These members of the <code>struct lconv</code> structure specify how to print
the sign (if any) of a monetary value.
</p>
<dl compact="compact">
<dt> <code>char *positive_sign</code></dt>
<dt> <code>char *negative_sign</code></dt>
<dd><p>These are strings used to indicate positive (or zero) and negative
monetary quantities, respectively.
</p>
<p>In the standard ‘<samp>C</samp>’ locale, both of these members have a value of
<code>""</code> (the empty string), meaning “unspecified”.
</p>
<p>The ISO standard doesn’t say what to do when you find this value; we
recommend printing <code>positive_sign</code> as you find it, even if it is
empty. For a negative value, print <code>negative_sign</code> as you find it
unless both it and <code>positive_sign</code> are empty, in which case print
‘<samp>-</samp>’ instead. (Failing to indicate the sign at all seems rather
unreasonable.)
</p>
</dd>
<dt> <code>char p_sign_posn</code></dt>
<dt> <code>char n_sign_posn</code></dt>
<dt> <code>char int_p_sign_posn</code></dt>
<dt> <code>char int_n_sign_posn</code></dt>
<dd><p>These members are small integers that indicate how to
position the sign for nonnegative and negative monetary quantities,
respectively. (The string used by the sign is what was specified with
<code>positive_sign</code> or <code>negative_sign</code>.) The possible values are
as follows:
</p>
<dl compact="compact">
<dt> <code>0</code></dt>
<dd><p>The currency symbol and quantity should be surrounded by parentheses.
</p>
</dd>
<dt> <code>1</code></dt>
<dd><p>Print the sign string before the quantity and currency symbol.
</p>
</dd>
<dt> <code>2</code></dt>
<dd><p>Print the sign string after the quantity and currency symbol.
</p>
</dd>
<dt> <code>3</code></dt>
<dd><p>Print the sign string right before the currency symbol.
</p>
</dd>
<dt> <code>4</code></dt>
<dd><p>Print the sign string right after the currency symbol.
</p>
</dd>
<dt> <code>CHAR_MAX</code></dt>
<dd><p>“Unspecified”. Both members have this value in the standard
‘<samp>C</samp>’ locale.
</p></dd>
</dl>
<p>The ISO standard doesn’t say what you should do when the value is
<code>CHAR_MAX</code>. We recommend you print the sign after the currency
symbol.
</p>
<p>The members with the <code>int_</code> prefix apply to the
<code>int_curr_symbol</code> while the other two apply to
<code>currency_symbol</code>.
</p></dd>
</dl>
<hr size="6">
<a name="The-Elegant-and-Fast-Way"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Sign-of-Money-Amount" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Formatting-Numbers" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Locale-Information" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Pinpoint-Access-to-Locale-Data"></a>
<h3 class="subsection">7.6.2 Pinpoint Access to Locale Data</h3>
<p>When writing the X/Open Portability Guide the authors realized that the
<code>localeconv</code> function is not enough to provide reasonable access to
locale information. The information which was meant to be available
in the locale (as later specified in the POSIX.1 standard) requires more
ways to access it. Therefore the <code>nl_langinfo</code> function
was introduced.
</p>
<dl>
<dt><a name="index-nl_005flanginfo"></a><u>Function:</u> char * <b>nl_langinfo</b><i> (nl_item <var>item</var>)</i></dt>
<dd><p>The <code>nl_langinfo</code> function can be used to access individual
elements of the locale categories. Unlike the <code>localeconv</code>
function, which returns all the information, <code>nl_langinfo</code>
lets the caller select what information it requires. This is very
fast and it is not a problem to call this function multiple times.
</p>
<p>A second advantage is that in addition to the numeric and monetary
formatting information, information from the
<code>LC_TIME</code> and <code>LC_MESSAGES</code> categories is available.
</p>
<a name="index-langinfo_002eh"></a>
<p>The type <code>nl_type</code> is defined in ‘<tt>nl_types.h</tt>’. The argument
<var>item</var> is a numeric value defined in the header ‘<tt>langinfo.h</tt>’.
The X/Open standard defines the following values:
</p>
<dl compact="compact">
<dt> <code>CODESET</code>
<a name="index-CODESET"></a>
</dt>
<dd><p><code>nl_langinfo</code> returns a string with the name of the coded character
set used in the selected locale.
</p>
</dd>
<dt> <code>ABDAY_1</code>
<a name="index-ABDAY_005f1"></a>
</dt>
<dt> <code>ABDAY_2</code>
<a name="index-ABDAY_005f2"></a>
</dt>
<dt> <code>ABDAY_3</code>
<a name="index-ABDAY_005f3"></a>
</dt>
<dt> <code>ABDAY_4</code>
<a name="index-ABDAY_005f4"></a>
</dt>
<dt> <code>ABDAY_5</code>
<a name="index-ABDAY_005f5"></a>
</dt>
<dt> <code>ABDAY_6</code>
<a name="index-ABDAY_005f6"></a>
</dt>
<dt> <code>ABDAY_7</code>
<a name="index-ABDAY_005f7"></a>
</dt>
<dd><p><code>nl_langinfo</code> returns the abbreviated weekday name. <code>ABDAY_1</code>
corresponds to Sunday.
</p></dd>
<dt> <code>DAY_1</code>
<a name="index-DAY_005f1"></a>
</dt>
<dt> <code>DAY_2</code>
<a name="index-DAY_005f2"></a>
</dt>
<dt> <code>DAY_3</code>
<a name="index-DAY_005f3"></a>
</dt>
<dt> <code>DAY_4</code>
<a name="index-DAY_005f4"></a>
</dt>
<dt> <code>DAY_5</code>
<a name="index-DAY_005f5"></a>
</dt>
<dt> <code>DAY_6</code>
<a name="index-DAY_005f6"></a>
</dt>
<dt> <code>DAY_7</code>
<a name="index-DAY_005f7"></a>
</dt>
<dd><p>Similar to <code>ABDAY_1</code> etc., but here the return value is the
unabbreviated weekday name.
</p></dd>
<dt> <code>ABMON_1</code>
<a name="index-ABMON_005f1"></a>
</dt>
<dt> <code>ABMON_2</code>
<a name="index-ABMON_005f2"></a>
</dt>
<dt> <code>ABMON_3</code>
<a name="index-ABMON_005f3"></a>
</dt>
<dt> <code>ABMON_4</code>
<a name="index-ABMON_005f4"></a>
</dt>
<dt> <code>ABMON_5</code>
<a name="index-ABMON_005f5"></a>
</dt>
<dt> <code>ABMON_6</code>
<a name="index-ABMON_005f6"></a>
</dt>
<dt> <code>ABMON_7</code>
<a name="index-ABMON_005f7"></a>
</dt>
<dt> <code>ABMON_8</code>
<a name="index-ABMON_005f8"></a>
</dt>
<dt> <code>ABMON_9</code>
<a name="index-ABMON_005f9"></a>
</dt>
<dt> <code>ABMON_10</code>
<a name="index-ABMON_005f10"></a>
</dt>
<dt> <code>ABMON_11</code>
<a name="index-ABMON_005f11"></a>
</dt>
<dt> <code>ABMON_12</code>
<a name="index-ABMON_005f12"></a>
</dt>
<dd><p>The return value is abbreviated name of the month. <code>ABMON_1</code>
corresponds to January.
</p></dd>
<dt> <code>MON_1</code>
<a name="index-MON_005f1"></a>
</dt>
<dt> <code>MON_2</code>
<a name="index-MON_005f2"></a>
</dt>
<dt> <code>MON_3</code>
<a name="index-MON_005f3"></a>
</dt>
<dt> <code>MON_4</code>
<a name="index-MON_005f4"></a>
</dt>
<dt> <code>MON_5</code>
<a name="index-MON_005f5"></a>
</dt>
<dt> <code>MON_6</code>
<a name="index-MON_005f6"></a>
</dt>
<dt> <code>MON_7</code>
<a name="index-MON_005f7"></a>
</dt>
<dt> <code>MON_8</code>
<a name="index-MON_005f8"></a>
</dt>
<dt> <code>MON_9</code>
<a name="index-MON_005f9"></a>
</dt>
<dt> <code>MON_10</code>
<a name="index-MON_005f10"></a>
</dt>
<dt> <code>MON_11</code>
<a name="index-MON_005f11"></a>
</dt>
<dt> <code>MON_12</code>
<a name="index-MON_005f12"></a>
</dt>
<dd><p>Similar to <code>ABMON_1</code> etc., but here the month names are not abbreviated.
Here the first value <code>MON_1</code> also corresponds to January.
</p></dd>
<dt> <code>AM_STR</code>
<a name="index-AM_005fSTR"></a>
</dt>
<dt> <code>PM_STR</code>
<a name="index-PM_005fSTR"></a>
</dt>
<dd><p>The return values are strings which can be used in the representation of time
as an hour from 1 to 12 plus an am/pm specifier.
</p>
<p>Note that in locales which do not use this time representation
these strings might be empty, in which case the am/pm format
cannot be used at all.
</p></dd>
<dt> <code>D_T_FMT</code>
<a name="index-D_005fT_005fFMT"></a>
</dt>
<dd><p>The return value can be used as a format string for <code>strftime</code> to
represent time and date in a locale-specific way.
</p></dd>
<dt> <code>D_FMT</code>
<a name="index-D_005fFMT"></a>
</dt>
<dd><p>The return value can be used as a format string for <code>strftime</code> to
represent a date in a locale-specific way.
</p></dd>
<dt> <code>T_FMT</code>
<a name="index-T_005fFMT"></a>
</dt>
<dd><p>The return value can be used as a format string for <code>strftime</code> to
represent time in a locale-specific way.
</p></dd>
<dt> <code>T_FMT_AMPM</code>
<a name="index-T_005fFMT_005fAMPM"></a>
</dt>
<dd><p>The return value can be used as a format string for <code>strftime</code> to
represent time in the am/pm format.
</p>
<p>Note that if the am/pm format does not make any sense for the
selected locale, the return value might be the same as the one for
<code>T_FMT</code>.
</p></dd>
<dt> <code>ERA</code>
<a name="index-ERA"></a>
</dt>
<dd><p>The return value represents the era used in the current locale.
</p>
<p>Most locales do not define this value. An example of a locale which
does define this value is the Japanese one. In Japan, the traditional
representation of dates includes the name of the era corresponding to
the then-emperor’s reign.
</p>
<p>Normally it should not be necessary to use this value directly.
Specifying the <code>E</code> modifier in their format strings causes the
<code>strftime</code> functions to use this information. The format of the
returned string is not specified, and therefore you should not assume
knowledge of it on different systems.
</p></dd>
<dt> <code>ERA_YEAR</code>
<a name="index-ERA_005fYEAR"></a>
</dt>
<dd><p>The return value gives the year in the relevant era of the locale.
As for <code>ERA</code> it should not be necessary to use this value directly.
</p></dd>
<dt> <code>ERA_D_T_FMT</code>
<a name="index-ERA_005fD_005fT_005fFMT"></a>
</dt>
<dd><p>This return value can be used as a format string for <code>strftime</code> to
represent dates and times in a locale-specific era-based way.
</p></dd>
<dt> <code>ERA_D_FMT</code>
<a name="index-ERA_005fD_005fFMT"></a>
</dt>
<dd><p>This return value can be used as a format string for <code>strftime</code> to
represent a date in a locale-specific era-based way.
</p></dd>
<dt> <code>ERA_T_FMT</code>
<a name="index-ERA_005fT_005fFMT"></a>
</dt>
<dd><p>This return value can be used as a format string for <code>strftime</code> to
represent time in a locale-specific era-based way.
</p></dd>
<dt> <code>ALT_DIGITS</code>
<a name="index-ALT_005fDIGITS"></a>
</dt>
<dd><p>The return value is a representation of up to <em>100</em> values used to
represent the values <em>0</em> to <em>99</em>. As for <code>ERA</code> this
value is not intended to be used directly, but instead indirectly
through the <code>strftime</code> function. When the modifier <code>O</code> is
used in a format which would otherwise use numerals to represent hours,
minutes, seconds, weekdays, months, or weeks, the appropriate value for
the locale is used instead.
</p></dd>
<dt> <code>INT_CURR_SYMBOL</code>
<a name="index-INT_005fCURR_005fSYMBOL"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>int_curr_symbol</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>CURRENCY_SYMBOL</code>
<a name="index-CURRENCY_005fSYMBOL"></a>
</dt>
<dt> <code>CRNCYSTR</code>
<a name="index-CRNCYSTR"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>currency_symbol</code> element of the <code>struct lconv</code>.
</p>
<p><code>CRNCYSTR</code> is a deprecated alias still required by Unix98.
</p></dd>
<dt> <code>MON_DECIMAL_POINT</code>
<a name="index-MON_005fDECIMAL_005fPOINT"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>mon_decimal_point</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>MON_THOUSANDS_SEP</code>
<a name="index-MON_005fTHOUSANDS_005fSEP"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>mon_thousands_sep</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>MON_GROUPING</code>
<a name="index-MON_005fGROUPING"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>mon_grouping</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>POSITIVE_SIGN</code>
<a name="index-POSITIVE_005fSIGN"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>positive_sign</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>NEGATIVE_SIGN</code>
<a name="index-NEGATIVE_005fSIGN"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>negative_sign</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>INT_FRAC_DIGITS</code>
<a name="index-INT_005fFRAC_005fDIGITS"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>int_frac_digits</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>FRAC_DIGITS</code>
<a name="index-FRAC_005fDIGITS"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>frac_digits</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>P_CS_PRECEDES</code>
<a name="index-P_005fCS_005fPRECEDES"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>p_cs_precedes</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>P_SEP_BY_SPACE</code>
<a name="index-P_005fSEP_005fBY_005fSPACE"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>p_sep_by_space</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>N_CS_PRECEDES</code>
<a name="index-N_005fCS_005fPRECEDES"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>n_cs_precedes</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>N_SEP_BY_SPACE</code>
<a name="index-N_005fSEP_005fBY_005fSPACE"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>n_sep_by_space</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>P_SIGN_POSN</code>
<a name="index-P_005fSIGN_005fPOSN"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>p_sign_posn</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>N_SIGN_POSN</code>
<a name="index-N_005fSIGN_005fPOSN"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>n_sign_posn</code> element of the <code>struct lconv</code>.
</p>
</dd>
<dt> <code>INT_P_CS_PRECEDES</code>
<a name="index-INT_005fP_005fCS_005fPRECEDES"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>int_p_cs_precedes</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>INT_P_SEP_BY_SPACE</code>
<a name="index-INT_005fP_005fSEP_005fBY_005fSPACE"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>int_p_sep_by_space</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>INT_N_CS_PRECEDES</code>
<a name="index-INT_005fN_005fCS_005fPRECEDES"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>int_n_cs_precedes</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>INT_N_SEP_BY_SPACE</code>
<a name="index-INT_005fN_005fSEP_005fBY_005fSPACE"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>int_n_sep_by_space</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>INT_P_SIGN_POSN</code>
<a name="index-INT_005fP_005fSIGN_005fPOSN"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>int_p_sign_posn</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>INT_N_SIGN_POSN</code>
<a name="index-INT_005fN_005fSIGN_005fPOSN"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>int_n_sign_posn</code> element of the <code>struct lconv</code>.
</p>
</dd>
<dt> <code>DECIMAL_POINT</code>
<a name="index-DECIMAL_005fPOINT"></a>
</dt>
<dt> <code>RADIXCHAR</code>
<a name="index-RADIXCHAR"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>decimal_point</code> element of the <code>struct lconv</code>.
</p>
<p>The name <code>RADIXCHAR</code> is a deprecated alias still used in Unix98.
</p></dd>
<dt> <code>THOUSANDS_SEP</code>
<a name="index-THOUSANDS_005fSEP"></a>
</dt>
<dt> <code>THOUSEP</code>
<a name="index-THOUSEP"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>thousands_sep</code> element of the <code>struct lconv</code>.
</p>
<p>The name <code>THOUSEP</code> is a deprecated alias still used in Unix98.
</p></dd>
<dt> <code>GROUPING</code>
<a name="index-GROUPING"></a>
</dt>
<dd><p>The same as the value returned by <code>localeconv</code> in the
<code>grouping</code> element of the <code>struct lconv</code>.
</p></dd>
<dt> <code>YESEXPR</code>
<a name="index-YESEXPR"></a>
</dt>
<dd><p>The return value is a regular expression which can be used with the
<code>regex</code> function to recognize a positive response to a yes/no
question. The GNU C library provides the <code>rpmatch</code> function for
easier handling in applications.
</p></dd>
<dt> <code>NOEXPR</code>
<a name="index-NOEXPR"></a>
</dt>
<dd><p>The return value is a regular expression which can be used with the
<code>regex</code> function to recognize a negative response to a yes/no
question.
</p></dd>
<dt> <code>YESSTR</code>
<a name="index-YESSTR"></a>
</dt>
<dd><p>The return value is a locale-specific translation of the positive response
to a yes/no question.
</p>
<p>Using this value is deprecated since it is a very special case of
message translation, and is better handled by the message
translation functions (see section <a href="libc_8.html#Message-Translation">Message Translation</a>).
</p>
<p>The use of this symbol is deprecated. Instead message translation
should be used.
</p></dd>
<dt> <code>NOSTR</code>
<a name="index-NOSTR"></a>
</dt>
<dd><p>The return value is a locale-specific translation of the negative response
to a yes/no question. What is said for <code>YESSTR</code> is also true here.
</p>
<p>The use of this symbol is deprecated. Instead message translation
should be used.
</p></dd>
</dl>
<p>The file ‘<tt>langinfo.h</tt>’ defines a lot more symbols but none of them
is official. Using them is not portable, and the format of the
return values might change. Therefore we recommended you not use
them.
</p>
<p>Note that the return value for any valid argument can be used for
in all situations (with the possible exception of the am/pm time formatting
codes). If the user has not selected any locale for the
appropriate category, <code>nl_langinfo</code> returns the information from the
<code>"C"</code> locale. It is therefore possible to use this function as
shown in the example below.
</p>
<p>If the argument <var>item</var> is not valid, a pointer to an empty string is
returned.
</p></dd></dl>
<p>An example of <code>nl_langinfo</code> usage is a function which has to
print a given date and time in a locale-specific way. At first one
might think that, since <code>strftime</code> internally uses the locale
information, writing something like the following is enough:
</p>
<table><tr><td> </td><td><pre class="smallexample">size_t
i18n_time_n_data (char *s, size_t len, const struct tm *tp)
{
return strftime (s, len, "%X %D", tp);
}
</pre></td></tr></table>
<p>The format contains no weekday or month names and therefore is
internationally usable. Wrong! The output produced is something like
<code>"hh:mm:ss MM/DD/YY"</code>. This format is only recognizable in the
USA. Other countries use different formats. Therefore the function
should be rewritten like this:
</p>
<table><tr><td> </td><td><pre class="smallexample">size_t
i18n_time_n_data (char *s, size_t len, const struct tm *tp)
{
return strftime (s, len, nl_langinfo (D_T_FMT), tp);
}
</pre></td></tr></table>
<p>Now it uses the date and time format of the locale
selected when the program runs. If the user selects the locale
correctly there should never be a misunderstanding over the time and
date format.
</p>
<hr size="6">
<a name="Formatting-Numbers"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#The-Elegant-and-Fast-Way" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Yes_002dor_002dNo-Questions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Locales" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="A-dedicated-function-to-format-numbers"></a>
<h2 class="section">7.7 A dedicated function to format numbers</h2>
<p>We have seen that the structure returned by <code>localeconv</code> as well as
the values given to <code>nl_langinfo</code> allow you to retrieve the various
pieces of locale-specific information to format numbers and monetary
amounts. We have also seen that the underlying rules are quite complex.
</p>
<p>Therefore the X/Open standards introduce a function which uses such
locale information, making it easier for the user to format
numbers according to these rules.
</p>
<dl>
<dt><a name="index-strfmon"></a><u>Function:</u> ssize_t <b>strfmon</b><i> (char *<var>s</var>, size_t <var>maxsize</var>, const char *<var>format</var>, …)</i></dt>
<dd><p>The <code>strfmon</code> function is similar to the <code>strftime</code> function
in that it takes a buffer, its size, a format string,
and values to write into the buffer as text in a form specified
by the format string. Like <code>strftime</code>, the function
also returns the number of bytes written into the buffer.
</p>
<p>There are two differences: <code>strfmon</code> can take more than one
argument, and, of course, the format specification is different. Like
<code>strftime</code>, the format string consists of normal text, which is
output as is, and format specifiers, which are indicated by a ‘<samp>%</samp>’.
Immediately after the ‘<samp>%</samp>’, you can optionally specify various flags
and formatting information before the main formatting character, in a
similar way to <code>printf</code>:
</p>
<ul>
<li>
Immediately following the ‘<samp>%</samp>’ there can be one or more of the
following flags:
<dl compact="compact">
<dt> ‘<samp>=<var>f</var></samp>’</dt>
<dd><p>The single byte character <var>f</var> is used for this field as the numeric
fill character. By default this character is a space character.
Filling with this character is only performed if a left precision
is specified. It is not just to fill to the given field width.
</p></dd>
<dt> ‘<samp>^</samp>’</dt>
<dd><p>The number is printed without grouping the digits according to the rules
of the current locale. By default grouping is enabled.
</p></dd>
<dt> ‘<samp>+</samp>’, ‘<samp>(</samp>’</dt>
<dd><p>At most one of these flags can be used. They select which format to
represent the sign of a currency amount. By default, and if
‘<samp>+</samp>’ is given, the locale equivalent of <em>+</em>/<em>-</em> is used. If
‘<samp>(</samp>’ is given, negative amounts are enclosed in parentheses. The
exact format is determined by the values of the <code>LC_MONETARY</code>
category of the locale selected at program runtime.
</p></dd>
<dt> ‘<samp>!</samp>’</dt>
<dd><p>The output will not contain the currency symbol.
</p></dd>
<dt> ‘<samp>-</samp>’</dt>
<dd><p>The output will be formatted left-justified instead of right-justified if
it does not fill the entire field width.
</p></dd>
</dl>
</li></ul>
<p>The next part of a specification is an optional field width. If no
width is specified <em>0</em> is taken. During output, the function first
determines how much space is required. If it requires at least as many
characters as given by the field width, it is output using as much space
as necessary. Otherwise, it is extended to use the full width by
filling with the space character. The presence or absence of the
‘<samp>-</samp>’ flag determines the side at which such padding occurs. If
present, the spaces are added at the right making the output
left-justified, and vice versa.
</p>
<p>So far the format looks familiar, being similar to the <code>printf</code> and
<code>strftime</code> formats. However, the next two optional fields
introduce something new. The first one is a ‘<samp>#</samp>’ character followed
by a decimal digit string. The value of the digit string specifies the
number of <em>digit</em> positions to the left of the decimal point (or
equivalent). This does <em>not</em> include the grouping character when
the ‘<samp>^</samp>’ flag is not given. If the space needed to print the number
does not fill the whole width, the field is padded at the left side with
the fill character, which can be selected using the ‘<samp>=</samp>’ flag and by
default is a space. For example, if the field width is selected as 6
and the number is <em>123</em>, the fill character is ‘<samp>*</samp>’ the result
will be ‘<samp>***123</samp>’.
</p>
<p>The second optional field starts with a ‘<samp>.</samp>’ (period) and consists
of another decimal digit string. Its value describes the number of
characters printed after the decimal point. The default is selected
from the current locale (<code>frac_digits</code>, <code>int_frac_digits</code>, see
see section <a href="#General-Numeric">Generic Numeric Formatting Parameters</a>). If the exact representation needs more digits
than given by the field width, the displayed value is rounded. If the
number of fractional digits is selected to be zero, no decimal point is
printed.
</p>
<p>As a GNU extension, the <code>strfmon</code> implementation in the GNU libc
allows an optional ‘<samp>L</samp>’ next as a format modifier. If this modifier
is given, the argument is expected to be a <code>long double</code> instead of
a <code>double</code> value.
</p>
<p>Finally, the last component is a format specifier. There are three
specifiers defined:
</p>
<dl compact="compact">
<dt> ‘<samp>i</samp>’</dt>
<dd><p>Use the locale’s rules for formatting an international currency value.
</p></dd>
<dt> ‘<samp>n</samp>’</dt>
<dd><p>Use the locale’s rules for formatting a national currency value.
</p></dd>
<dt> ‘<samp>%</samp>’</dt>
<dd><p>Place a ‘<samp>%</samp>’ in the output. There must be no flag, width
specifier or modifier given, only ‘<samp>%%</samp>’ is allowed.
</p></dd>
</dl>
<p>As for <code>printf</code>, the function reads the format string
from left to right and uses the values passed to the function following
the format string. The values are expected to be either of type
<code>double</code> or <code>long double</code>, depending on the presence of the
modifier ‘<samp>L</samp>’. The result is stored in the buffer pointed to by
<var>s</var>. At most <var>maxsize</var> characters are stored.
</p>
<p>The return value of the function is the number of characters stored in
<var>s</var>, including the terminating <code>NULL</code> byte. If the number of
characters stored would exceed <var>maxsize</var>, the function returns
<em>-1</em> and the content of the buffer <var>s</var> is unspecified. In this
case <code>errno</code> is set to <code>E2BIG</code>.
</p></dd></dl>
<p>A few examples should make clear how the function works. It is
assumed that all the following pieces of code are executed in a program
which uses the USA locale (<code>en_US</code>). The simplest
form of the format is this:
</p>
<table><tr><td> </td><td><pre class="smallexample">strfmon (buf, 100, "@%n@%n@%n@", 123.45, -567.89, 12345.678);
</pre></td></tr></table>
<p>The output produced is
</p><table><tr><td> </td><td><pre class="smallexample">"@$123.45@-$567.89@$12,345.68@"
</pre></td></tr></table>
<p>We can notice several things here. First, the widths of the output
numbers are different. We have not specified a width in the format
string, and so this is no wonder. Second, the third number is printed
using thousands separators. The thousands separator for the
<code>en_US</code> locale is a comma. The number is also rounded.
<em>.678</em> is rounded to <em>.68</em> since the format does not specify a
precision and the default value in the locale is <em>2</em>. Finally,
note that the national currency symbol is printed since ‘<samp>%n</samp>’ was
used, not ‘<samp>i</samp>’. The next example shows how we can align the output.
</p>
<table><tr><td> </td><td><pre class="smallexample">strfmon (buf, 100, "@%=*11n@%=*11n@%=*11n@", 123.45, -567.89, 12345.678);
</pre></td></tr></table>
<p>The output this time is:
</p>
<table><tr><td> </td><td><pre class="smallexample">"@ $123.45@ -$567.89@ $12,345.68@"
</pre></td></tr></table>
<p>Two things stand out. Firstly, all fields have the same width (eleven
characters) since this is the width given in the format and since no
number required more characters to be printed. The second important
point is that the fill character is not used. This is correct since the
white space was not used to achieve a precision given by a ‘<samp>#</samp>’
modifier, but instead to fill to the given width. The difference
becomes obvious if we now add a width specification.
</p>
<table><tr><td> </td><td><pre class="smallexample">strfmon (buf, 100, "@%=*11#5n@%=*11#5n@%=*11#5n@",
123.45, -567.89, 12345.678);
</pre></td></tr></table>
<p>The output is
</p>
<table><tr><td> </td><td><pre class="smallexample">"@ $***123.45@-$***567.89@ $12,456.68@"
</pre></td></tr></table>
<p>Here we can see that all the currency symbols are now aligned, and that
the space between the currency sign and the number is filled with the
selected fill character. Note that although the width is selected to be
<em>5</em> and <em>123.45</em> has three digits left of the decimal point,
the space is filled with three asterisks. This is correct since, as
explained above, the width does not include the positions used to store
thousands separators. One last example should explain the remaining
functionality.
</p>
<table><tr><td> </td><td><pre class="smallexample">strfmon (buf, 100, "@%=0(16#5.3i@%=0(16#5.3i@%=0(16#5.3i@",
123.45, -567.89, 12345.678);
</pre></td></tr></table>
<p>This rather complex format string produces the following output:
</p>
<table><tr><td> </td><td><pre class="smallexample">"@ USD 000123,450 @(USD 000567.890)@ USD 12,345.678 @"
</pre></td></tr></table>
<p>The most noticeable change is the alternative way of representing
negative numbers. In financial circles this is often done using
parentheses, and this is what the ‘<samp>(</samp>’ flag selected. The fill
character is now ‘<samp>0</samp>’. Note that this ‘<samp>0</samp>’ character is not
regarded as a numeric zero, and therefore the first and second numbers
are not printed using a thousands separator. Since we used the format
specifier ‘<samp>i</samp>’ instead of ‘<samp>n</samp>’, the international form of the
currency symbol is used. This is a four letter string, in this case
<code>"USD "</code>. The last point is that since the precision right of the
decimal point is selected to be three, the first and second numbers are
printed with an extra zero at the end and the third number is printed
without rounding.
</p>
<hr size="6">
<a name="Yes_002dor_002dNo-Questions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Formatting-Numbers" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Locales" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<a name="Yes_002dor_002dNo-Questions-1"></a>
<h2 class="section">7.8 Yes-or-No Questions</h2>
<p>Some non GUI programs ask a yes-or-no question. If the messages
(especially the questions) are translated into foreign languages, be
sure that you localize the answers too. It would be very bad habit to
ask a question in one language and request the answer in another, often
English.
</p>
<p>The GNU C library contains <code>rpmatch</code> to give applications easy
access to the corresponding locale definitions.
</p>
<dl>
<dt><a name="index-rpmatch"></a><u>Function:</u> int <b>rpmatch</b><i> (const char *<var>response</var>)</i></dt>
<dd><p>The function <code>rpmatch</code> checks the string in <var>response</var> whether
or not it is a correct yes-or-no answer and if yes, which one. The
check uses the <code>YESEXPR</code> and <code>NOEXPR</code> data in the
<code>LC_MESSAGES</code> category of the currently selected locale. The
return value is as follows:
</p>
<dl compact="compact">
<dt> <code>1</code></dt>
<dd><p>The user entered an affirmative answer.
</p>
</dd>
<dt> <code>0</code></dt>
<dd><p>The user entered a negative answer.
</p>
</dd>
<dt> <code>-1</code></dt>
<dd><p>The answer matched neither the <code>YESEXPR</code> nor the <code>NOEXPR</code>
regular expression.
</p></dd>
</dl>
<p>This function is not standardized but available beside in GNU libc at
least also in the IBM AIX library.
</p></dd></dl>
<p>This function would normally be used like this:
</p>
<table><tr><td> </td><td><pre class="smallexample"> …
/* <span class="roman">Use a safe default.</span> */
_Bool doit = false;
fputs (gettext ("Do you really want to do this? "), stdout);
fflush (stdout);
/* <span class="roman">Prepare the <code>getline</code> call.</span> */
line = NULL;
len = 0;
while (getline (&line, &len, stdin) >= 0)
{
/* <span class="roman">Check the response.</span> */
int res = rpmatch (line);
if (res >= 0)
{
/* <span class="roman">We got a definitive answer.</span> */
if (res > 0)
doit = true;
break;
}
}
/* <span class="roman">Free what <code>getline</code> allocated.</span> */
free (line);
</pre></td></tr></table>
<p>Note that the loop continues until an read error is detected or until a
definitive (positive or negative) answer is read.
</p><hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Locales" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="libc_8.html#Message-Translation" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="libc_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
<font size="-1">
This document was generated by <em>root</em> on <em>April 20, 2012</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html 1.82</em></a>.
</font>
<br>
</p>
</body>
</html>
|