freebsd/lib/libmp/libmp.3

.\"
.\" 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 LIBMP 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 rpow "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 bn 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.