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