322 lines
6.9 KiB
Groff
322 lines
6.9 KiB
Groff
.\"
|
|
.\" Copyright (c) 2001 Dima Dorfman.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" This manual page is based on the mp(3X) manual page from Sun Release
|
|
.\" 4.1, dated 7 September 1989. It's an old, crufty, and relatively ugly
|
|
.\" manual page, but it does document what appears to be the "traditional"
|
|
.\" libmp interface.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.\" See above for rationale for this date.
|
|
.Dd September 7, 1989
|
|
.Dt MP 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm libmp
|
|
.Nd traditional BSD multiple precision integer arithmetic library
|
|
.Sh SYNOPSIS
|
|
.In mp.h
|
|
.Pp
|
|
Function prototypes are given in the main body of the text.
|
|
.Pp
|
|
Applications using this interface must be linked with
|
|
.Fl l Ns Ar mp
|
|
(this library)
|
|
and
|
|
.Fl l Ns Ar crypto
|
|
.Pq Xr crypto 3 .
|
|
.Sh DESCRIPTION
|
|
.Bf -symbolic
|
|
This interface is obsolete in favor of the
|
|
.Xr crypto 3
|
|
.Vt BIGNUM
|
|
library.
|
|
.Ef
|
|
.Pp
|
|
.Nm
|
|
is the traditional
|
|
.Bx
|
|
multiple precision integer arithmetic library.
|
|
It has a number of problems,
|
|
and is unsuitable for use in any programs where reliability is a concern.
|
|
It is provided here for compatibility only.
|
|
.Pp
|
|
These routines perform arithmetic on integers of arbitrary precision
|
|
stored using the defined type
|
|
.Vt MINT .
|
|
Pointers to
|
|
.Vt MINT
|
|
are initialized using
|
|
.Fn itom
|
|
or
|
|
.Fn xtom ,
|
|
and must be recycled with
|
|
.Fn mfree
|
|
when they are no longer needed.
|
|
Routines which store a result in one of their arguments expect that
|
|
the latter has also been initialized prior to being passed to it.
|
|
The following routines are defined and implemented:
|
|
.Pp
|
|
.Ft "MINT *" Ns
|
|
.Fn itom "short n" ;
|
|
.Pp
|
|
.Ft "MINT *" Ns
|
|
.Fn xtom "const char *s" ;
|
|
.Pp
|
|
.Ft "char *" Ns
|
|
.Fn mtox "const MINT *mp" ;
|
|
.Pp
|
|
.Ft void
|
|
.Fn mfree "MINT *mp" ;
|
|
.Bd -ragged -offset indent
|
|
.Fn itom
|
|
returns an
|
|
.Vt MINT
|
|
with the value of
|
|
.Fa n .
|
|
.Fn xtom
|
|
returns an
|
|
.Vt MINT
|
|
with the value of
|
|
.Fa s ,
|
|
which is treated to be in hexadecimal.
|
|
The return values from
|
|
.Fn itom
|
|
and
|
|
.Fn xtom
|
|
must be released with
|
|
.Fn mfree
|
|
when they are no longer needed.
|
|
.Fn mtox
|
|
returns a null-terminated hexadecimal string having the value of
|
|
.Fa mp ;
|
|
its return value must be released with
|
|
.Fn free
|
|
.Pq Xr free 3
|
|
when it is no longer needed.
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn madd "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ;
|
|
.Pp
|
|
.Ft void
|
|
.Fn msub "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ;
|
|
.Pp
|
|
.Ft void
|
|
.Fn mult "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ;
|
|
.Bd -ragged -offset indent
|
|
.Fn madd ,
|
|
.Fn msub ,
|
|
and
|
|
.Fn mult
|
|
store the sum, difference, or product, respectively, of
|
|
.Fa mp1
|
|
and
|
|
.Fa mp2
|
|
in
|
|
.Fa rmp .
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn mdiv "const MINT *nmp" "const MINT *dmp" "MINT *qmp" "MINT *rmp" ;
|
|
.Pp
|
|
.Ft void
|
|
.Fn sdiv "const MINT *nmp" "short d" "MINT *qmp" "short *ro" ;
|
|
.Bd -ragged -offset indent
|
|
.Fn mdiv
|
|
computes the quotient and remainder of
|
|
.Fa nmp
|
|
and
|
|
.Fa dmp
|
|
and stores the result in
|
|
.Fa qmp
|
|
and
|
|
.Fa rmp ,
|
|
respectively.
|
|
.Fn sdiv
|
|
is similar to
|
|
.Fn mdiv
|
|
except the divisor
|
|
.Fa ( dmp
|
|
or
|
|
.Fa d )
|
|
and remainder
|
|
.Fa ( rmp
|
|
or
|
|
.Fa ro )
|
|
are ordinary integers.
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn pow "const MINT *bmp" "const MINT *emp" "const MINT *mmp" "MINT *rmp" ;
|
|
.Pp
|
|
.Ft void
|
|
.Fn pow "const MINT *bmp" "short e" "MINT *rmp" ;
|
|
.Bd -ragged -offset indent
|
|
.Fn rpow
|
|
computes the result of
|
|
.Fa bmp
|
|
raised to the
|
|
.Fa emp Ns th
|
|
power and reduced modulo
|
|
.Fa mmp ;
|
|
the result is stored in
|
|
.Fa rmp .
|
|
.Fn pow
|
|
computes the result of
|
|
.Fa bmp
|
|
raised to the
|
|
.Fa e Ns th
|
|
power and stores the result in
|
|
.Fa rmp .
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn min "MINT *mp" ;
|
|
.Pp
|
|
.Ft void
|
|
.Fn mout "const MINT *mp" ;
|
|
.Bd -ragged -offset indent
|
|
.Fn min
|
|
reads a line from standard input, tries to interpret it as a decimal
|
|
number, and if successful, stores the result in
|
|
.Fa mp .
|
|
.Fn mout
|
|
prints the value, in decimal, of
|
|
.Fa mp
|
|
to standard output (without a trailing newline).
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn gcd "const MINT *mp1" "const MINT *mp2" "MINT *rmp" ;
|
|
.Bd -ragged -offset indent
|
|
.Fn gcd
|
|
computes the greatest common divisor of
|
|
.Fa mp1
|
|
and
|
|
.Fa mp2
|
|
and stores the result in
|
|
.Fa rmp .
|
|
.Ed
|
|
.Pp
|
|
.Ft int
|
|
.Fn mcmp "const MINT *mp1" "const MINT *mp2" ;
|
|
.Bd -ragged -offset indent
|
|
.Fa mcmp
|
|
compares the values of
|
|
.Fa mp1
|
|
and
|
|
.Fa mp2
|
|
and returns
|
|
0 if the two values are equal,
|
|
a value greater than 0 if
|
|
.Fa mp1
|
|
is greater than
|
|
.Fa mp2 ,
|
|
and a value less than 0 if
|
|
.Fa mp2
|
|
is greater than
|
|
.Fa mp1 .
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn move "const MINT *smp" "MINT *tmp" ;
|
|
.Bd -ragged -offset indent
|
|
.Fn move
|
|
copies the value of
|
|
.Fa smp
|
|
to
|
|
.Fa tmp
|
|
(both values must be initialized).
|
|
.Ed
|
|
.Pp
|
|
.Ft void
|
|
.Fn msqrt "const MINT *nmp" "MINT *xmp" "MINT *rmp" ;
|
|
.Bd -ragged -offset indent
|
|
.Fn msqrt
|
|
computes the square root and remainder of
|
|
.Fa nmp
|
|
and stores them in
|
|
.Fa xmp
|
|
and
|
|
.Fa rmp ,
|
|
respectively.
|
|
.Ed
|
|
.Sh IMPLEMENTATION NOTES
|
|
This version of
|
|
.Nm
|
|
is implemented in terms of the
|
|
.Xr crypto 3
|
|
.Vt BIGNUM
|
|
library.
|
|
.Sh DIAGNOSTICS
|
|
Running out of memory or illegal operations result in error messages
|
|
on standard error and a call to
|
|
.Xr abort 3 .
|
|
.Sh SEE ALSO
|
|
.Xr abort 3 ,
|
|
.Xr crypto 3 ,
|
|
.Xr free 3 ,
|
|
.Xr malloc 3 ,
|
|
.Xr math 3
|
|
.Sh HISTORY
|
|
A
|
|
.Nm
|
|
library appeared in
|
|
.Bx 4.3 .
|
|
.Fx 2.2
|
|
shipped with a
|
|
.Nm
|
|
implemented in terms of
|
|
.Nm libgmp .
|
|
This implementation appeared in
|
|
.Fx 5.0 .
|
|
.Sh BUGS
|
|
The
|
|
.Fn pow
|
|
routine exists in both
|
|
.Nm libmp
|
|
and
|
|
.Nm libm
|
|
with incompatible semantics.
|
|
.Pp
|
|
Errors are reported via output to standard error and abnormal
|
|
program termination instead of via return values.
|
|
The application cannot control this behavior.
|
|
.Pp
|
|
It is not clear whether the string returned by
|
|
.Fn mtox
|
|
may be written to by the caller.
|
|
This implementation allows it, but others may not.
|
|
Ideally,
|
|
.Fn mtox
|
|
would take a pointer to a buffer to fill in.
|
|
.Pp
|
|
It is not clear whether using the same variable as both source and
|
|
destination in a single invocation is permitted.
|
|
Some of the calls in this implementation allow this, while others
|
|
do not.
|