mirror of
https://github.com/freebsd/freebsd-src.git
synced 2024-11-29 17:32:43 +00:00
Add a manual page for the libmp interface. Some of the descriptions
great, but then again neither is the interface it's documenting.
This commit is contained in:
Dima Dorfman
parent
ab1d004fd0
commit
4edf53c462
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=80609
321
lib/libmp/libmp.3
Normal file
321
lib/libmp/libmp.3
Normal file
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user