summaryrefslogtreecommitdiffstats
path: root/lib/libmp/libmp.3
blob: 9be21d7b0de43416b9bff3b56d81a8cf8167d5ef (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
.\"
.\" 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.
OpenPOWER on IntegriCloud