/usr/share/doc/glibc-doc/html/libc_34.html is in glibc-doc 2.15-0ubuntu10.18.
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 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 | <!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.18) .
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 March 23, 2017 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: A. C Language Facilities in the Library</title>
<meta name="description" content="The GNU C Library: A. C Language Facilities in the Library">
<meta name="keywords" content="The GNU C Library: A. C Language Facilities in the Library">
<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="Language-Features"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="libc_33.html#Backtraces" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Consistency-Checking" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="libc_33.html#Debugging-Support" 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_35.html#Library-Summary" 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="C-Language-Facilities-in-the-Library"></a>
<h1 class="appendix">A. C Language Facilities in the Library</h1>
<p>Some of the facilities implemented by the C library really should be
thought of as parts of the C language itself. These facilities ought to
be documented in the C Language Manual, not in the library manual; but
since we don’t have the language manual yet, and documentation for these
features has been written, we are publishing it here.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Consistency-Checking">A.1 Explicitly Checking Internal Consistency</a></td><td> </td><td align="left" valign="top"> Using <code>assert</code> to abort if
something “impossible” happens.
</td></tr>
<tr><td align="left" valign="top"><a href="#Variadic-Functions">A.2 Variadic Functions</a></td><td> </td><td align="left" valign="top"> Defining functions with varying numbers
of args.
</td></tr>
<tr><td align="left" valign="top"><a href="#Null-Pointer-Constant">A.3 Null Pointer Constant</a></td><td> </td><td align="left" valign="top"> The macro <code>NULL</code>.
</td></tr>
<tr><td align="left" valign="top"><a href="#Important-Data-Types">A.4 Important Data Types</a></td><td> </td><td align="left" valign="top"> Data types for object sizes.
</td></tr>
<tr><td align="left" valign="top"><a href="#Data-Type-Measurements">A.5 Data Type Measurements</a></td><td> </td><td align="left" valign="top"> Parameters of data type representations.
</td></tr>
</table>
<hr size="6">
<a name="Consistency-Checking"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Language-Features" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Variadic-Functions" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Explicitly-Checking-Internal-Consistency"></a>
<h2 class="section">A.1 Explicitly Checking Internal Consistency</h2>
<a name="index-consistency-checking"></a>
<a name="index-impossible-events"></a>
<a name="index-assertions"></a>
<p>When you’re writing a program, it’s often a good idea to put in checks
at strategic places for “impossible” errors or violations of basic
assumptions. These kinds of checks are helpful in debugging problems
with the interfaces between different parts of the program, for example.
</p>
<a name="index-assert_002eh"></a>
<p>The <code>assert</code> macro, defined in the header file ‘<tt>assert.h</tt>’,
provides a convenient way to abort the program while printing a message
about where in the program the error was detected.
</p>
<a name="index-NDEBUG"></a>
<p>Once you think your program is debugged, you can disable the error
checks performed by the <code>assert</code> macro by recompiling with the
macro <code>NDEBUG</code> defined. This means you don’t actually have to
change the program source code to disable these checks.
</p>
<p>But disabling these consistency checks is undesirable unless they make
the program significantly slower. All else being equal, more error
checking is good no matter who is running the program. A wise user
would rather have a program crash, visibly, than have it return nonsense
without indicating anything might be wrong.
</p>
<dl>
<dt><a name="index-assert"></a><u>Macro:</u> void <b>assert</b><i> (int <var>expression</var>)</i></dt>
<dd><p>Verify the programmer’s belief that <var>expression</var> is nonzero at
this point in the program.
</p>
<p>If <code>NDEBUG</code> is not defined, <code>assert</code> tests the value of
<var>expression</var>. If it is false (zero), <code>assert</code> aborts the
program (see section <a href="libc_25.html#Aborting-a-Program">Aborting a Program</a>) after printing a message of the
form:
</p>
<table><tr><td> </td><td><pre class="smallexample">‘<tt><var>file</var></tt>’:<var>linenum</var>: <var>function</var>: Assertion `<var>expression</var>' failed.
</pre></td></tr></table>
<p>on the standard error stream <code>stderr</code> (see section <a href="libc_12.html#Standard-Streams">Standard Streams</a>).
The filename and line number are taken from the C preprocessor macros
<code>__FILE__</code> and <code>__LINE__</code> and specify where the call to
<code>assert</code> was made. When using the GNU C compiler, the name of
the function which calls <code>assert</code> is taken from the built-in
variable <code>__PRETTY_FUNCTION__</code>; with older compilers, the function
name and following colon are omitted.
</p>
<p>If the preprocessor macro <code>NDEBUG</code> is defined before
‘<tt>assert.h</tt>’ is included, the <code>assert</code> macro is defined to do
absolutely nothing.
</p>
<p><strong>Warning:</strong> Even the argument expression <var>expression</var> is not
evaluated if <code>NDEBUG</code> is in effect. So never use <code>assert</code>
with arguments that involve side effects. For example, <code>assert
(++i > 0);</code> is a bad idea, because <code>i</code> will not be incremented if
<code>NDEBUG</code> is defined.
</p></dd></dl>
<p>Sometimes the “impossible” condition you want to check for is an error
return from an operating system function. Then it is useful to display
not only where the program crashes, but also what error was returned.
The <code>assert_perror</code> macro makes this easy.
</p>
<dl>
<dt><a name="index-assert_005fperror"></a><u>Macro:</u> void <b>assert_perror</b><i> (int <var>errnum</var>)</i></dt>
<dd><p>Similar to <code>assert</code>, but verifies that <var>errnum</var> is zero.
</p>
<p>If <code>NDEBUG</code> is not defined, <code>assert_perror</code> tests the value of
<var>errnum</var>. If it is nonzero, <code>assert_perror</code> aborts the program
after printing a message of the form:
</p>
<table><tr><td> </td><td><pre class="smallexample">‘<tt><var>file</var></tt>’:<var>linenum</var>: <var>function</var>: <var>error text</var>
</pre></td></tr></table>
<p>on the standard error stream. The file name, line number, and function
name are as for <code>assert</code>. The error text is the result of
<code>strerror (<var>errnum</var>)</code>. See section <a href="libc_2.html#Error-Messages">Error Messages</a>.
</p>
<p>Like <code>assert</code>, if <code>NDEBUG</code> is defined before ‘<tt>assert.h</tt>’
is included, the <code>assert_perror</code> macro does absolutely nothing. It
does not evaluate the argument, so <var>errnum</var> should not have any side
effects. It is best for <var>errnum</var> to be just a simple variable
reference; often it will be <code>errno</code>.
</p>
<p>This macro is a GNU extension.
</p></dd></dl>
<p><strong>Usage note:</strong> The <code>assert</code> facility is designed for
detecting <em>internal inconsistency</em>; it is not suitable for
reporting invalid input or improper usage by the <em>user</em> of the
program.
</p>
<p>The information in the diagnostic messages printed by the <code>assert</code>
and <code>assert_perror</code> macro is intended to help you, the programmer,
track down the cause of a bug, but is not really useful for telling a user
of your program why his or her input was invalid or why a command could not
be carried out. What’s more, your program should not abort when given
invalid input, as <code>assert</code> would do—it should exit with nonzero
status (see section <a href="libc_25.html#Exit-Status">Exit Status</a>) after printing its error messages, or perhaps
read another command or move on to the next input file.
</p>
<p>See section <a href="libc_2.html#Error-Messages">Error Messages</a>, for information on printing error messages for
problems that <em>do not</em> represent bugs in the program.
</p>
<hr size="6">
<a name="Variadic-Functions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Consistency-Checking" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Why-Variadic" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Variadic-Functions-1"></a>
<h2 class="section">A.2 Variadic Functions</h2>
<a name="index-variable-number-of-arguments"></a>
<a name="index-variadic-functions"></a>
<a name="index-optional-arguments"></a>
<p>ISO C defines a syntax for declaring a function to take a variable
number or type of arguments. (Such functions are referred to as
<em>varargs functions</em> or <em>variadic functions</em>.) However, the
language itself provides no mechanism for such functions to access their
non-required arguments; instead, you use the variable arguments macros
defined in ‘<tt>stdarg.h</tt>’.
</p>
<p>This section describes how to declare variadic functions, how to write
them, and how to call them properly.
</p>
<p><strong>Compatibility Note:</strong> Many older C dialects provide a similar,
but incompatible, mechanism for defining functions with variable numbers
of arguments, using ‘<tt>varargs.h</tt>’.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Why-Variadic">A.2.1 Why Variadic Functions are Used</a></td><td> </td><td align="left" valign="top"> Reasons for making functions take
variable arguments.
</td></tr>
<tr><td align="left" valign="top"><a href="#How-Variadic">A.2.2 How Variadic Functions are Defined and Used</a></td><td> </td><td align="left" valign="top"> How to define and call variadic functions.
</td></tr>
<tr><td align="left" valign="top"><a href="#Variadic-Example">A.2.3 Example of a Variadic Function</a></td><td> </td><td align="left" valign="top"> A complete example.
</td></tr>
</table>
<hr size="6">
<a name="Why-Variadic"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Variadic-Functions" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#How-Variadic" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Variadic-Functions" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Why-Variadic-Functions-are-Used"></a>
<h3 class="subsection">A.2.1 Why Variadic Functions are Used</h3>
<p>Ordinary C functions take a fixed number of arguments. When you define
a function, you specify the data type for each argument. Every call to
the function should supply the expected number of arguments, with types
that can be converted to the specified ones. Thus, if the function
‘<samp>foo</samp>’ is declared with <code>int foo (int, char *);</code> then you must
call it with two arguments, a number (any kind will do) and a string
pointer.
</p>
<p>But some functions perform operations that can meaningfully accept an
unlimited number of arguments.
</p>
<p>In some cases a function can handle any number of values by operating on
all of them as a block. For example, consider a function that allocates
a one-dimensional array with <code>malloc</code> to hold a specified set of
values. This operation makes sense for any number of values, as long as
the length of the array corresponds to that number. Without facilities
for variable arguments, you would have to define a separate function for
each possible array size.
</p>
<p>The library function <code>printf</code> (see section <a href="libc_12.html#Formatted-Output">Formatted Output</a>) is an
example of another class of function where variable arguments are
useful. This function prints its arguments (which can vary in type as
well as number) under the control of a format template string.
</p>
<p>These are good reasons to define a <em>variadic</em> function which can
handle as many arguments as the caller chooses to pass.
</p>
<p>Some functions such as <code>open</code> take a fixed set of arguments, but
occasionally ignore the last few. Strict adherence to ISO C requires
these functions to be defined as variadic; in practice, however, the GNU
C compiler and most other C compilers let you define such a function to
take a fixed set of arguments—the most it can ever use—and then only
<em>declare</em> the function as variadic (or not declare its arguments
at all!).
</p>
<hr size="6">
<a name="How-Variadic"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Why-Variadic" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Variadic-Prototypes" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Variadic-Functions" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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-Variadic-Functions-are-Defined-and-Used"></a>
<h3 class="subsection">A.2.2 How Variadic Functions are Defined and Used</h3>
<p>Defining and using a variadic function involves three steps:
</p>
<ul>
<li>
<em>Define</em> the function as variadic, using an ellipsis
(‘<samp>…</samp>’) in the argument list, and using special macros to
access the variable arguments. See section <a href="#Receiving-Arguments">Receiving the Argument Values</a>.
</li><li>
<em>Declare</em> the function as variadic, using a prototype with an
ellipsis (‘<samp>…</samp>’), in all the files which call it.
See section <a href="#Variadic-Prototypes">Syntax for Variable Arguments</a>.
</li><li>
<em>Call</em> the function by writing the fixed arguments followed by the
additional variable arguments. See section <a href="#Calling-Variadics">Calling Variadic Functions</a>.
</li></ul>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Variadic-Prototypes">A.2.2.1 Syntax for Variable Arguments</a></td><td> </td><td align="left" valign="top"> How to make a prototype for a function
with variable arguments.
</td></tr>
<tr><td align="left" valign="top"><a href="#Receiving-Arguments">A.2.2.2 Receiving the Argument Values</a></td><td> </td><td align="left" valign="top"> Steps you must follow to access the
optional argument values.
</td></tr>
<tr><td align="left" valign="top"><a href="#How-Many-Arguments">A.2.2.3 How Many Arguments Were Supplied</a></td><td> </td><td align="left" valign="top"> How to decide whether there are more arguments.
</td></tr>
<tr><td align="left" valign="top"><a href="#Calling-Variadics">A.2.2.4 Calling Variadic Functions</a></td><td> </td><td align="left" valign="top"> Things you need to know about calling
variable arguments functions.
</td></tr>
<tr><td align="left" valign="top"><a href="#Argument-Macros">A.2.2.5 Argument Access Macros</a></td><td> </td><td align="left" valign="top"> Detailed specification of the macros
for accessing variable arguments.
</td></tr>
<tr><td align="left" valign="top"><a href="#Old-Varargs">A.2.3.1 Old-Style Variadic Functions</a></td><td> </td><td align="left" valign="top"> The pre-ISO way of defining variadic functions.
</td></tr>
</table>
<hr size="6">
<a name="Variadic-Prototypes"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#How-Variadic" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Receiving-Arguments" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#How-Variadic" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Syntax-for-Variable-Arguments"></a>
<h4 class="subsubsection">A.2.2.1 Syntax for Variable Arguments</h4>
<a name="index-function-prototypes-_0028variadic_0029"></a>
<a name="index-prototypes-for-variadic-functions"></a>
<a name="index-variadic-function-prototypes"></a>
<p>A function that accepts a variable number of arguments must be declared
with a prototype that says so. You write the fixed arguments as usual,
and then tack on ‘<samp>…</samp>’ to indicate the possibility of
additional arguments. The syntax of ISO C requires at least one fixed
argument before the ‘<samp>…</samp>’. For example,
</p>
<table><tr><td> </td><td><pre class="smallexample">int
func (const char *a, int b, …)
{
…
}
</pre></td></tr></table>
<p>defines a function <code>func</code> which returns an <code>int</code> and takes two
required arguments, a <code>const char *</code> and an <code>int</code>. These are
followed by any number of anonymous arguments.
</p>
<p><strong>Portability note:</strong> For some C compilers, the last required
argument must not be declared <code>register</code> in the function
definition. Furthermore, this argument’s type must be
<em>self-promoting</em>: that is, the default promotions must not change
its type. This rules out array and function types, as well as
<code>float</code>, <code>char</code> (whether signed or not) and <code>short int</code>
(whether signed or not). This is actually an ISO C requirement.
</p>
<hr size="6">
<a name="Receiving-Arguments"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Variadic-Prototypes" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#How-Many-Arguments" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#How-Variadic" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Receiving-the-Argument-Values"></a>
<h4 class="subsubsection">A.2.2.2 Receiving the Argument Values</h4>
<a name="index-variadic-function-argument-access"></a>
<a name="index-arguments-_0028variadic-functions_0029"></a>
<p>Ordinary fixed arguments have individual names, and you can use these
names to access their values. But optional arguments have no
names—nothing but ‘<samp>…</samp>’. How can you access them?
</p>
<a name="index-stdarg_002eh"></a>
<p>The only way to access them is sequentially, in the order they were
written, and you must use special macros from ‘<tt>stdarg.h</tt>’ in the
following three step process:
</p>
<ol>
<li>
You initialize an argument pointer variable of type <code>va_list</code> using
<code>va_start</code>. The argument pointer when initialized points to the
first optional argument.
</li><li>
You access the optional arguments by successive calls to <code>va_arg</code>.
The first call to <code>va_arg</code> gives you the first optional argument,
the next call gives you the second, and so on.
<p>You can stop at any time if you wish to ignore any remaining optional
arguments. It is perfectly all right for a function to access fewer
arguments than were supplied in the call, but you will get garbage
values if you try to access too many arguments.
</p>
</li><li>
You indicate that you are finished with the argument pointer variable by
calling <code>va_end</code>.
<p>(In practice, with most C compilers, calling <code>va_end</code> does nothing.
This is always true in the GNU C compiler. But you might as well call
<code>va_end</code> just in case your program is someday compiled with a peculiar
compiler.)
</p></li></ol>
<p>See section <a href="#Argument-Macros">Argument Access Macros</a>, for the full definitions of <code>va_start</code>,
<code>va_arg</code> and <code>va_end</code>.
</p>
<p>Steps 1 and 3 must be performed in the function that accepts the
optional arguments. However, you can pass the <code>va_list</code> variable
as an argument to another function and perform all or part of step 2
there.
</p>
<p>You can perform the entire sequence of three steps multiple times
within a single function invocation. If you want to ignore the optional
arguments, you can do these steps zero times.
</p>
<p>You can have more than one argument pointer variable if you like. You
can initialize each variable with <code>va_start</code> when you wish, and
then you can fetch arguments with each argument pointer as you wish.
Each argument pointer variable will sequence through the same set of
argument values, but at its own pace.
</p>
<p><strong>Portability note:</strong> With some compilers, once you pass an
argument pointer value to a subroutine, you must not keep using the same
argument pointer value after that subroutine returns. For full
portability, you should just pass it to <code>va_end</code>. This is actually
an ISO C requirement, but most ANSI C compilers work happily
regardless.
</p>
<hr size="6">
<a name="How-Many-Arguments"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Receiving-Arguments" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Calling-Variadics" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#How-Variadic" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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-Many-Arguments-Were-Supplied"></a>
<h4 class="subsubsection">A.2.2.3 How Many Arguments Were Supplied</h4>
<a name="index-number-of-arguments-passed"></a>
<a name="index-how-many-arguments"></a>
<a name="index-arguments_002c-how-many"></a>
<p>There is no general way for a function to determine the number and type
of the optional arguments it was called with. So whoever designs the
function typically designs a convention for the caller to specify the number
and type of arguments. It is up to you to define an appropriate calling
convention for each variadic function, and write all calls accordingly.
</p>
<p>One kind of calling convention is to pass the number of optional
arguments as one of the fixed arguments. This convention works provided
all of the optional arguments are of the same type.
</p>
<p>A similar alternative is to have one of the required arguments be a bit
mask, with a bit for each possible purpose for which an optional
argument might be supplied. You would test the bits in a predefined
sequence; if the bit is set, fetch the value of the next argument,
otherwise use a default value.
</p>
<p>A required argument can be used as a pattern to specify both the number
and types of the optional arguments. The format string argument to
<code>printf</code> is one example of this (see section <a href="libc_12.html#Formatted-Output-Functions">Formatted Output Functions</a>).
</p>
<p>Another possibility is to pass an “end marker” value as the last
optional argument. For example, for a function that manipulates an
arbitrary number of pointer arguments, a null pointer might indicate the
end of the argument list. (This assumes that a null pointer isn’t
otherwise meaningful to the function.) The <code>execl</code> function works
in just this way; see <a href="libc_26.html#Executing-a-File">Executing a File</a>.
</p>
<hr size="6">
<a name="Calling-Variadics"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#How-Many-Arguments" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Argument-Macros" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#How-Variadic" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Calling-Variadic-Functions"></a>
<h4 class="subsubsection">A.2.2.4 Calling Variadic Functions</h4>
<a name="index-variadic-functions_002c-calling"></a>
<a name="index-calling-variadic-functions"></a>
<a name="index-declaring-variadic-functions"></a>
<p>You don’t have to do anything special to call a variadic function.
Just put the arguments (required arguments, followed by optional ones)
inside parentheses, separated by commas, as usual. But you must declare
the function with a prototype and know how the argument values are converted.
</p>
<p>In principle, functions that are <em>defined</em> to be variadic must also
be <em>declared</em> to be variadic using a function prototype whenever
you call them. (See section <a href="#Variadic-Prototypes">Syntax for Variable Arguments</a>, for how.) This is because
some C compilers use a different calling convention to pass the same set
of argument values to a function depending on whether that function
takes variable arguments or fixed arguments.
</p>
<p>In practice, the GNU C compiler always passes a given set of argument
types in the same way regardless of whether they are optional or
required. So, as long as the argument types are self-promoting, you can
safely omit declaring them. Usually it is a good idea to declare the
argument types for variadic functions, and indeed for all functions.
But there are a few functions which it is extremely convenient not to
have to declare as variadic—for example, <code>open</code> and
<code>printf</code>.
</p>
<a name="index-default-argument-promotions"></a>
<a name="index-argument-promotion"></a>
<p>Since the prototype doesn’t specify types for optional arguments, in a
call to a variadic function the <em>default argument promotions</em> are
performed on the optional argument values. This means the objects of
type <code>char</code> or <code>short int</code> (whether signed or not) are
promoted to either <code>int</code> or <code>unsigned int</code>, as
appropriate; and that objects of type <code>float</code> are promoted to type
<code>double</code>. So, if the caller passes a <code>char</code> as an optional
argument, it is promoted to an <code>int</code>, and the function can access
it with <code>va_arg (<var>ap</var>, int)</code>.
</p>
<p>Conversion of the required arguments is controlled by the function
prototype in the usual way: the argument expression is converted to the
declared argument type as if it were being assigned to a variable of
that type.
</p>
<hr size="6">
<a name="Argument-Macros"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Calling-Variadics" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Variadic-Example" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#How-Variadic" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Argument-Access-Macros"></a>
<h4 class="subsubsection">A.2.2.5 Argument Access Macros</h4>
<p>Here are descriptions of the macros used to retrieve variable arguments.
These macros are defined in the header file ‘<tt>stdarg.h</tt>’.
<a name="index-stdarg_002eh-1"></a>
</p>
<dl>
<dt><a name="index-va_005flist"></a><u>Data Type:</u> <b>va_list</b></dt>
<dd><p>The type <code>va_list</code> is used for argument pointer variables.
</p></dd></dl>
<dl>
<dt><a name="index-va_005fstart"></a><u>Macro:</u> void <b>va_start</b><i> (va_list <var>ap</var>, <var>last-required</var>)</i></dt>
<dd><p>This macro initializes the argument pointer variable <var>ap</var> to point
to the first of the optional arguments of the current function;
<var>last-required</var> must be the last required argument to the function.
</p>
<p>See section <a href="#Old-Varargs">Old-Style Variadic Functions</a>, for an alternate definition of <code>va_start</code>
found in the header file ‘<tt>varargs.h</tt>’.
</p></dd></dl>
<dl>
<dt><a name="index-va_005farg"></a><u>Macro:</u> <var>type</var> <b>va_arg</b><i> (va_list <var>ap</var>, <var>type</var>)</i></dt>
<dd><p>The <code>va_arg</code> macro returns the value of the next optional argument,
and modifies the value of <var>ap</var> to point to the subsequent argument.
Thus, successive uses of <code>va_arg</code> return successive optional
arguments.
</p>
<p>The type of the value returned by <code>va_arg</code> is <var>type</var> as
specified in the call. <var>type</var> must be a self-promoting type (not
<code>char</code> or <code>short int</code> or <code>float</code>) that matches the type
of the actual argument.
</p></dd></dl>
<dl>
<dt><a name="index-va_005fend"></a><u>Macro:</u> void <b>va_end</b><i> (va_list <var>ap</var>)</i></dt>
<dd><p>This ends the use of <var>ap</var>. After a <code>va_end</code> call, further
<code>va_arg</code> calls with the same <var>ap</var> may not work. You should invoke
<code>va_end</code> before returning from the function in which <code>va_start</code>
was invoked with the same <var>ap</var> argument.
</p>
<p>In the GNU C library, <code>va_end</code> does nothing, and you need not ever
use it except for reasons of portability.
</p></dd></dl>
<p>Sometimes it is necessary to parse the list of parameters more than once
or one wants to remember a certain position in the parameter list. To
do this, one will have to make a copy of the current value of the
argument. But <code>va_list</code> is an opaque type and one cannot necessarily
assign the value of one variable of type <code>va_list</code> to another variable
of the same type.
</p>
<dl>
<dt><a name="index-_005f_005fva_005fcopy-1"></a><u>Macro:</u> void <b>__va_copy</b><i> (va_list <var>dest</var>, va_list <var>src</var>)</i></dt>
<dd><p>The <code>__va_copy</code> macro allows copying of objects of type
<code>va_list</code> even if this is not an integral type. The argument pointer
in <var>dest</var> is initialized to point to the same argument as the
pointer in <var>src</var>.
</p>
<p>This macro is a GNU extension but it will hopefully also be available in
the next update of the ISO C standard.
</p></dd></dl>
<p>If you want to use <code>__va_copy</code> you should always be prepared for the
possibility that this macro will not be available. On architectures where a
simple assignment is invalid, hopefully <code>__va_copy</code> <em>will</em> be available,
so one should always write something like this:
</p>
<table><tr><td> </td><td><pre class="smallexample">{
va_list ap, save;
…
#ifdef __va_copy
__va_copy (save, ap);
#else
save = ap;
#endif
…
}
</pre></td></tr></table>
<hr size="6">
<a name="Variadic-Example"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Argument-Macros" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Old-Varargs" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Variadic-Functions" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Example-of-a-Variadic-Function"></a>
<h3 class="subsection">A.2.3 Example of a Variadic Function</h3>
<p>Here is a complete sample function that accepts a variable number of
arguments. The first argument to the function is the count of remaining
arguments, which are added up and the result returned. While trivial,
this function is sufficient to illustrate how to use the variable
arguments facility.
</p>
<table><tr><td> </td><td><pre class="smallexample">#include <stdarg.h>
#include <stdio.h>
int
add_em_up (int count,...)
{
va_list ap;
int i, sum;
va_start (ap, count); /* <span class="roman">Initialize the argument list.</span> */
sum = 0;
for (i = 0; i < count; i++)
sum += va_arg (ap, int); /* <span class="roman">Get the next argument value.</span> */
va_end (ap); /* <span class="roman">Clean up.</span> */
return sum;
}
int
main (void)
{
/* <span class="roman">This call prints 16.</span> */
printf ("%d\n", add_em_up (3, 5, 5, 6));
/* <span class="roman">This call prints 55.</span> */
printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
return 0;
}
</pre></td></tr></table>
<hr size="6">
<a name="Old-Varargs"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Variadic-Example" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Null-Pointer-Constant" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Variadic-Example" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Old_002dStyle-Variadic-Functions"></a>
<h4 class="subsubsection">A.2.3.1 Old-Style Variadic Functions</h4>
<a name="index-varargs_002eh"></a>
<p>Before ISO C, programmers used a slightly different facility for
writing variadic functions. The GNU C compiler still supports it;
currently, it is more portable than the ISO C facility, since support
for ISO C is still not universal. The header file which defines the
old-fashioned variadic facility is called ‘<tt>varargs.h</tt>’.
</p>
<p>Using ‘<tt>varargs.h</tt>’ is almost the same as using ‘<tt>stdarg.h</tt>’.
There is no difference in how you call a variadic function;
see <a href="#Calling-Variadics">Calling Variadic Functions</a>. The only difference is in how you define
them. First of all, you must use old-style non-prototype syntax, like
this:
</p>
<table><tr><td> </td><td><pre class="smallexample">tree
build (va_alist)
va_dcl
{
</pre></td></tr></table>
<p>Secondly, you must give <code>va_start</code> only one argument, like this:
</p>
<table><tr><td> </td><td><pre class="smallexample"> va_list p;
va_start (p);
</pre></td></tr></table>
<p>These are the special macros used for defining old-style variadic
functions:
</p>
<dl>
<dt><a name="index-va_005falist"></a><u>Macro:</u> <b>va_alist</b></dt>
<dd><p>This macro stands for the argument name list required in a variadic
function.
</p></dd></dl>
<dl>
<dt><a name="index-va_005fdcl"></a><u>Macro:</u> <b>va_dcl</b></dt>
<dd><p>This macro declares the implicit argument or arguments for a variadic
function.
</p></dd></dl>
<dl>
<dt><a name="index-va_005fstart-1"></a><u>Macro:</u> void <b>va_start</b><i> (va_list <var>ap</var>)</i></dt>
<dd><p>This macro, as defined in ‘<tt>varargs.h</tt>’, initializes the argument
pointer variable <var>ap</var> to point to the first argument of the current
function.
</p></dd></dl>
<p>The other argument macros, <code>va_arg</code> and <code>va_end</code>, are the same
in ‘<tt>varargs.h</tt>’ as in ‘<tt>stdarg.h</tt>’; see <a href="#Argument-Macros">Argument Access Macros</a>, for
details.
</p>
<p>It does not work to include both ‘<tt>varargs.h</tt>’ and ‘<tt>stdarg.h</tt>’ in
the same compilation; they define <code>va_start</code> in conflicting ways.
</p>
<hr size="6">
<a name="Null-Pointer-Constant"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Old-Varargs" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Important-Data-Types" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Null-Pointer-Constant-1"></a>
<h2 class="section">A.3 Null Pointer Constant</h2>
<a name="index-null-pointer-constant"></a>
<p>The null pointer constant is guaranteed not to point to any real object.
You can assign it to any pointer variable since it has type <code>void
*</code>. The preferred way to write a null pointer constant is with
<code>NULL</code>.
</p>
<dl>
<dt><a name="index-NULL"></a><u>Macro:</u> void * <b>NULL</b></dt>
<dd><p>This is a null pointer constant.
</p></dd></dl>
<p>You can also use <code>0</code> or <code>(void *)0</code> as a null pointer
constant, but using <code>NULL</code> is cleaner because it makes the purpose
of the constant more evident.
</p>
<p>If you use the null pointer constant as a function argument, then for
complete portability you should make sure that the function has a
prototype declaration. Otherwise, if the target machine has two
different pointer representations, the compiler won’t know which
representation to use for that argument. You can avoid the problem by
explicitly casting the constant to the proper pointer type, but we
recommend instead adding a prototype for the function you are calling.
</p>
<hr size="6">
<a name="Important-Data-Types"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Null-Pointer-Constant" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Data-Type-Measurements" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Important-Data-Types-1"></a>
<h2 class="section">A.4 Important Data Types</h2>
<p>The result of subtracting two pointers in C is always an integer, but the
precise data type varies from C compiler to C compiler. Likewise, the
data type of the result of <code>sizeof</code> also varies between compilers.
ISO defines standard aliases for these two types, so you can refer to
them in a portable fashion. They are defined in the header file
‘<tt>stddef.h</tt>’.
<a name="index-stddef_002eh"></a>
</p>
<dl>
<dt><a name="index-ptrdiff_005ft"></a><u>Data Type:</u> <b>ptrdiff_t</b></dt>
<dd><p>This is the signed integer type of the result of subtracting two
pointers. For example, with the declaration <code>char *p1, *p2;</code>, the
expression <code>p2 - p1</code> is of type <code>ptrdiff_t</code>. This will
probably be one of the standard signed integer types (<code>short
int</code>, <code>int</code> or <code>long int</code>), but might be a nonstandard
type that exists only for this purpose.
</p></dd></dl>
<dl>
<dt><a name="index-size_005ft"></a><u>Data Type:</u> <b>size_t</b></dt>
<dd><p>This is an unsigned integer type used to represent the sizes of objects.
The result of the <code>sizeof</code> operator is of this type, and functions
such as <code>malloc</code> (see section <a href="libc_3.html#Unconstrained-Allocation">Unconstrained Allocation</a>) and
<code>memcpy</code> (see section <a href="libc_5.html#Copying-and-Concatenation">Copying and Concatenation</a>) accept arguments of
this type to specify object sizes.
</p>
<p><strong>Usage Note:</strong> <code>size_t</code> is the preferred way to declare any
arguments or variables that hold the size of an object.
</p></dd></dl>
<p>In the GNU system <code>size_t</code> is equivalent to either
<code>unsigned int</code> or <code>unsigned long int</code>. These types
have identical properties on the GNU system and, for most purposes, you
can use them interchangeably. However, they are distinct as data types,
which makes a difference in certain contexts.
</p>
<p>For example, when you specify the type of a function argument in a
function prototype, it makes a difference which one you use. If the
system header files declare <code>malloc</code> with an argument of type
<code>size_t</code> and you declare <code>malloc</code> with an argument of type
<code>unsigned int</code>, you will get a compilation error if <code>size_t</code>
happens to be <code>unsigned long int</code> on your system. To avoid any
possibility of error, when a function argument or value is supposed to
have type <code>size_t</code>, never declare its type in any other way.
</p>
<p><strong>Compatibility Note:</strong> Implementations of C before the advent of
ISO C generally used <code>unsigned int</code> for representing object sizes
and <code>int</code> for pointer subtraction results. They did not
necessarily define either <code>size_t</code> or <code>ptrdiff_t</code>. Unix
systems did define <code>size_t</code>, in ‘<tt>sys/types.h</tt>’, but the
definition was usually a signed type.
</p>
<hr size="6">
<a name="Data-Type-Measurements"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Important-Data-Types" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Width-of-Type" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Data-Type-Measurements-1"></a>
<h2 class="section">A.5 Data Type Measurements</h2>
<p>Most of the time, if you choose the proper C data type for each object
in your program, you need not be concerned with just how it is
represented or how many bits it uses. When you do need such
information, the C language itself does not provide a way to get it.
The header files ‘<tt>limits.h</tt>’ and ‘<tt>float.h</tt>’ contain macros
which give you this information in full detail.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Width-of-Type">A.5.1 Computing the Width of an Integer Data Type</a></td><td> </td><td align="left" valign="top"> How many bits does an integer type hold?
</td></tr>
<tr><td align="left" valign="top"><a href="#Range-of-Type">A.5.2 Range of an Integer Type</a></td><td> </td><td align="left" valign="top"> What are the largest and smallest values
that an integer type can hold?
</td></tr>
<tr><td align="left" valign="top"><a href="#Floating-Type-Macros">A.5.3 Floating Type Macros</a></td><td> </td><td align="left" valign="top"> Parameters that measure the floating point types.
</td></tr>
<tr><td align="left" valign="top"><a href="#Structure-Measurement">A.5.4 Structure Field Offset Measurement</a></td><td> </td><td align="left" valign="top"> Getting measurements on structure types.
</td></tr>
</table>
<hr size="6">
<a name="Width-of-Type"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Data-Type-Measurements" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Range-of-Type" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Data-Type-Measurements" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Computing-the-Width-of-an-Integer-Data-Type"></a>
<h3 class="subsection">A.5.1 Computing the Width of an Integer Data Type</h3>
<a name="index-integer-type-width"></a>
<a name="index-width-of-integer-type"></a>
<a name="index-type-measurements_002c-integer"></a>
<p>The most common reason that a program needs to know how many bits are in
an integer type is for using an array of <code>long int</code> as a bit vector.
You can access the bit at index <var>n</var> with
</p>
<table><tr><td> </td><td><pre class="smallexample">vector[<var>n</var> / LONGBITS] & (1 << (<var>n</var> % LONGBITS))
</pre></td></tr></table>
<p>provided you define <code>LONGBITS</code> as the number of bits in a
<code>long int</code>.
</p>
<a name="index-limits_002eh-4"></a>
<p>There is no operator in the C language that can give you the number of
bits in an integer data type. But you can compute it from the macro
<code>CHAR_BIT</code>, defined in the header file ‘<tt>limits.h</tt>’.
</p>
<dl compact="compact">
<dt> <code>CHAR_BIT</code></dt>
<dd><p>This is the number of bits in a <code>char</code>—eight, on most systems.
The value has type <code>int</code>.
</p>
<p>You can compute the number of bits in any data type <var>type</var> like
this:
</p>
<table><tr><td> </td><td><pre class="smallexample">sizeof (<var>type</var>) * CHAR_BIT
</pre></td></tr></table>
</dd>
</dl>
<hr size="6">
<a name="Range-of-Type"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Width-of-Type" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Floating-Type-Macros" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Data-Type-Measurements" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Range-of-an-Integer-Type"></a>
<h3 class="subsection">A.5.2 Range of an Integer Type</h3>
<a name="index-integer-type-range"></a>
<a name="index-range-of-integer-type"></a>
<a name="index-limits_002c-integer-types"></a>
<p>Suppose you need to store an integer value which can range from zero to
one million. Which is the smallest type you can use? There is no
general rule; it depends on the C compiler and target machine. You can
use the ‘<samp>MIN</samp>’ and ‘<samp>MAX</samp>’ macros in ‘<tt>limits.h</tt>’ to determine
which type will work.
</p>
<p>Each signed integer type has a pair of macros which give the smallest
and largest values that it can hold. Each unsigned integer type has one
such macro, for the maximum value; the minimum value is, of course,
zero.
</p>
<p>The values of these macros are all integer constant expressions. The
‘<samp>MAX</samp>’ and ‘<samp>MIN</samp>’ macros for <code>char</code> and <code>short
int</code> types have values of type <code>int</code>. The ‘<samp>MAX</samp>’ and
‘<samp>MIN</samp>’ macros for the other types have values of the same type
described by the macro—thus, <code>ULONG_MAX</code> has type
<code>unsigned long int</code>.
</p>
<dl compact="compact">
<dt> <code>SCHAR_MIN</code>
<a name="index-SCHAR_005fMIN"></a>
</dt>
<dd>
<p>This is the minimum value that can be represented by a <code>signed char</code>.
</p>
</dd>
<dt> <code>SCHAR_MAX</code>
<a name="index-SCHAR_005fMAX"></a>
</dt>
<dt> <code>UCHAR_MAX</code>
<a name="index-UCHAR_005fMAX"></a>
</dt>
<dd>
<p>These are the maximum values that can be represented by a
<code>signed char</code> and <code>unsigned char</code>, respectively.
</p>
</dd>
<dt> <code>CHAR_MIN</code>
<a name="index-CHAR_005fMIN"></a>
</dt>
<dd>
<p>This is the minimum value that can be represented by a <code>char</code>.
It’s equal to <code>SCHAR_MIN</code> if <code>char</code> is signed, or zero
otherwise.
</p>
</dd>
<dt> <code>CHAR_MAX</code>
<a name="index-CHAR_005fMAX"></a>
</dt>
<dd>
<p>This is the maximum value that can be represented by a <code>char</code>.
It’s equal to <code>SCHAR_MAX</code> if <code>char</code> is signed, or
<code>UCHAR_MAX</code> otherwise.
</p>
</dd>
<dt> <code>SHRT_MIN</code>
<a name="index-SHRT_005fMIN"></a>
</dt>
<dd>
<p>This is the minimum value that can be represented by a <code>signed
short int</code>. On most machines that the GNU C library runs on,
<code>short</code> integers are 16-bit quantities.
</p>
</dd>
<dt> <code>SHRT_MAX</code>
<a name="index-SHRT_005fMAX"></a>
</dt>
<dt> <code>USHRT_MAX</code>
<a name="index-USHRT_005fMAX"></a>
</dt>
<dd>
<p>These are the maximum values that can be represented by a
<code>signed short int</code> and <code>unsigned short int</code>,
respectively.
</p>
</dd>
<dt> <code>INT_MIN</code>
<a name="index-INT_005fMIN"></a>
</dt>
<dd>
<p>This is the minimum value that can be represented by a <code>signed
int</code>. On most machines that the GNU C system runs on, an <code>int</code> is
a 32-bit quantity.
</p>
</dd>
<dt> <code>INT_MAX</code>
<a name="index-INT_005fMAX"></a>
</dt>
<dt> <code>UINT_MAX</code>
<a name="index-UINT_005fMAX"></a>
</dt>
<dd>
<p>These are the maximum values that can be represented by, respectively,
the type <code>signed int</code> and the type <code>unsigned int</code>.
</p>
</dd>
<dt> <code>LONG_MIN</code>
<a name="index-LONG_005fMIN"></a>
</dt>
<dd>
<p>This is the minimum value that can be represented by a <code>signed
long int</code>. On most machines that the GNU C system runs on, <code>long</code>
integers are 32-bit quantities, the same size as <code>int</code>.
</p>
</dd>
<dt> <code>LONG_MAX</code>
<a name="index-LONG_005fMAX"></a>
</dt>
<dt> <code>ULONG_MAX</code>
<a name="index-ULONG_005fMAX"></a>
</dt>
<dd>
<p>These are the maximum values that can be represented by a
<code>signed long int</code> and <code>unsigned long int</code>, respectively.
</p>
</dd>
<dt> <code>LONG_LONG_MIN</code>
<a name="index-LONG_005fLONG_005fMIN"></a>
</dt>
<dd>
<p>This is the minimum value that can be represented by a <code>signed
long long int</code>. On most machines that the GNU C system runs on,
<code>long long</code> integers are 64-bit quantities.
</p>
</dd>
<dt> <code>LONG_LONG_MAX</code>
<a name="index-LONG_005fLONG_005fMAX"></a>
</dt>
<dt> <code>ULONG_LONG_MAX</code>
<a name="index-ULONG_005fLONG_005fMAX"></a>
</dt>
<dd>
<p>These are the maximum values that can be represented by a <code>signed
long long int</code> and <code>unsigned long long int</code>, respectively.
</p>
</dd>
<dt> <code>WCHAR_MAX</code>
<a name="index-WCHAR_005fMAX-1"></a>
</dt>
<dd>
<p>This is the maximum value that can be represented by a <code>wchar_t</code>.
See section <a href="libc_6.html#Extended-Char-Intro">Introduction to Extended Characters</a>.
</p></dd>
</dl>
<p>The header file ‘<tt>limits.h</tt>’ also defines some additional constants
that parameterize various operating system and file system limits. These
constants are described in <a href="libc_31.html#System-Configuration">System Configuration Parameters</a>.
</p>
<hr size="6">
<a name="Floating-Type-Macros"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Range-of-Type" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Floating-Point-Concepts" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Data-Type-Measurements" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Floating-Type-Macros-1"></a>
<h3 class="subsection">A.5.3 Floating Type Macros</h3>
<a name="index-floating-type-measurements"></a>
<a name="index-measurements-of-floating-types"></a>
<a name="index-type-measurements_002c-floating"></a>
<a name="index-limits_002c-floating-types"></a>
<p>The specific representation of floating point numbers varies from
machine to machine. Because floating point numbers are represented
internally as approximate quantities, algorithms for manipulating
floating point data often need to take account of the precise details of
the machine’s floating point representation.
</p>
<p>Some of the functions in the C library itself need this information; for
example, the algorithms for printing and reading floating point numbers
(see section <a href="libc_12.html#I_002fO-on-Streams">Input/Output on Streams</a>) and for calculating trigonometric and
irrational functions (see section <a href="libc_19.html#Mathematics">Mathematics</a>) use it to avoid round-off
error and loss of accuracy. User programs that implement numerical
analysis techniques also often need this information in order to
minimize or compute error bounds.
</p>
<p>The header file ‘<tt>float.h</tt>’ describes the format used by your
machine.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#Floating-Point-Concepts">A.5.3.1 Floating Point Representation Concepts</a></td><td> </td><td align="left" valign="top"> Definitions of terminology.
</td></tr>
<tr><td align="left" valign="top"><a href="#Floating-Point-Parameters">A.5.3.2 Floating Point Parameters</a></td><td> </td><td align="left" valign="top"> Details of specific macros.
</td></tr>
<tr><td align="left" valign="top"><a href="#IEEE-Floating-Point">A.5.3.3 IEEE Floating Point</a></td><td> </td><td align="left" valign="top"> The measurements for one common
representation.
</td></tr>
</table>
<hr size="6">
<a name="Floating-Point-Concepts"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Floating-Type-Macros" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Floating-Point-Parameters" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Floating-Type-Macros" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Floating-Point-Representation-Concepts"></a>
<h4 class="subsubsection">A.5.3.1 Floating Point Representation Concepts</h4>
<p>This section introduces the terminology for describing floating point
representations.
</p>
<p>You are probably already familiar with most of these concepts in terms
of scientific or exponential notation for floating point numbers. For
example, the number <code>123456.0</code> could be expressed in exponential
notation as <code>1.23456e+05</code>, a shorthand notation indicating that the
mantissa <code>1.23456</code> is multiplied by the base <code>10</code> raised to
power <code>5</code>.
</p>
<p>More formally, the internal representation of a floating point number
can be characterized in terms of the following parameters:
</p>
<ul>
<li>
<a name="index-sign-_0028of-floating-point-number_0029"></a>
The <em>sign</em> is either <code>-1</code> or <code>1</code>.
</li><li>
<a name="index-base-_0028of-floating-point-number_0029"></a>
<a name="index-radix-_0028of-floating-point-number_0029"></a>
The <em>base</em> or <em>radix</em> for exponentiation, an integer greater
than <code>1</code>. This is a constant for a particular representation.
</li><li>
<a name="index-exponent-_0028of-floating-point-number_0029"></a>
The <em>exponent</em> to which the base is raised. The upper and lower
bounds of the exponent value are constants for a particular
representation.
<a name="index-bias-_0028of-floating-point-number-exponent_0029"></a>
<p>Sometimes, in the actual bits representing the floating point number,
the exponent is <em>biased</em> by adding a constant to it, to make it
always be represented as an unsigned quantity. This is only important
if you have some reason to pick apart the bit fields making up the
floating point number by hand, which is something for which the GNU
library provides no support. So this is ignored in the discussion that
follows.
</p>
</li><li>
<a name="index-mantissa-_0028of-floating-point-number_0029"></a>
<a name="index-significand-_0028of-floating-point-number_0029"></a>
The <em>mantissa</em> or <em>significand</em> is an unsigned integer which is a
part of each floating point number.
</li><li>
<a name="index-precision-_0028of-floating-point-number_0029"></a>
The <em>precision</em> of the mantissa. If the base of the representation
is <var>b</var>, then the precision is the number of base-<var>b</var> digits in
the mantissa. This is a constant for a particular representation.
<a name="index-hidden-bit-_0028of-floating-point-number-mantissa_0029"></a>
<p>Many floating point representations have an implicit <em>hidden bit</em> in
the mantissa. This is a bit which is present virtually in the mantissa,
but not stored in memory because its value is always 1 in a normalized
number. The precision figure (see above) includes any hidden bits.
</p>
<p>Again, the GNU library provides no facilities for dealing with such
low-level aspects of the representation.
</p></li></ul>
<p>The mantissa of a floating point number represents an implicit fraction
whose denominator is the base raised to the power of the precision. Since
the largest representable mantissa is one less than this denominator, the
value of the fraction is always strictly less than <code>1</code>. The
mathematical value of a floating point number is then the product of this
fraction, the sign, and the base raised to the exponent.
</p>
<a name="index-normalized-floating-point-number"></a>
<p>We say that the floating point number is <em>normalized</em> if the
fraction is at least <code>1/<var>b</var></code>, where <var>b</var> is the base. In
other words, the mantissa would be too large to fit if it were
multiplied by the base. Non-normalized numbers are sometimes called
<em>denormal</em>; they contain less precision than the representation
normally can hold.
</p>
<p>If the number is not normalized, then you can subtract <code>1</code> from the
exponent while multiplying the mantissa by the base, and get another
floating point number with the same value. <em>Normalization</em> consists
of doing this repeatedly until the number is normalized. Two distinct
normalized floating point numbers cannot be equal in value.
</p>
<p>(There is an exception to this rule: if the mantissa is zero, it is
considered normalized. Another exception happens on certain machines
where the exponent is as small as the representation can hold. Then
it is impossible to subtract <code>1</code> from the exponent, so a number
may be normalized even if its fraction is less than <code>1/<var>b</var></code>.)
</p>
<hr size="6">
<a name="Floating-Point-Parameters"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Floating-Point-Concepts" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#IEEE-Floating-Point" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Floating-Type-Macros" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Floating-Point-Parameters-1"></a>
<h4 class="subsubsection">A.5.3.2 Floating Point Parameters</h4>
<a name="index-float_002eh"></a>
<p>These macro definitions can be accessed by including the header file
‘<tt>float.h</tt>’ in your program.
</p>
<p>Macro names starting with ‘<samp>FLT_</samp>’ refer to the <code>float</code> type,
while names beginning with ‘<samp>DBL_</samp>’ refer to the <code>double</code> type
and names beginning with ‘<samp>LDBL_</samp>’ refer to the <code>long double</code>
type. (If GCC does not support <code>long double</code> as a distinct data
type on a target machine then the values for the ‘<samp>LDBL_</samp>’ constants
are equal to the corresponding constants for the <code>double</code> type.)
</p>
<p>Of these macros, only <code>FLT_RADIX</code> is guaranteed to be a constant
expression. The other macros listed here cannot be reliably used in
places that require constant expressions, such as ‘<samp>#if</samp>’
preprocessing directives or in the dimensions of static arrays.
</p>
<p>Although the ISO C standard specifies minimum and maximum values for
most of these parameters, the GNU C implementation uses whatever values
describe the floating point representation of the target machine. So in
principle GNU C actually satisfies the ISO C requirements only if the
target machine is suitable. In practice, all the machines currently
supported are suitable.
</p>
<dl compact="compact">
<dt> <code>FLT_ROUNDS</code>
<a name="index-FLT_005fROUNDS"></a>
</dt>
<dd><p>This value characterizes the rounding mode for floating point addition.
The following values indicate standard rounding modes:
</p>
<dl compact="compact">
<dt> <code>-1</code></dt>
<dd><p>The mode is indeterminable.
</p></dd>
<dt> <code>0</code></dt>
<dd><p>Rounding is towards zero.
</p></dd>
<dt> <code>1</code></dt>
<dd><p>Rounding is to the nearest number.
</p></dd>
<dt> <code>2</code></dt>
<dd><p>Rounding is towards positive infinity.
</p></dd>
<dt> <code>3</code></dt>
<dd><p>Rounding is towards negative infinity.
</p></dd>
</dl>
<p>Any other value represents a machine-dependent nonstandard rounding
mode.
</p>
<p>On most machines, the value is <code>1</code>, in accordance with the IEEE
standard for floating point.
</p>
<p>Here is a table showing how certain values round for each possible value
of <code>FLT_ROUNDS</code>, if the other aspects of the representation match
the IEEE single-precision standard.
</p>
<table><tr><td> </td><td><pre class="smallexample"> 0 1 2 3
1.00000003 1.0 1.0 1.00000012 1.0
1.00000007 1.0 1.00000012 1.00000012 1.0
-1.00000003 -1.0 -1.0 -1.0 -1.00000012
-1.00000007 -1.0 -1.00000012 -1.0 -1.00000012
</pre></td></tr></table>
</dd>
<dt> <code>FLT_RADIX</code>
<a name="index-FLT_005fRADIX"></a>
</dt>
<dd><p>This is the value of the base, or radix, of the exponent representation.
This is guaranteed to be a constant expression, unlike the other macros
described in this section. The value is 2 on all machines we know of
except the IBM 360 and derivatives.
</p>
</dd>
<dt> <code>FLT_MANT_DIG</code>
<a name="index-FLT_005fMANT_005fDIG"></a>
</dt>
<dd><p>This is the number of base-<code>FLT_RADIX</code> digits in the floating point
mantissa for the <code>float</code> data type. The following expression
yields <code>1.0</code> (even though mathematically it should not) due to the
limited number of mantissa digits:
</p>
<table><tr><td> </td><td><pre class="smallexample">float radix = FLT_RADIX;
1.0f + 1.0f / radix / radix / … / radix
</pre></td></tr></table>
<p>where <code>radix</code> appears <code>FLT_MANT_DIG</code> times.
</p>
</dd>
<dt> <code>DBL_MANT_DIG</code>
<a name="index-DBL_005fMANT_005fDIG"></a>
</dt>
<dt> <code>LDBL_MANT_DIG</code>
<a name="index-LDBL_005fMANT_005fDIG"></a>
</dt>
<dd><p>This is the number of base-<code>FLT_RADIX</code> digits in the floating point
mantissa for the data types <code>double</code> and <code>long double</code>,
respectively.
</p>
</dd>
<dt> <code>FLT_DIG</code>
<a name="index-FLT_005fDIG"></a>
</dt>
<dd>
<p>This is the number of decimal digits of precision for the <code>float</code>
data type. Technically, if <var>p</var> and <var>b</var> are the precision and
base (respectively) for the representation, then the decimal precision
<var>q</var> is the maximum number of decimal digits such that any floating
point number with <var>q</var> base 10 digits can be rounded to a floating
point number with <var>p</var> base <var>b</var> digits and back again, without
change to the <var>q</var> decimal digits.
</p>
<p>The value of this macro is supposed to be at least <code>6</code>, to satisfy
ISO C.
</p>
</dd>
<dt> <code>DBL_DIG</code>
<a name="index-DBL_005fDIG"></a>
</dt>
<dt> <code>LDBL_DIG</code>
<a name="index-LDBL_005fDIG"></a>
</dt>
<dd>
<p>These are similar to <code>FLT_DIG</code>, but for the data types
<code>double</code> and <code>long double</code>, respectively. The values of these
macros are supposed to be at least <code>10</code>.
</p>
</dd>
<dt> <code>FLT_MIN_EXP</code>
<a name="index-FLT_005fMIN_005fEXP"></a>
</dt>
<dd><p>This is the smallest possible exponent value for type <code>float</code>.
More precisely, is the minimum negative integer such that the value
<code>FLT_RADIX</code> raised to this power minus 1 can be represented as a
normalized floating point number of type <code>float</code>.
</p>
</dd>
<dt> <code>DBL_MIN_EXP</code>
<a name="index-DBL_005fMIN_005fEXP"></a>
</dt>
<dt> <code>LDBL_MIN_EXP</code>
<a name="index-LDBL_005fMIN_005fEXP"></a>
</dt>
<dd>
<p>These are similar to <code>FLT_MIN_EXP</code>, but for the data types
<code>double</code> and <code>long double</code>, respectively.
</p>
</dd>
<dt> <code>FLT_MIN_10_EXP</code>
<a name="index-FLT_005fMIN_005f10_005fEXP"></a>
</dt>
<dd><p>This is the minimum negative integer such that <code>10</code> raised to this
power minus 1 can be represented as a normalized floating point number
of type <code>float</code>. This is supposed to be <code>-37</code> or even less.
</p>
</dd>
<dt> <code>DBL_MIN_10_EXP</code>
<a name="index-DBL_005fMIN_005f10_005fEXP"></a>
</dt>
<dt> <code>LDBL_MIN_10_EXP</code>
<a name="index-LDBL_005fMIN_005f10_005fEXP"></a>
</dt>
<dd><p>These are similar to <code>FLT_MIN_10_EXP</code>, but for the data types
<code>double</code> and <code>long double</code>, respectively.
</p>
</dd>
<dt> <code>FLT_MAX_EXP</code>
<a name="index-FLT_005fMAX_005fEXP"></a>
</dt>
<dd><p>This is the largest possible exponent value for type <code>float</code>. More
precisely, this is the maximum positive integer such that value
<code>FLT_RADIX</code> raised to this power minus 1 can be represented as a
floating point number of type <code>float</code>.
</p>
</dd>
<dt> <code>DBL_MAX_EXP</code>
<a name="index-DBL_005fMAX_005fEXP"></a>
</dt>
<dt> <code>LDBL_MAX_EXP</code>
<a name="index-LDBL_005fMAX_005fEXP"></a>
</dt>
<dd><p>These are similar to <code>FLT_MAX_EXP</code>, but for the data types
<code>double</code> and <code>long double</code>, respectively.
</p>
</dd>
<dt> <code>FLT_MAX_10_EXP</code>
<a name="index-FLT_005fMAX_005f10_005fEXP"></a>
</dt>
<dd><p>This is the maximum positive integer such that <code>10</code> raised to this
power minus 1 can be represented as a normalized floating point number
of type <code>float</code>. This is supposed to be at least <code>37</code>.
</p>
</dd>
<dt> <code>DBL_MAX_10_EXP</code>
<a name="index-DBL_005fMAX_005f10_005fEXP"></a>
</dt>
<dt> <code>LDBL_MAX_10_EXP</code>
<a name="index-LDBL_005fMAX_005f10_005fEXP"></a>
</dt>
<dd><p>These are similar to <code>FLT_MAX_10_EXP</code>, but for the data types
<code>double</code> and <code>long double</code>, respectively.
</p>
</dd>
<dt> <code>FLT_MAX</code>
<a name="index-FLT_005fMAX"></a>
</dt>
<dd>
<p>The value of this macro is the maximum number representable in type
<code>float</code>. It is supposed to be at least <code>1E+37</code>. The value
has type <code>float</code>.
</p>
<p>The smallest representable number is <code>- FLT_MAX</code>.
</p>
</dd>
<dt> <code>DBL_MAX</code>
<a name="index-DBL_005fMAX"></a>
</dt>
<dt> <code>LDBL_MAX</code>
<a name="index-LDBL_005fMAX"></a>
</dt>
<dd>
<p>These are similar to <code>FLT_MAX</code>, but for the data types
<code>double</code> and <code>long double</code>, respectively. The type of the
macro’s value is the same as the type it describes.
</p>
</dd>
<dt> <code>FLT_MIN</code>
<a name="index-FLT_005fMIN"></a>
</dt>
<dd>
<p>The value of this macro is the minimum normalized positive floating
point number that is representable in type <code>float</code>. It is supposed
to be no more than <code>1E-37</code>.
</p>
</dd>
<dt> <code>DBL_MIN</code>
<a name="index-DBL_005fMIN"></a>
</dt>
<dt> <code>LDBL_MIN</code>
<a name="index-LDBL_005fMIN"></a>
</dt>
<dd>
<p>These are similar to <code>FLT_MIN</code>, but for the data types
<code>double</code> and <code>long double</code>, respectively. The type of the
macro’s value is the same as the type it describes.
</p>
</dd>
<dt> <code>FLT_EPSILON</code>
<a name="index-FLT_005fEPSILON"></a>
</dt>
<dd>
<p>This is the minimum positive floating point number of type <code>float</code>
such that <code>1.0 + FLT_EPSILON != 1.0</code> is true. It’s supposed to
be no greater than <code>1E-5</code>.
</p>
</dd>
<dt> <code>DBL_EPSILON</code>
<a name="index-DBL_005fEPSILON"></a>
</dt>
<dt> <code>LDBL_EPSILON</code>
<a name="index-LDBL_005fEPSILON"></a>
</dt>
<dd>
<p>These are similar to <code>FLT_EPSILON</code>, but for the data types
<code>double</code> and <code>long double</code>, respectively. The type of the
macro’s value is the same as the type it describes. The values are not
supposed to be greater than <code>1E-9</code>.
</p></dd>
</dl>
<hr size="6">
<a name="IEEE-Floating-Point"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Floating-Point-Parameters" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#Structure-Measurement" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Floating-Type-Macros" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="IEEE-Floating-Point-1"></a>
<h4 class="subsubsection">A.5.3.3 IEEE Floating Point</h4>
<a name="index-IEEE-floating-point-representation"></a>
<a name="index-floating-point_002c-IEEE"></a>
<p>Here is an example showing how the floating type measurements come out
for the most common floating point representation, specified by the
<cite>IEEE Standard for Binary Floating Point Arithmetic (ANSI/IEEE Std
754-1985)</cite>. Nearly all computers designed since the 1980s use this
format.
</p>
<p>The IEEE single-precision float representation uses a base of 2. There
is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total
precision is 24 base-2 digits), and an 8-bit exponent that can represent
values in the range -125 to 128, inclusive.
</p>
<p>So, for an implementation that uses this representation for the
<code>float</code> data type, appropriate values for the corresponding
parameters are:
</p>
<table><tr><td> </td><td><pre class="smallexample">FLT_RADIX 2
FLT_MANT_DIG 24
FLT_DIG 6
FLT_MIN_EXP -125
FLT_MIN_10_EXP -37
FLT_MAX_EXP 128
FLT_MAX_10_EXP +38
FLT_MIN 1.17549435E-38F
FLT_MAX 3.40282347E+38F
FLT_EPSILON 1.19209290E-07F
</pre></td></tr></table>
<p>Here are the values for the <code>double</code> data type:
</p>
<table><tr><td> </td><td><pre class="smallexample">DBL_MANT_DIG 53
DBL_DIG 15
DBL_MIN_EXP -1021
DBL_MIN_10_EXP -307
DBL_MAX_EXP 1024
DBL_MAX_10_EXP 308
DBL_MAX 1.7976931348623157E+308
DBL_MIN 2.2250738585072014E-308
DBL_EPSILON 2.2204460492503131E-016
</pre></td></tr></table>
<hr size="6">
<a name="Structure-Measurement"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#IEEE-Floating-Point" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#Data-Type-Measurements" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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="Structure-Field-Offset-Measurement"></a>
<h3 class="subsection">A.5.4 Structure Field Offset Measurement</h3>
<p>You can use <code>offsetof</code> to measure the location within a structure
type of a particular structure member.
</p>
<dl>
<dt><a name="index-offsetof"></a><u>Macro:</u> size_t <b>offsetof</b><i> (<var>type</var>, <var>member</var>)</i></dt>
<dd><p>This expands to a integer constant expression that is the offset of the
structure member named <var>member</var> in the structure type <var>type</var>.
For example, <code>offsetof (struct s, elem)</code> is the offset, in bytes,
of the member <code>elem</code> in a <code>struct s</code>.
</p>
<p>This macro won’t work if <var>member</var> is a bit field; you get an error
from the C compiler in that case.
</p></dd></dl>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#Language-Features" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="libc_35.html#Library-Summary" 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>March 23, 2017</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html 1.82</em></a>.
</font>
<br>
</p>
</body>
</html>
|