1.\" 2.\" Copyright (c) 2001 Dima Dorfman. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" This manual page is based on the mp(3X) manual page from Sun Release 27.\" 4.1, dated 7 September 1989. It's an old, crufty, and relatively ugly 28.\" manual page, but it does document what appears to be the "traditional" 29.\" libmp interface. 30.\" 31.\" $FreeBSD$ 32.\" 33.\" See above for rationale for this date. 34.Dd September 7, 1989 35.Dt LIBMP 3 36.Os 37.Sh NAME 38.Nm libmp 39.Nd traditional BSD multiple precision integer arithmetic library 40.Sh SYNOPSIS 41.In mp.h 42.Pp 43Function prototypes are given in the main body of the text. 44.Pp 45Applications using this interface must be linked with 46.Fl l Ns Ar mp 47(this library) 48and 49.Fl l Ns Ar crypto 50.Pq Xr crypto 3 . 51.Sh DESCRIPTION 52.Bf -symbolic 53This interface is obsolete in favor of the 54.Xr crypto 3 55.Vt BIGNUM 56library. 57.Ef 58.Pp 59.Nm 60is the traditional 61.Bx 62multiple precision integer arithmetic library. 63It has a number of problems, 64and is unsuitable for use in any programs where reliability is a concern. 65It is provided here for compatibility only. 66.Pp 67These routines perform arithmetic on integers of arbitrary precision 68stored using the defined type 69.Vt MINT . 70Pointers to 71.Vt MINT 72are initialized using 73.Fn mp_itom 74or 75.Fn mp_xtom , 76and must be recycled with 77.Fn mp_mfree 78when they are no longer needed. 79Routines which store a result in one of their arguments expect that 80the latter has also been initialized prior to being passed to it. 81The following routines are defined and implemented: 82.Pp 83.Ft "MINT *" Ns 84.Fn mp_itom "short n" ; 85.Pp 86.Ft "MINT *" Ns 87.Fn mp_xtom "const char *s" ; 88.Pp 89.Ft "char *" Ns 90.Fn mp_mtox "const MINT *mp" ; 91.Pp 92.Ft void 93.Fn mp_mfree "MINT *mp" ; 94.Bd -ragged -offset indent 95.Fn mp_itom 96returns an 97.Vt MINT 98with the value of 99.Fa n . 100.Fn mp_xtom 101returns an 102.Vt MINT 103with the value of 104.Fa s , 105which is treated to be in hexadecimal. 106The return values from 107.Fn mp_itom 108and 109.Fn mp_xtom 110must be released with 111.Fn mp_mfree 112when they are no longer needed. 113.Fn mp_mtox 114returns a null-terminated hexadecimal string having the value of 115.Fa mp ; 116its return value must be released with 117.Fn free 118.Pq Xr free 3 119when it is no longer needed. 120.Ed 121.Pp 122.Ft void 123.Fn mp_madd "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ; 124.Pp 125.Ft void 126.Fn mp_msub "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ; 127.Pp 128.Ft void 129.Fn mp_mult "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ; 130.Bd -ragged -offset indent 131.Fn mp_madd , 132.Fn mp_msub , 133and 134.Fn mp_mult 135store the sum, difference, or product, respectively, of 136.Fa mp1 137and 138.Fa mp2 139in 140.Fa rmp . 141.Ed 142.Pp 143.Ft void 144.Fn mp_mdiv "const MINT *nmp" "const MINT *dmp" "MINT *qmp" "MINT *rmp" ; 145.Pp 146.Ft void 147.Fn mp_sdiv "const MINT *nmp" "short d" "MINT *qmp" "short *ro" ; 148.Bd -ragged -offset indent 149.Fn mp_mdiv 150computes the quotient and remainder of 151.Fa nmp 152and 153.Fa dmp 154and stores the result in 155.Fa qmp 156and 157.Fa rmp , 158respectively. 159.Fn mp_sdiv 160is similar to 161.Fn mp_mdiv 162except the divisor 163.Fa ( dmp 164or 165.Fa d ) 166and remainder 167.Fa ( rmp 168or 169.Fa ro ) 170are ordinary integers. 171.Ed 172.Pp 173.Ft void 174.Fn mp_pow "const MINT *bmp" "const MINT *emp" "const MINT *mmp" "MINT *rmp" ; 175.Pp 176.Ft void 177.Fn mp_rpow "const MINT *bmp" "short e" "MINT *rmp" ; 178.Bd -ragged -offset indent 179.Fn mp_rpow 180computes the result of 181.Fa bmp 182raised to the 183.Fa emp Ns th 184power and reduced modulo 185.Fa mmp ; 186the result is stored in 187.Fa rmp . 188.Fn mp_pow 189computes the result of 190.Fa bmp 191raised to the 192.Fa e Ns th 193power and stores the result in 194.Fa rmp . 195.Ed 196.Pp 197.Ft void 198.Fn mp_min "MINT *mp" ; 199.Pp 200.Ft void 201.Fn mp_mout "const MINT *mp" ; 202.Bd -ragged -offset indent 203.Fn mp_min 204reads a line from standard input, tries to interpret it as a decimal 205number, and if successful, stores the result in 206.Fa mp . 207.Fn mp_mout 208prints the value, in decimal, of 209.Fa mp 210to standard output (without a trailing newline). 211.Ed 212.Pp 213.Ft void 214.Fn mp_gcd "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ; 215.Bd -ragged -offset indent 216.Fn mp_gcd 217computes the greatest common divisor of 218.Fa mp1 219and 220.Fa mp2 221and stores the result in 222.Fa rmp . 223.Ed 224.Pp 225.Ft int 226.Fn mp_mcmp "const MINT *mp1" "const MINT *mp2" ; 227.Bd -ragged -offset indent 228.Fa mcmp 229compares the values of 230.Fa mp1 231and 232.Fa mp2 233and returns 2340 if the two values are equal, 235a value greater than 0 if 236.Fa mp1 237is greater than 238.Fa mp2 , 239and a value less than 0 if 240.Fa mp2 241is greater than 242.Fa mp1 . 243.Ed 244.Pp 245.Ft void 246.Fn mp_move "const MINT *smp" "MINT *tmp" ; 247.Bd -ragged -offset indent 248.Fn mp_move 249copies the value of 250.Fa smp 251to 252.Fa tmp 253(both values must be initialized). 254.Ed 255.Pp 256.Ft void 257.Fn mp_msqrt "const MINT *nmp" "MINT *xmp" "MINT *rmp" ; 258.Bd -ragged -offset indent 259.Fn mp_msqrt 260computes the square root and remainder of 261.Fa nmp 262and stores them in 263.Fa xmp 264and 265.Fa rmp , 266respectively. 267.Ed 268.Sh IMPLEMENTATION NOTES 269This version of 270.Nm 271is implemented in terms of the 272.Xr crypto 3 273.Vt BIGNUM 274library. 275.Sh DIAGNOSTICS 276Running out of memory or illegal operations result in error messages 277on standard error and a call to 278.Xr abort 3 . 279.Sh SEE ALSO 280.Xr abort 3 , 281.Xr bn 3 , 282.Xr crypto 3 , 283.Xr free 3 , 284.Xr malloc 3 , 285.Xr math 3 286.Sh HISTORY 287A 288.Nm 289library appeared in 290.Bx 4.3 . 291.Fx 2.2 292shipped with a 293.Nm 294implemented in terms of 295.Nm libgmp . 296This implementation appeared in 297.Fx 5.0 . 298.Sh BUGS 299Errors are reported via output to standard error and abnormal 300program termination instead of via return values. 301The application cannot control this behavior. 302.Pp 303It is not clear whether the string returned by 304.Fn mp_mtox 305may be written to by the caller. 306This implementation allows it, but others may not. 307Ideally, 308.Fn mp_mtox 309would take a pointer to a buffer to fill in. 310.Pp 311It is not clear whether using the same variable as both source and 312destination in a single invocation is permitted. 313Some of the calls in this implementation allow this, while others 314do not. 315