lib/libmp/libmp.3

   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
  41 Function prototypes are given in the main body of the text.
  42 .Pp
  43 Applications using this interface must be linked with
  44 .Fl l Ns Ar mp
  45 (this library)
  46 and
  47 .Fl l Ns Ar crypto
  48 .Pq Xr crypto 3 .
  49 .Sh DESCRIPTION
  50 .Bf -symbolic
  51 This interface is obsolete in favor of the
  52 .Xr crypto 3
  53 .Vt BIGNUM
  54 library.
  55 .Ef
  56 .Pp
  57 .Nm
  58 is the traditional
  59 .Bx
  60 multiple precision integer arithmetic library.
  61 It has a number of problems,
  62 and is unsuitable for use in any programs where reliability is a concern.
  63 It is provided here for compatibility only.
  64 .Pp
  65 These routines perform arithmetic on integers of arbitrary precision
  66 stored using the defined type
  67 .Vt MINT .
  68 Pointers to
  69 .Vt MINT
  70 are initialized using
  71 .Fn mp_itom
  72 or
  73 .Fn mp_xtom ,
  74 and must be recycled with
  75 .Fn mp_mfree
  76 when they are no longer needed.
  77 Routines which store a result in one of their arguments expect that
  78 the latter has also been initialized prior to being passed to it.
  79 The 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
  94 returns an
  95 .Vt MINT
  96 with the value of
  97 .Fa n .
  98 .Fn mp_xtom
  99 returns an
 100 .Vt MINT
 101 with the value of
 102 .Fa s ,
 103 which is treated to be in hexadecimal.
 104 The return values from
 105 .Fn mp_itom
 106 and
 107 .Fn mp_xtom
 108 must be released with
 109 .Fn mp_mfree
 110 when they are no longer needed.
 111 .Fn mp_mtox
 112 returns a null-terminated hexadecimal string having the value of
 113 .Fa mp ;
 114 its return value must be released with
 115 .Fn free
 116 .Pq Xr free 3
 117 when 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 ,
 131 and
 132 .Fn mp_mult
 133 store the sum, difference, or product, respectively, of
 134 .Fa mp1
 135 and
 136 .Fa mp2
 137 in
 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
 148 computes the quotient and remainder of
 149 .Fa nmp
 150 and
 151 .Fa dmp
 152 and stores the result in
 153 .Fa qmp
 154 and
 155 .Fa rmp ,
 156 respectively.
 157 .Fn mp_sdiv
 158 is similar to
 159 .Fn mp_mdiv
 160 except the divisor
 161 .Fa ( dmp
 162 or
 163 .Fa d )
 164 and remainder
 165 .Fa ( rmp
 166 or
 167 .Fa ro )
 168 are 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
 178 computes the result of
 179 .Fa bmp
 180 raised to the
 181 .Fa emp Ns th
 182 power and reduced modulo
 183 .Fa mmp ;
 184 the result is stored in
 185 .Fa rmp .
 186 .Fn mp_pow
 187 computes the result of
 188 .Fa bmp
 189 raised to the
 190 .Fa e Ns th
 191 power 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
 202 reads a line from standard input, tries to interpret it as a decimal
 203 number, and if successful, stores the result in
 204 .Fa mp .
 205 .Fn mp_mout
 206 prints the value, in decimal, of
 207 .Fa mp
 208 to 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
 215 computes the greatest common divisor of
 216 .Fa mp1
 217 and
 218 .Fa mp2
 219 and 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
 227 compares the values of
 228 .Fa mp1
 229 and
 230 .Fa mp2
 231 and returns
 232 0 if the two values are equal,
 233 a value greater than 0 if
 234 .Fa mp1
 235 is greater than
 236 .Fa mp2 ,
 237 and a value less than 0 if
 238 .Fa mp2
 239 is 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
 247 copies the value of
 248 .Fa smp
 249 to
 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
 258 computes the square root and remainder of
 259 .Fa nmp
 260 and stores them in
 261 .Fa xmp
 262 and
 263 .Fa rmp ,
 264 respectively.
 265 .Ed
 266 .Sh IMPLEMENTATION NOTES
 267 This version of
 268 .Nm
 269 is implemented in terms of the
 270 .Xr crypto 3
 271 .Vt BIGNUM
 272 library.
 273 .Sh DIAGNOSTICS
 274 Running out of memory or illegal operations result in error messages
 275 on 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
 285 A
 286 .Nm
 287 library appeared in
 288 .Bx 4.3 .
 289 .Fx 2.2
 290 shipped with a
 291 .Nm
 292 implemented in terms of
 293 .Nm libgmp .
 294 This implementation appeared in
 295 .Fx 5.0 .
 296 .Sh BUGS
 297 Errors are reported via output to standard error and abnormal
 298 program termination instead of via return values.
 299 The application cannot control this behavior.
 300 .Pp
 301 It is not clear whether the string returned by
 302 .Fn mp_mtox
 303 may be written to by the caller.
 304 This implementation allows it, but others may not.
 305 Ideally,
 306 .Fn mp_mtox
 307 would take a pointer to a buffer to fill in.
 308 .Pp
 309 It is not clear whether using the same variable as both source and
 310 destination in a single invocation is permitted.
 311 Some of the calls in this implementation allow this, while others
 312 do not.