Add a manual page for the libmp interface. Some of the descriptions

great, but then again neither is the interface it's documenting.

1 files changed, 321 insertions, 0 deletions

diff --git a/lib/libmp/libmp.3 b/lib/libmp/libmp.3
new file mode 100644
index 000000000000..2d9d1d6ac80b
--- /dev/null
+++ b/lib/libmp/libmp.3
@@ -0,0 +1,321 @@
+.\"
+.\" 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
+.Li -lmp
+(this library)
+and
+.Li -lcrypto
+.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 s .
+.Fn xtom
+returns an
+.Vt MINT
+with the value of
+.Fa x ,
+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
+.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 he 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 math 3 ,
+.Xr malloc 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.