.\" Copyright 2026 Andrew V.Kosteltsev (kx@radix-linux.su)
.\"
.\"
.TH ipow_mod 3  "September 14, 2026" "libmpu" "LibMPU Programmer's Manual"
.SH NAME
\fBipow_mod\fP \- unsigned modular exponentiation
.SH SYNOPSIS
.nf
.B #include <libmpu.h>
.PP
.BI "void ipow_mod( mpu_int *" c ", mpu_int *" a ", mpu_int *" e ", mpu_int *" m ", int " nb " );"
.fi
.SH DESCRIPTION
The \fBipow_mod()\fP function performs unsigned modular exponentiation
.sp
.nf
        c = (a ^ e) mod m
.fi
.sp
and places the result at address \fBc\fP. The exponent located at \fBe\fP is interpreted as
an unsigned integer. The memory contents at addresses \fBa\fP, \fBe\fP and \fBm\fP are not
changed. The \fBnb\fP parameter determines the size of all operands, in bytes.
.PP
For a zero exponent the result is \fB1 mod m\fP; consequently, when \fBe == 0\fP and
\fBm == 1\fP, the result is zero.
.PP
If \fBm\fP is zero, the value at \fBc\fP is not changed, the \fBV\fP (Invalid operation)
flag is set, and \fB__mpu_integer_error_no\fP is set to \fB__I_ENUMBER__\fP.
.PP
The operation clears the integer flags before execution. The arithmetic flags may be affected
by the internal modular operations; the \fBV\fP flag is set for a zero modulus.
.sp
.SH EXAMPLES
.nf
.sp
#include <libmpu.h>
#include <stdio.h>

int main( void )
{
  mpu_int1024_t  c, a, e, m;
  int            nb = NB_I1024;
  __mpu_char8_t  s[4096];

  __mpu_init();

  iatoui( a, "4", nb );
  iatoui( e, "13", nb );
  iatoui( m, "251", nb );

  ipow_mod( c, a, e, m, nb );
  iuitoa( s, c, RADIX_DEC, LOWERCASE, nb );
  printf( "c = %s;\\n", s ); /* c = 249; */

  __mpu_free_context();

  return( 0 );
}
.fi
.sp
.SH SEE ALSO
.BR iadd(3),
.BR isub(3),
.BR iadc(3),
.BR isbb(3),
.BR ineg(3),
.BR inot(3),
.BR iand(3),
.BR itest(3),
.BR icmp(3),
.BR ior(3),
.BR ixor(3),
.BR iinc(3),
.BR idec(3),
.BR ixchg(3),
.BR icpy(3),
.BR icvt(3),
.BR imul(3),
.BR ismul(3),
.BR idiv(3),
.BR isdiv(3),
.BR iatoi(3),
.BR iatoui(3),
.BR iitoa(3),
.BR iuitoa(3),
.BR _int_digs(3),
.BR ibits_len(3),
.BR igcd(3),
.BR ilcm(3),
.BR imod(3),
.BR imul_mod(3),
.BR ipowm1_mod(3),
.BR shifts(3),
.BR shifts\-n(3),
.BR circular\-shifts(3),
.BR circular\-shifts\-n(3),
.BR integer\-flags(3),
.BR real\-flags(3),
.BR libmpu(7).