release/src-rt-6.x.4708/toolchains/hndtools-arm-linux-2.6.36-uclibc-4.5.3/share/doc/mpfr/FAQ.html

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3
   4 <!--
   5 Copyright 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
   6 Contributed by the Arenaire and Cacao projects, INRIA.
   7
   8 This file is part of the GNU MPFR Library.
   9
  10 The GNU MPFR Library is free software; you can redistribute it and/or modify
  11 it under the terms of the GNU Lesser General Public License as published by
  12 the Free Software Foundation; either version 3 of the License, or (at your
  13 option) any later version.
  14
  15 The GNU MPFR Library is distributed in the hope that it will be useful, but
  16 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  17 or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  18 License for more details.
  19
  20 You should have received a copy of the GNU Lesser General Public License
  21 along with the GNU MPFR Library; see the file COPYING.LESSER.  If not, see
  22 http://www.gnu.org/licenses/ or write to the Free Software Foundation, Inc.,
  23 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
  24 -->
  25
  26 <!--
  27     Do not modify directly! Regenerate this file with:
  28       xsltproc -\-nodtdattr faq-web.xsl faq.xhtml
  29   -->
  30 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
  31
  32 <head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  33 <title>Frequently Asked Questions about GNU MPFR</title>
  34 <style type="text/css">/*<![CDATA[*/
  35 /* Global stylesheet for visual media */
  36
  37 html, body
  38 {
  39   background: white;
  40   color: black;
  41 }
  42
  43 div.logo { float: right }
  44 div.logo img { border: 0 }
  45
  46 div.footer img { border: 0 }
  47
  48 dt
  49 {
  50   margin-top: 2ex;
  51   margin-bottom: 1ex;
  52   font-weight: bolder;
  53 }
  54
  55 /* For testing: dd { background: #ddddff } */
  56
  57 table { margin: 0.5ex auto }
  58
  59 li { margin-top: 0.5ex; margin-bottom: 0.5ex }
  60
  61 dd + dd
  62 {
  63   margin-top: 0;
  64   margin-bottom: 0;
  65   padding-top: 0.5ex;
  66   padding-bottom: 0;
  67 }
  68
  69 li > p, dd > p
  70 {
  71   margin-top: 0;
  72   margin-bottom: 0;
  73   padding-top: 0.5ex;
  74   padding-bottom: 0.5ex;
  75 }
  76
  77 .block-code code, code.block-code,
  78 .block-code samp, samp.block-code
  79 {
  80   display: block;
  81   padding: 0.5ex 0;
  82   margin-left: 2em;
  83 }
  84
  85 .nowrap { white-space: nowrap }
  86
  87 /*
  88 dl.faq { counter-reset: faq }
  89
  90 dl.faq dt:before
  91 {
  92   counter-increment: faq;
  93   content: counter(faq) ". ";
  94 }
  95 */
  96
  97 dl.faq dt { background: #dddddd }
  98
  99 dl.faq dd
 100 {
 101   border-left: 4px solid;
 102   border-color: transparent;
 103   margin-left: 0em;
 104   padding-left: 1.5em;
 105 }
 106
 107 dl.faq dt:target + dd
 108 {
 109   border-left-color: #aaaaaa;
 110 }
 111
 112 var.env { font-style: normal }
 113 /*]]>*/</style>
 114 </head>
 115
 116 <body>
 117
 118 <h1>Frequently Asked Questions about <cite><acronym>GNU</acronym> <acronym>MPFR</acronym></cite></h1>
 119
 120 <p><strong>Important notice: Problems with a particular version of
 121 <cite><acronym>MPFR</acronym></cite> are discussed in the corresponding
 122 bugs page.</strong></p>
 123
 124 <p>The latest version of this <acronym>FAQ</acronym> is available at
 125 <a href="http://www.mpfr.org/faq.html">http://www.mpfr.org/faq.html</a>.
 126 Please look at this version if possible.</p>
 127
 128 <ol>
 129 <li><a href="#mpfr_vs_mpf">What are the differences between
 130 <cite><acronym>MPF</acronym></cite> from <cite><acronym>GMP</acronym></cite>
 131 and <cite><acronym>MPFR</acronym></cite>?</a></li>
 132 <li><a href="#mpf2mpfr">How to convert my program written using
 133 <cite><acronym>MPF</acronym></cite> to
 134 <cite><acronym>MPFR</acronym></cite>?</a></li>
 135 <li><a href="#no_libgmp">At configure time, I get the error: <q>libgmp not found or uses a different ABI.</q></a></li>
 136 <li><a href="#undef_ref1">I get undefined reference to <code>__gmp_get_memory_functions</code>.</a></li>
 137 <li><a href="#undef_ref2">When I link my program with
 138 <cite><acronym>MPFR</acronym></cite>, I get undefined reference
 139 to <code>__gmpXXXX</code>.</a></li>
 140 <li><a href="#crash_high_prec">My program crashes with high precisions.</a></li>
 141 <li><a href="#accuracy">Though I have increased the precision, the results
 142 are not more accurate.</a></li>
 143 <li><a href="#detect_mpfr">How can I detect <cite><acronym>MPFR</acronym></cite>
 144 installation using <cite>autoconf</cite> or <cite>pkg-config</cite>?</a></li>
 145 <li><a href="#cite">How to cite <cite><acronym>MPFR</acronym></cite> in a
 146 scientific publication?</a></li>
 147 <li><a href="#fpic">When I build <cite><acronym>MPFR</acronym></cite>, I get
 148 an error asking me to recompile with <samp>-fPIC</samp>.</a></li>
 149 </ol>
 150
 151 <dl class="faq">
 152
 153 <dt id="mpfr_vs_mpf">1. What are the differences between
 154 <cite><acronym>MPF</acronym></cite> from <cite><acronym>GMP</acronym></cite>
 155 and <cite><acronym>MPFR</acronym></cite>?</dt>
 156
 157 <dd><p>The main differences are:</p>
 158 <ul>
 159 <li><p>The precision of a <cite><acronym>MPFR</acronym></cite> variable
 160 is the <em>exact</em> number of bits used for its mantissa, whereas in
 161 <cite><acronym>MPF</acronym></cite>, the precision requested by the user
 162 is a minimum value (<cite><acronym>MPF</acronym></cite> generally uses a
 163 higher precision). With the additional difference below, this implies that
 164 the <cite><acronym>MPFR</acronym></cite> results do not depend on the
 165 number of bits (16, 32, 64 or more) of the underlying architecture.</p></li>
 166 <li><p>As a consequence, <cite><acronym>MPFR</acronym></cite> uses a
 167 base-2 exponent, whereas in <cite><acronym>MPF</acronym></cite>, this
 168 is a base-2<sup>32</sup> or base-2<sup>64</sup> exponent, depending on
 169 the limb size. For this reason (and other internal ones), the maximum
 170 exponent range in <cite><acronym>MPFR</acronym></cite> is different
 171 (and smaller, if the exponent is represented by the same type as in
 172 <cite><acronym>MPF</acronym></cite>).</p></li>
 173 <li><p><cite><acronym>MPFR</acronym></cite> provides an additional rounding
 174 mode argument to its functions; furthermore, it is guaranteed that the
 175 result of any operation is the nearest possible floating-point value from
 176 the exact result (considering the input variables as exact values), taking
 177 into account the precision of the destination variable and the rounding
 178 mode. <cite><acronym>MPFR</acronym></cite> also says whether the rounded
 179 result is above or below the exact result.</p></li>
 180 <li><p><cite><acronym>MPFR</acronym></cite> supports much more functions
 181 (in particular transcendental functions such as exponentials, logarithms,
 182 trigonometric functions and so on) and special values: signed zeros,
 183 infinities, not-a-number (NaN).</p></li>
 184 </ul></dd>
 185
 186 <dt id="mpf2mpfr">2. How to convert my program written using
 187 <cite><acronym>MPF</acronym></cite> to
 188 <cite><acronym>MPFR</acronym></cite>?</dt>
 189
 190 <dd><p>You need to add <q><code>r</code></q> to the function names, and to
 191 specify the rounding mode (<code>MPFR_RNDN</code> for rounding to nearest,
 192 <code>MPFR_RNDZ</code> for rounding towards zero, <code>MPFR_RNDU</code>
 193 for rounding towards plus infinity, <code>MPFR_RNDD</code> for rounding
 194 towards minus infinity). You can also define macros as follows:
 195 <code class="block-code">#define mpf_add(a, b, c) mpfr_add(a, b, c, MPFR_RNDN)</code></p>
 196 <p>The header file <samp>mpf2mpfr.h</samp> from the
 197 <cite><acronym>MPFR</acronym></cite> distribution automatically
 198 redefines all <cite><acronym>MPF</acronym></cite> functions in this
 199 way, using the default <cite><acronym>MPFR</acronym></cite> rounding
 200 mode. Thus you simply need to add the following line in all your files
 201 using <cite><acronym>MPF</acronym></cite> functions:
 202 <code class="block-code">#include &lt;mpf2mpfr.h&gt;</code>
 203 just after the <samp>gmp.h</samp> and <samp>mpfr.h</samp>
 204 header files. If the program uses <cite><acronym>MPF</acronym></cite>
 205 internals (such as direct access to <code>__mpf_struct</code> members),
 206 additional changes will be needed.</p></dd>
 207
 208 <dt id="no_libgmp">3. At configure time, I get the error: <q>libgmp not found or uses a different ABI.</q></dt>
 209
 210 <dd><p>This test (<samp>checking for __gmpz_init in -lgmp</samp>) comes
 211 after the <samp>gmp.h</samp> detection. The failure occurs either because
 212 the <cite><acronym>GMP</acronym></cite> library could not be found
 213 (as it is not in the provided library search paths) or because the
 214 <cite><acronym>GMP</acronym></cite> library that was found does not have
 215 the expected <acronym title="Application Binary Interface">ABI</acronym>
 216 (<abbr>e.g.</abbr> 32-bit <abbr>vs</abbr> 64-bit). The latter problem can
 217 have several causes:</p>
 218 <ul>
 219 <li>A wrong libgmp library has been picked up. This can occur if you have
 220 several <cite><acronym>GMP</acronym></cite> versions installed on the
 221 machine and something is wrong with the provided library search paths.</li>
 222 <li>Wrong compiler options (<samp>CFLAGS</samp>) were given. In general, the
 223 presence or absence of the <samp>-m64</samp> compiler option must match the
 224 library <acronym title="Application Binary Interface">ABI</acronym>.</li>
 225 <li>A wrong <samp>gmp.h</samp> file has been picked up (if you have several
 226 <cite><acronym>GMP</acronym></cite> versions installed). Indeed, by default,
 227 <cite><acronym>MPFR</acronym></cite> gets the compiler options from the
 228 <samp>gmp.h</samp> file (with <cite><acronym>GMP</acronym></cite> 4.2.3
 229 or later); this is needed because <cite><acronym>GMP</acronym></cite> does
 230 not necessarily use the default <acronym>ABI</acronym>. The consequence is
 231 that if the <samp>gmp.h</samp> file is associated with a library using a
 232 different <acronym>ABI</acronym>, the <acronym>ABI</acronym>-related options
 233 will be incorrect. Hence the failure.</li>
 234 </ul>
 235 <p>Note: The <samp>config.log</samp> output gives more information
 236 than the error message. In particular, see the output of the test:
 237 <samp>checking for CC and CFLAGS in gmp.h</samp>; it should give you
 238 the default compiler options (from <samp>gmp.h</samp>).</p>
 239
 240 <p>See also the answer to the <a href="#undef_ref1">next question</a>.</p></dd>
 241
 242 <dt id="undef_ref1">4. I get undefined reference to <code>__gmp_get_memory_functions</code>.</dt>
 243
 244 <dd><p>Note: this was mainly a problem when upgrading from
 245 <cite><acronym>GMP</acronym></cite> 4.1.4 to a later version,
 246 but information given below may still be useful in other cases,
 247 when several <cite><acronym>GMP</acronym></cite> libraries are
 248 installed on the same machine.</p>
 249
 250 <p>If you get such an error, in particular when running
 251 <samp>make check</samp>, then this probably means that you are using
 252 the header file from <cite><acronym>GMP</acronym></cite> 4.2.x but the
 253 <cite><acronym>GMP</acronym></cite> 4.1.4 library. This can happen if
 254 several <cite><acronym>GMP</acronym></cite> versions are installed on
 255 your machine (<abbr>e.g.</abbr>, one provided by the system in
 256 <samp>/usr/{include,lib}</samp> and a new one installed by the owner or
 257 administrator of the machine in <samp>/usr/local/{include,lib}</samp>)
 258 and your include and library search paths are inconsistent. On various
 259 <acronym>GNU</acronym>/Linux machines, this is unfortunately the case
 260 by default (<samp>/usr/local/include</samp> is in the default include
 261 search path, but <samp>/usr/local/lib</samp> is <em>not</em> in the
 262 default library search path). Typical errors are:
 263 <samp class="block-code">undefined reference to `__gmp_get_memory_functions'</samp>
 264 in <samp>make check</samp>. The best solution is to add
 265 <samp>/usr/local/include</samp> to your <var class="env">C_INCLUDE_PATH</var>
 266 environment variable and to add <samp>/usr/local/lib</samp> to your
 267 <var class="env">LIBRARY_PATH</var> and <var class="env">LD_LIBRARY_PATH</var>
 268 environment variables (and/or <var class="env">LD_RUN_PATH</var>).
 269 Alternatively, you can use <samp>--with-gmp*</samp> configure options,
 270 <abbr>e.g.</abbr> <samp>--with-gmp=/usr/local</samp>, but <strong>this is
 271 not guaranteed to work</strong> (in particular with <samp>gcc</samp> and
 272 system directories such as <samp>/usr</samp> or <samp>/usr/local</samp>),
 273 and other software that uses <cite><acronym>GMP</acronym></cite> and/or
 274 <cite><acronym>MPFR</acronym></cite> will need correct paths too;
 275 environment variables allow you to set them in a global way.</p>
 276 <p>Other information can be given in the <samp>INSTALL</samp> file and
 277 <samp>ld</samp> manual. Please look at them for more details. See also
 278 the <a href="#undef_ref2">next question</a>.</p></dd>
 279
 280 <dt id="undef_ref2">5. When I link my program with
 281 <cite><acronym>MPFR</acronym></cite>, I get undefined reference
 282 to <code>__gmpXXXX</code>.</dt>
 283
 284 <dd><p>Link your program with <cite><acronym>GMP</acronym></cite>. Assuming
 285 that your program is <samp>foo.c</samp>, you should link it using:
 286 <samp class="block-code">cc link.c -lmpfr -lgmp</samp>
 287 <cite><acronym>MPFR</acronym></cite> library reference (<samp>-lmpfr</samp>)
 288 should be before <cite><acronym>GMP</acronym></cite>'s one
 289 (<samp>-lgmp</samp>). Another solution is, with <acronym>GNU</acronym>
 290 <samp>ld</samp>, to give all the libraries inside a group:
 291 <samp class="block-code">gcc link.c -Wl,--start-group libgmp.a libmpfr.a -Wl,--end-group</samp>
 292 See <samp>INSTALL</samp> file and <samp>ld</samp> manual for more
 293 details.</p>
 294 <p>If you used correct link options, but still get an error, this may mean
 295 that your include and library search paths are inconsistent. Please see the
 296 <a href="#undef_ref1">previous question</a>.</p></dd>
 297
 298 <dt id="crash_high_prec">6. My program crashes with high precisions.</dt>
 299
 300 <dd><p>Your stack size limit may be too small; indeed, by default,
 301 <cite><acronym>GMP</acronym></cite> 4.1.4 and below allocates all
 302 temporary results on the stack, and in very high precisions, this
 303 limit may be reached. You can solve this problem in different ways:</p>
 304 <ul>
 305 <li><p>You can upgrade to <cite><acronym>GMP</acronym></cite> 4.2 (or above),
 306 which now makes temporary allocations on the stack only when they are
 307 small.</p></li>
 308 <li><p>You can increase the stack size limit with the <samp>limit</samp>,
 309 <samp>unlimit</samp> or <samp>ulimit</samp> command, depending on your
 310 shell. This may fail on some systems, where the maximum stack size cannot
 311 be increased above some value.</p></li>
 312 <li><p>You can rebuild both <cite><acronym>GMP</acronym></cite> and
 313 <cite><acronym>MPFR</acronym></cite> to use another allocation method.</p></li>
 314 </ul></dd>
 315
 316 <dt id="accuracy">7. Though I have increased the precision, the results
 317 are not more accurate.</dt>
 318
 319 <dd><p>The reason may be the use of C floating-point numbers. If you want
 320 to store a floating-point constant to a <code>mpfr_t</code>, you should use
 321 <code>mpfr_set_str</code> (or one of the <cite><acronym>MPFR</acronym></cite>
 322 constant functions, such as <code>mpfr_const_pi</code> for &#960;) instead
 323 of <code>mpfr_set_d</code> or <code>mpfr_set_ld</code>. Otherwise the
 324 floating-point constant will be first converted into a reduced-precision
 325 (<abbr>e.g.</abbr>, 53-bit) binary number before
 326 <cite><acronym>MPFR</acronym></cite> can work with it. This is the case
 327 in particular for most exact decimal numbers, such as 0.17, which are
 328 not exactly representable in binary.</p>
 329 <p>Also remember that <cite><acronym>MPFR</acronym></cite> does not track
 330 the accuracy of the results: copying a value <var>x</var> to <var>y</var>
 331 with <code>mpfr_set (y, x, MPFR_RNDN)</code> where the variable <var>y</var>
 332 is more precise than the variable <var>x</var> will not make it more
 333 accurate; the (binary) value will remain unchanged.</p></dd>
 334
 335 <dt id="detect_mpfr">8. How can I detect <cite><acronym>MPFR</acronym></cite>
 336 installation using <cite>autoconf</cite> or <cite>pkg-config</cite>?</dt>
 337
 338 <dd><p>The <cite><acronym>MPFR</acronym></cite> team does not currently
 339 recommend any <cite>autoconf</cite> code, but a section will later
 340 be added to the <cite><acronym>MPFR</acronym></cite> manual. The
 341 <cite><acronym>MPFR</acronym></cite> team does not wish to support
 342 <cite>pkg-config</cite> yet.</p></dd>
 343
 344 <dt id="cite">9. How to cite <cite><acronym>MPFR</acronym></cite> in a
 345 scientific publication?</dt>
 346
 347 <dd><p>To properly cite <cite><acronym>MPFR</acronym></cite> in a scientific
 348 publication, please cite the
 349 <a href="http://doi.acm.org/10.1145/1236463.1236468"><acronym title="Association for Computing Machinery">ACM</acronym>
 350 <acronym title="Transactions on Mathematical Software">TOMS</acronym>
 351 paper</a>
 352 (<a href="http://toms.acm.org/cgi/TOMSbibget.cgi?Fousse:2007:MMP">BibTeX</a>)
 353 and/or the library web page
 354 <a href="http://www.mpfr.org/">http://www.mpfr.org</a>. If your publication
 355 is related to a particular release of <cite><acronym>MPFR</acronym></cite>,
 356 for example if you report timings, please also indicate the release number
 357 for future reference.</p></dd>
 358
 359 <dt id="fpic">10. When I build <cite><acronym>MPFR</acronym></cite>, I get
 360 an error asking me to recompile with <samp>-fPIC</samp>.</dt>
 361
 362 <dd><p>A typical error looks like:</p>
 363 <p><tt>/usr/bin/ld: <em>/path/to/</em>libgmp.a(realloc.o): relocation
 364 R_X86_64_32 against `.rodata.str1.1' can not be used when making a
 365 shared object; recompile with -fPIC<br />
 366 <em>/path/to/</em>libgmp.a: could not read symbols: Bad value<br />
 367 collect2: ld returned 1 exit status</tt></p>
 368 <p>The probable reason is that you tried to build
 369 <cite><acronym>MPFR</acronym></cite> with the shared library enabled (this
 370 is the default), while only a static <cite><acronym>GMP</acronym></cite>
 371 library could be found. To solve this problem, either rebuild and reinstall
 372 <cite><acronym>GMP</acronym></cite> without the <samp>--disable-shared</samp>
 373 configure option, or configure <cite><acronym>MPFR</acronym></cite> with
 374 <samp>--disable-shared</samp>. If you did this and still get the above
 375 error, the cause may be conflicting <cite><acronym>GMP</acronym></cite>
 376 versions installed on your system; please check that your search path
 377 settings are correct.</p>
 378 <p>Additional note about the last sentence: Under <acronym>GNU</acronym>/Linux
 379 (for instance), the linker takes the first library found in the library search
 380 path, whether it is dynamic or static. The default behavior under darwin is
 381 different, but <cite><acronym>MPFR</acronym></cite> will change it.</p></dd>
 382 <!-- Reference concerning darwin: see MPFR_LD_SEARCH_PATHS_FIRST
 383      in MPFR's configure.{ac,in} and acinclude.m4 -->
 384
 385 </dl>
 386
 387 </body>
 388
 389 </html>