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.\" See above for rationale for this date. 32.Dd September 7, 1989 33.Dt LIBMP 3 34.Os 35.Sh NAME 36.Nm libmp 37.Nd traditional BSD multiple precision integer arithmetic library 38.Sh SYNOPSIS 39.In mp.h 40.Pp 41Function prototypes are given in the main body of the text. 42.Pp 43Applications using this interface must be linked with 44.Fl l Ns Ar mp 45(this library) 46and 47.Fl l Ns Ar crypto 48.Pq Xr crypto 3 . 49.Sh DESCRIPTION 50.Bf -symbolic 51This interface is obsolete in favor of the 52.Xr crypto 3 53.Vt BIGNUM 54library. 55.Ef 56.Pp 57.Nm 58is the traditional 59.Bx 60multiple precision integer arithmetic library. 61It has a number of problems, 62and is unsuitable for use in any programs where reliability is a concern. 63It is provided here for compatibility only. 64.Pp 65These routines perform arithmetic on integers of arbitrary precision 66stored using the defined type 67.Vt MINT . 68Pointers to 69.Vt MINT 70are initialized using 71.Fn mp_itom 72or 73.Fn mp_xtom , 74and must be recycled with 75.Fn mp_mfree 76when they are no longer needed. 77Routines which store a result in one of their arguments expect that 78the latter has also been initialized prior to being passed to it. 79The following routines are defined and implemented: 80.Pp 81.Ft "MINT *" Ns 82.Fn mp_itom "short n" ; 83.Pp 84.Ft "MINT *" Ns 85.Fn mp_xtom "const char *s" ; 86.Pp 87.Ft "char *" Ns 88.Fn mp_mtox "const MINT *mp" ; 89.Pp 90.Ft void 91.Fn mp_mfree "MINT *mp" ; 92.Bd -ragged -offset indent 93.Fn mp_itom 94returns an 95.Vt MINT 96with the value of 97.Fa n . 98.Fn mp_xtom 99returns an 100.Vt MINT 101with the value of 102.Fa s , 103which is treated to be in hexadecimal. 104The return values from 105.Fn mp_itom 106and 107.Fn mp_xtom 108must be released with 109.Fn mp_mfree 110when they are no longer needed. 111.Fn mp_mtox 112returns a null-terminated hexadecimal string having the value of 113.Fa mp ; 114its return value must be released with 115.Fn free 116.Pq Xr free 3 117when it is no longer needed. 118.Ed 119.Pp 120.Ft void 121.Fn mp_madd "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ; 122.Pp 123.Ft void 124.Fn mp_msub "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ; 125.Pp 126.Ft void 127.Fn mp_mult "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ; 128.Bd -ragged -offset indent 129.Fn mp_madd , 130.Fn mp_msub , 131and 132.Fn mp_mult 133store the sum, difference, or product, respectively, of 134.Fa mp1 135and 136.Fa mp2 137in 138.Fa rmp . 139.Ed 140.Pp 141.Ft void 142.Fn mp_mdiv "const MINT *nmp" "const MINT *dmp" "MINT *qmp" "MINT *rmp" ; 143.Pp 144.Ft void 145.Fn mp_sdiv "const MINT *nmp" "short d" "MINT *qmp" "short *ro" ; 146.Bd -ragged -offset indent 147.Fn mp_mdiv 148computes the quotient and remainder of 149.Fa nmp 150and 151.Fa dmp 152and stores the result in 153.Fa qmp 154and 155.Fa rmp , 156respectively. 157.Fn mp_sdiv 158is similar to 159.Fn mp_mdiv 160except the divisor 161.Fa ( dmp 162or 163.Fa d ) 164and remainder 165.Fa ( rmp 166or 167.Fa ro ) 168are ordinary integers. 169.Ed 170.Pp 171.Ft void 172.Fn mp_pow "const MINT *bmp" "const MINT *emp" "const MINT *mmp" "MINT *rmp" ; 173.Pp 174.Ft void 175.Fn mp_rpow "const MINT *bmp" "short e" "MINT *rmp" ; 176.Bd -ragged -offset indent 177.Fn mp_rpow 178computes the result of 179.Fa bmp 180raised to the 181.Fa emp Ns th 182power and reduced modulo 183.Fa mmp ; 184the result is stored in 185.Fa rmp . 186.Fn mp_pow 187computes the result of 188.Fa bmp 189raised to the 190.Fa e Ns th 191power and stores the result in 192.Fa rmp . 193.Ed 194.Pp 195.Ft void 196.Fn mp_min "MINT *mp" ; 197.Pp 198.Ft void 199.Fn mp_mout "const MINT *mp" ; 200.Bd -ragged -offset indent 201.Fn mp_min 202reads a line from standard input, tries to interpret it as a decimal 203number, and if successful, stores the result in 204.Fa mp . 205.Fn mp_mout 206prints the value, in decimal, of 207.Fa mp 208to standard output (without a trailing newline). 209.Ed 210.Pp 211.Ft void 212.Fn mp_gcd "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ; 213.Bd -ragged -offset indent 214.Fn mp_gcd 215computes the greatest common divisor of 216.Fa mp1 217and 218.Fa mp2 219and stores the result in 220.Fa rmp . 221.Ed 222.Pp 223.Ft int 224.Fn mp_mcmp "const MINT *mp1" "const MINT *mp2" ; 225.Bd -ragged -offset indent 226.Fa mcmp 227compares the values of 228.Fa mp1 229and 230.Fa mp2 231and returns 2320 if the two values are equal, 233a value greater than 0 if 234.Fa mp1 235is greater than 236.Fa mp2 , 237and a value less than 0 if 238.Fa mp2 239is greater than 240.Fa mp1 . 241.Ed 242.Pp 243.Ft void 244.Fn mp_move "const MINT *smp" "MINT *tmp" ; 245.Bd -ragged -offset indent 246.Fn mp_move 247copies the value of 248.Fa smp 249to 250.Fa tmp 251(both values must be initialized). 252.Ed 253.Pp 254.Ft void 255.Fn mp_msqrt "const MINT *nmp" "MINT *xmp" "MINT *rmp" ; 256.Bd -ragged -offset indent 257.Fn mp_msqrt 258computes the square root and remainder of 259.Fa nmp 260and stores them in 261.Fa xmp 262and 263.Fa rmp , 264respectively. 265.Ed 266.Sh IMPLEMENTATION NOTES 267This version of 268.Nm 269is implemented in terms of the 270.Xr crypto 3 271.Vt BIGNUM 272library. 273.Sh DIAGNOSTICS 274Running out of memory or illegal operations result in error messages 275on standard error and a call to 276.Xr abort 3 . 277.Sh SEE ALSO 278.Xr abort 3 , 279.Xr bn 3 , 280.Xr crypto 3 , 281.Xr free 3 , 282.Xr malloc 3 , 283.Xr math 3 284.Sh HISTORY 285A 286.Nm 287library appeared in 288.Bx 4.3 . 289.Fx 2.2 290shipped with a 291.Nm 292implemented in terms of 293.Nm libgmp . 294This implementation appeared in 295.Fx 5.0 . 296.Sh BUGS 297Errors are reported via output to standard error and abnormal 298program termination instead of via return values. 299The application cannot control this behavior. 300.Pp 301It is not clear whether the string returned by 302.Fn mp_mtox 303may be written to by the caller. 304This implementation allows it, but others may not. 305Ideally, 306.Fn mp_mtox 307would take a pointer to a buffer to fill in. 308.Pp 309It is not clear whether using the same variable as both source and 310destination in a single invocation is permitted. 311Some of the calls in this implementation allow this, while others 312do not. 313