From 4edf53c462b51e907c255888a48160d0273dbeb5 Mon Sep 17 00:00:00 2001 From: Dima Dorfman Date: Mon, 30 Jul 2001 09:13:56 +0000 Subject: [PATCH] Add a manual page for the libmp interface. Some of the descriptions great, but then again neither is the interface it's documenting. --- lib/libmp/libmp.3 | 321 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 321 insertions(+) create mode 100644 lib/libmp/libmp.3 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.