diff options
author | Gavin Howard <gavin@yzena.com> | 2021-06-21 12:30:19 -0600 |
---|---|---|
committer | Gavin Howard <gavin@yzena.com> | 2021-06-21 12:30:19 -0600 |
commit | ffa20d1b15eb3d25e0f5d4d95c323ad0bb29f127 (patch) | |
tree | c503231b451d14266b28605e7dcff04c8d904d9c /manuals | |
parent | 184cbbe720fd2274755c124751d46043d8beeae7 (diff) | |
download | platform_external_bc-ffa20d1b15eb3d25e0f5d4d95c323ad0bb29f127.tar.gz platform_external_bc-ffa20d1b15eb3d25e0f5d4d95c323ad0bb29f127.tar.bz2 platform_external_bc-ffa20d1b15eb3d25e0f5d4d95c323ad0bb29f127.zip |
Fix formatting in the bcl manual
Signed-off-by: Gavin Howard <gavin@yzena.com>
Diffstat (limited to 'manuals')
-rw-r--r-- | manuals/bcl.3 | 297 | ||||
-rw-r--r-- | manuals/bcl.3.md | 250 |
2 files changed, 275 insertions, 272 deletions
diff --git a/manuals/bcl.3 b/manuals/bcl.3 index 27203248..de4cd4fd 100644 --- a/manuals/bcl.3 +++ b/manuals/bcl.3 @@ -40,22 +40,22 @@ Link with \f[I]-lbcl\f[R]. This procedure will allow clients to use signals to interrupt computations running in bcl(3). .PP -\f[B]void bcl_handleSignal(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]void bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B]);\f[R] .PP -\f[B]bool bcl_running(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]bool bcl_running(\f[R]\f[I]void\f[R]\f[B]);\f[R] .SS Setup .PP These items allow clients to set up bcl(3). .PP -\f[B]BclError bcl_init(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]BclError bcl_init(\f[R]\f[I]void\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_free(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]void bcl_free(\f[R]\f[I]void\f[R]\f[B]);\f[R] .PP -\f[B]bool bcl_abortOnFatalError(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]bool bcl_abortOnFatalError(\f[R]\f[I]void\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_setAbortOnFatalError(bool\f[R] \f[I]abrt\f[R]**);** +\f[B]void bcl_setAbortOnFatalError(bool\f[R] \f[I]abrt\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_gc(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]void bcl_gc(\f[R]\f[I]void\f[R]\f[B]);\f[R] .SS Contexts .PP These items will allow clients to handle contexts, which are isolated @@ -66,39 +66,39 @@ This allows more than one client to use bcl(3) in the same program. .PP \f[B]typedef struct BclCtxt* BclContext;\f[R] .PP -\f[B]BclContext bcl_ctxt_create(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]BclContext bcl_ctxt_create(\f[R]\f[I]void\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_ctxt_free(BclContext\f[R] \f[I]ctxt\f[R]**);** +\f[B]void bcl_ctxt_free(BclContext\f[R] \f[I]ctxt\f[R]\f[B]);\f[R] .PP -\f[B]BclError bcl_pushContext(BclContext\f[R] \f[I]ctxt\f[R]**);** +\f[B]BclError bcl_pushContext(BclContext\f[R] \f[I]ctxt\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_popContext(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]void bcl_popContext(\f[R]\f[I]void\f[R]\f[B]);\f[R] .PP -\f[B]BclContext bcl_context(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]BclContext bcl_context(\f[R]\f[I]void\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_ctxt_freeNums(BclContext\f[R] \f[I]ctxt\f[R]**);** +\f[B]void bcl_ctxt_freeNums(BclContext\f[R] \f[I]ctxt\f[R]\f[B]);\f[R] .PP -\f[B]size_t bcl_ctxt_scale(BclContext\f[R] \f[I]ctxt\f[R]**);** +\f[B]size_t bcl_ctxt_scale(BclContext\f[R] \f[I]ctxt\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_ctxt_setScale(BclContext\f[R] \f[I]ctxt\f[R]**, size_t** -\f[I]scale\f[R]**);** +\f[B]void bcl_ctxt_setScale(BclContext\f[R] \f[I]ctxt\f[R]\f[B], +size_t\f[R] \f[I]scale\f[R]\f[B]);\f[R] .PP -\f[B]size_t bcl_ctxt_ibase(BclContext\f[R] \f[I]ctxt\f[R]**);** +\f[B]size_t bcl_ctxt_ibase(BclContext\f[R] \f[I]ctxt\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_ctxt_setIbase(BclContext\f[R] \f[I]ctxt\f[R]**, size_t** -\f[I]ibase\f[R]**);** +\f[B]void bcl_ctxt_setIbase(BclContext\f[R] \f[I]ctxt\f[R]\f[B], +size_t\f[R] \f[I]ibase\f[R]\f[B]);\f[R] .PP -\f[B]size_t bcl_ctxt_obase(BclContext\f[R] \f[I]ctxt\f[R]**);** +\f[B]size_t bcl_ctxt_obase(BclContext\f[R] \f[I]ctxt\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_ctxt_setObase(BclContext\f[R] \f[I]ctxt\f[R]**, size_t** -\f[I]obase\f[R]**);** +\f[B]void bcl_ctxt_setObase(BclContext\f[R] \f[I]ctxt\f[R]\f[B], +size_t\f[R] \f[I]obase\f[R]\f[B]);\f[R] .SS Errors .PP These items allow clients to handle errors. .PP \f[B]typedef enum BclError BclError;\f[R] .PP -\f[B]BclError bcl_err(BclNumber\f[R] \f[I]n\f[R]**);** +\f[B]BclError bcl_err(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .SS Numbers .PP These items allow clients to manipulate and query the @@ -106,85 +106,86 @@ arbitrary-precision numbers managed by bcl(3). .PP \f[B]typedef struct { size_t i; } BclNumber;\f[R] .PP -\f[B]BclNumber bcl_num_create(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]BclNumber bcl_num_create(\f[R]\f[I]void\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_num_free(BclNumber\f[R] \f[I]n\f[R]**);** +\f[B]void bcl_num_free(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .PP -\f[B]bool bcl_num_neg(BclNumber\f[R] \f[I]n\f[R]**);** +\f[B]bool bcl_num_neg(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_num_setNeg(BclNumber\f[R] \f[I]n\f[R]**, bool** -\f[I]neg\f[R]**);** +\f[B]void bcl_num_setNeg(BclNumber\f[R] \f[I]n\f[R]\f[B], bool\f[R] +\f[I]neg\f[R]\f[B]);\f[R] .PP -\f[B]size_t bcl_num_scale(BclNumber\f[R] \f[I]n\f[R]**);** +\f[B]size_t bcl_num_scale(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .PP -\f[B]BclError bcl_num_setScale(BclNumber\f[R] \f[I]n\f[R]**, size_t** -\f[I]scale\f[R]**);** +\f[B]BclError bcl_num_setScale(BclNumber\f[R] \f[I]n\f[R]\f[B], +size_t\f[R] \f[I]scale\f[R]\f[B]);\f[R] .PP -\f[B]size_t bcl_num_len(BclNumber\f[R] \f[I]n\f[R]**);** +\f[B]size_t bcl_num_len(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .SS Conversion .PP These items allow clients to convert numbers into and from strings and integers. .PP -\f[B]BclNumber bcl_parse(const char *restrict\f[R] \f[I]val\f[R]**);** +\f[B]BclNumber bcl_parse(const char *restrict\f[R] +\f[I]val\f[R]\f[B]);\f[R] .PP -\f[B]char* bcl_string(BclNumber\f[R] \f[I]n\f[R]**);** +\f[B]char* bcl_string(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .PP -\f[B]BclError bcl_bigdig(BclNumber\f[R] \f[I]n\f[R]**, BclBigDig -*\f[I]\f[BI]result\f[I]\f[R]);** +\f[B]BclError bcl_bigdig(BclNumber\f[R] \f[I]n\f[R]\f[B], BclBigDig +*\f[R]\f[I]result\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_bigdig2num(BclBigDig\f[R] \f[I]val\f[R]**);** +\f[B]BclNumber bcl_bigdig2num(BclBigDig\f[R] \f[I]val\f[R]\f[B]);\f[R] .SS Math .PP These items allow clients to run math on numbers. .PP -\f[B]BclNumber bcl_add(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** -\f[I]b\f[R]**);** +\f[B]BclNumber bcl_add(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] +\f[I]b\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_sub(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** -\f[I]b\f[R]**);** +\f[B]BclNumber bcl_sub(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] +\f[I]b\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_mul(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** -\f[I]b\f[R]**);** +\f[B]BclNumber bcl_mul(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] +\f[I]b\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_div(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** -\f[I]b\f[R]**);** +\f[B]BclNumber bcl_div(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] +\f[I]b\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_mod(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** -\f[I]b\f[R]**);** +\f[B]BclNumber bcl_mod(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] +\f[I]b\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_pow(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** -\f[I]b\f[R]**);** +\f[B]BclNumber bcl_pow(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] +\f[I]b\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_lshift(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** -\f[I]b\f[R]**);** +\f[B]BclNumber bcl_lshift(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_rshift(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** -\f[I]b\f[R]**);** +\f[B]BclNumber bcl_rshift(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_sqrt(BclNumber\f[R] \f[I]a\f[R]**);** +\f[B]BclNumber bcl_sqrt(BclNumber\f[R] \f[I]a\f[R]\f[B]);\f[R] .PP -\f[B]BclError bcl_divmod(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** -\f[I]b\f[R]**, BclNumber *\f[I]\f[BI]c\f[I]\f[R], BclNumber -*\f[I]\f[BI]d\f[I]\f[R]);** +\f[B]BclError bcl_divmod(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] +\f[I]b\f[R]\f[B], BclNumber *\f[R]\f[I]c\f[R]\f[B], BclNumber +*\f[R]\f[I]d\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_modexp(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** -\f[I]b\f[R]**, BclNumber** \f[I]c\f[R]**);** +\f[B]BclNumber bcl_modexp(BclNumber\f[R] \f[I]a\f[R]\f[B], +BclNumber\f[R] \f[I]b\f[R]\f[B], BclNumber\f[R] \f[I]c\f[R]\f[B]);\f[R] .SS Miscellaneous .PP These items are miscellaneous. .PP -\f[B]void bcl_zero(BclNumber\f[R] \f[I]n\f[R]**);** +\f[B]void bcl_zero(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .PP -\f[B]void bcl_one(BclNumber\f[R] \f[I]n\f[R]**);** +\f[B]void bcl_one(BclNumber\f[R] \f[I]n\f[R]\f[B]);\f[R] .PP -\f[B]ssize_t bcl_cmp(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** -\f[I]b\f[R]**);** +\f[B]ssize_t bcl_cmp(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] +\f[I]b\f[R]\f[B]);\f[R] .PP -\f[B]BclError bcl_copy(BclNumber\f[R] \f[I]d\f[R]**, BclNumber** -\f[I]s\f[R]**);** +\f[B]BclError bcl_copy(BclNumber\f[R] \f[I]d\f[R]\f[B], BclNumber\f[R] +\f[I]s\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_dup(BclNumber\f[R] \f[I]s\f[R]**);** +\f[B]BclNumber bcl_dup(BclNumber\f[R] \f[I]s\f[R]\f[B]);\f[R] .SS Pseudo-Random Number Generator .PP These items allow clients to manipulate the seeded pseudo-random number @@ -198,25 +199,27 @@ generator in bcl(3). .PP \f[B]typedef unsigned long BclRandInt;\f[R] .PP -\f[B]BclNumber bcl_irand(BclNumber\f[R] \f[I]a\f[R]**);** +\f[B]BclNumber bcl_irand(BclNumber\f[R] \f[I]a\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_frand(size_t\f[R] \f[I]places\f[R]**);** +\f[B]BclNumber bcl_frand(size_t\f[R] \f[I]places\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_ifrand(BclNumber\f[R] \f[I]a\f[R]**, size_t** -\f[I]places\f[R]**);** +\f[B]BclNumber bcl_ifrand(BclNumber\f[R] \f[I]a\f[R]\f[B], size_t\f[R] +\f[I]places\f[R]\f[B]);\f[R] .PP -\f[B]BclError bcl_rand_seedWithNum(BclNumber\f[R] \f[I]n\f[R]**);** +\f[B]BclError bcl_rand_seedWithNum(BclNumber\f[R] +\f[I]n\f[R]\f[B]);\f[R] .PP \f[B]BclError bcl_rand_seed(unsigned char\f[R] -\f[I]seed\f[R]**[\f[I]\f[BI]BC_SEED_SIZE\f[I]\f[R]]);** +\f[I]seed\f[R]\f[B][\f[R]\f[I]BC_SEED_SIZE\f[R]\f[B]]);\f[R] .PP -\f[B]void bcl_rand_reseed(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]void bcl_rand_reseed(\f[R]\f[I]void\f[R]\f[B]);\f[R] .PP -\f[B]BclNumber bcl_rand_seed2num(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]BclNumber bcl_rand_seed2num(\f[R]\f[I]void\f[R]\f[B]);\f[R] .PP -\f[B]BclRandInt bcl_rand_int(\f[BI]\f[I]void\f[BI]\f[B]);\f[R] +\f[B]BclRandInt bcl_rand_int(\f[R]\f[I]void\f[R]\f[B]);\f[R] .PP -\f[B]BclRandInt bcl_rand_bounded(BclRandInt\f[R] \f[I]bound\f[R]**);** +\f[B]BclRandInt bcl_rand_bounded(BclRandInt\f[R] +\f[I]bound\f[R]\f[B]);\f[R] .SH DESCRIPTION .PP bcl(3) is a library that implements arbitrary-precision decimal math, as @@ -225,7 +228,7 @@ POSIX (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) in bc(1). .PP bcl(3) is async-signal-safe if -\f[B]bcl_handleSignal(\f[BI]\f[I]void\f[BI]\f[B])\f[R] is used properly. +\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] is used properly. (See the \f[B]SIGNAL HANDLING\f[R] section.) .PP All of the items in its interface are described below. @@ -233,7 +236,7 @@ See the documentation for each function for what each function can return. .SS Signals .TP -\f[B]void bcl_handleSignal(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]void bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] An async-signal-safe function that can be called from a signal handler. If called from a signal handler on the same thread as any executing bcl(3) functions, it will interrupt the functions and force them to @@ -244,17 +247,17 @@ functions are executing. .RS .PP If execution \f[I]is\f[R] interrupted, -\f[B]bcl_handleSignal(\f[BI]\f[I]void\f[BI]\f[B])\f[R] does -\f[I]not\f[R] return to its caller. +\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] does \f[I]not\f[R] +return to its caller. .PP See the \f[B]SIGNAL HANDLING\f[R] section. .RE .TP -\f[B]bool bcl_running(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]bool bcl_running(\f[R]\f[I]void\f[R]\f[B])\f[R] An async-signal-safe function that can be called from a signal handler. It will return \f[B]true\f[R] if any bcl(3) procedures are running, which means it is safe to call -\f[B]bcl_handleSignal(\f[BI]\f[I]void\f[BI]\f[B])\f[R]. +\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R]. Otherwise, it returns \f[B]false\f[R]. .RS .PP @@ -262,10 +265,10 @@ See the \f[B]SIGNAL HANDLING\f[R] section. .RE .SS Setup .TP -\f[B]BclError bcl_init(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]BclError bcl_init(\f[R]\f[I]void\f[R]\f[B])\f[R] Initializes this library. This function can be called multiple times, but each call must be -matched by a call to \f[B]bcl_free(\f[BI]\f[I]void\f[BI]\f[B])\f[R]. +matched by a call to \f[B]bcl_free(\f[R]\f[I]void\f[R]\f[B])\f[R]. This is to make it possible for multiple libraries and applications to initialize bcl(3) without problem. .RS @@ -280,7 +283,7 @@ Calling any other function without calling this one first is undefined behavior. .RE .TP -\f[B]void bcl_free(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]void bcl_free(\f[R]\f[I]void\f[R]\f[B])\f[R] Decrements bcl(3)\[cq]s reference count and frees the data associated with it if the reference count is \f[B]0\f[R]. .RS @@ -290,7 +293,7 @@ Calling this function before calling any other function is undefined behavior. .RE .TP -\f[B]bool bcl_abortOnFatalError(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]bool bcl_abortOnFatalError(\f[R]\f[I]void\f[R]\f[B])\f[R] Queries and returns the current state of calling \f[B]abort()\f[R] on fatal errors. If \f[B]true\f[R] is returned, bcl(3) will cause a \f[B]SIGABRT\f[R] if @@ -300,7 +303,7 @@ a fatal error occurs. If activated, clients do not need to check for fatal errors. .RE .TP -\f[B]void bcl_setAbortOnFatalError(bool\f[R] \f[I]abrt\f[R]**)** +\f[B]void bcl_setAbortOnFatalError(bool\f[R] \f[I]abrt\f[R]\f[B])\f[R] Sets the state of calling \f[B]abort()\f[R] on fatal errors. If \f[I]abrt\f[R] is \f[B]false\f[R], bcl(3) will not cause a \f[B]SIGABRT\f[R] on fatal errors after the call. @@ -311,7 +314,7 @@ If \f[I]abrt\f[R] is \f[B]true\f[R], bcl(3) will cause a If activated, clients do not need to check for fatal errors. .RE .TP -\f[B]void bcl_gc(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]void bcl_gc(\f[R]\f[I]void\f[R]\f[B])\f[R] Garbage collects cached instances of arbitrary-precision numbers. This only frees the memory of numbers that are \f[I]not\f[R] in use, so it is safe to call at any time. @@ -361,18 +364,18 @@ Contexts are meant to isolate the numbers used by different clients in the same application. .RE .TP -\f[B]BclContext bcl_ctxt_create(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]BclContext bcl_ctxt_create(\f[R]\f[I]void\f[R]\f[B])\f[R] Creates a context and returns it. Returns \f[B]NULL\f[R] if there was an error. .TP -\f[B]void bcl_ctxt_free(BclContext\f[R] \f[I]ctxt\f[R]**)** +\f[B]void bcl_ctxt_free(BclContext\f[R] \f[I]ctxt\f[R]\f[B])\f[R] Frees \f[I]ctxt\f[R], after which it is no longer valid. It is undefined behavior to attempt to use an invalid context. .TP -\f[B]BclError bcl_pushContext(BclContext\f[R] \f[I]ctxt\f[R]**)** +\f[B]BclError bcl_pushContext(BclContext\f[R] \f[I]ctxt\f[R]\f[B])\f[R] Pushes \f[I]ctxt\f[R] onto bcl(3)\[cq]s stack of contexts. \f[I]ctxt\f[R] must have been created with -\f[B]bcl_ctxt_create(\f[BI]\f[I]void\f[BI]\f[B])\f[R]. +\f[B]bcl_ctxt_create(\f[R]\f[I]void\f[R]\f[B])\f[R]. .RS .PP If there was no error, \f[B]BCL_ERROR_NONE\f[R] is returned. @@ -383,40 +386,40 @@ Otherwise, this function can return: There \f[I]must\f[R] be a valid context to do any arithmetic. .RE .TP -\f[B]void bcl_popContext(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]void bcl_popContext(\f[R]\f[I]void\f[R]\f[B])\f[R] Pops the current context off of the stack, if one exists. .TP -\f[B]BclContext bcl_context(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]BclContext bcl_context(\f[R]\f[I]void\f[R]\f[B])\f[R] Returns the current context, or \f[B]NULL\f[R] if no context exists. .TP -\f[B]void bcl_ctxt_freeNums(BclContext\f[R] \f[I]ctxt\f[R]**)** +\f[B]void bcl_ctxt_freeNums(BclContext\f[R] \f[I]ctxt\f[R]\f[B])\f[R] Frees all numbers in use that are associated with \f[I]ctxt\f[R]. It is undefined behavior to attempt to use a number associated with \f[I]ctxt\f[R] after calling this procedure unless such numbers have -been created with \f[B]bcl_num_create(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +been created with \f[B]bcl_num_create(\f[R]\f[I]void\f[R]\f[B])\f[R] after calling this procedure. .TP -\f[B]size_t bcl_ctxt_scale(BclContext\f[R] \f[I]ctxt\f[R]**)** +\f[B]size_t bcl_ctxt_scale(BclContext\f[R] \f[I]ctxt\f[R]\f[B])\f[R] Returns the \f[B]scale\f[R] for given context. .TP -\f[B]void bcl_ctxt_setScale(BclContext\f[R] \f[I]ctxt\f[R]**, size_t** \f[I]scale\f[R]**)** +\f[B]void bcl_ctxt_setScale(BclContext\f[R] \f[I]ctxt\f[R]\f[B], size_t\f[R] \f[I]scale\f[R]\f[B])\f[R] Sets the \f[B]scale\f[R] for the given context to the argument \f[I]scale\f[R]. .TP -\f[B]size_t bcl_ctxt_ibase(BclContext\f[R] \f[I]ctxt\f[R]**)** +\f[B]size_t bcl_ctxt_ibase(BclContext\f[R] \f[I]ctxt\f[R]\f[B])\f[R] Returns the \f[B]ibase\f[R] for the given context. .TP -\f[B]void bcl_ctxt_setIbase(BclContext\f[R] \f[I]ctxt\f[R]**, size_t** \f[I]ibase\f[R]**)** +\f[B]void bcl_ctxt_setIbase(BclContext\f[R] \f[I]ctxt\f[R]\f[B], size_t\f[R] \f[I]ibase\f[R]\f[B])\f[R] Sets the \f[B]ibase\f[R] for the given context to the argument \f[I]ibase\f[R]. If the argument \f[I]ibase\f[R] is invalid, it clamped, so an \f[I]ibase\f[R] of \f[B]0\f[R] or \f[B]1\f[R] is clamped to \f[B]2\f[R], and any values above \f[B]36\f[R] are clamped to \f[B]36\f[R]. .TP -\f[B]size_t bcl_ctxt_obase(BclContext\f[R] \f[I]ctxt\f[R]**)** +\f[B]size_t bcl_ctxt_obase(BclContext\f[R] \f[I]ctxt\f[R]\f[B])\f[R] Returns the \f[B]obase\f[R] for the given context. .TP -\f[B]void bcl_ctxt_setObase(BclContext\f[R] \f[I]ctxt\f[R]**, size_t** \f[I]obase\f[R]**)** +\f[B]void bcl_ctxt_setObase(BclContext\f[R] \f[I]ctxt\f[R]\f[B], size_t\f[R] \f[I]obase\f[R]\f[B])\f[R] Sets the \f[B]obase\f[R] for the given context to the argument \f[I]obase\f[R]. .SS Errors @@ -425,7 +428,7 @@ Sets the \f[B]obase\f[R] for the given context to the argument An \f[B]enum\f[R] of possible error codes. See the \f[B]ERRORS\f[R] section for a complete listing the codes. .TP -\f[B]BclError bcl_err(BclNumber\f[R] \f[I]n\f[R]**)** +\f[B]BclError bcl_err(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] Checks for errors in a \f[B]BclNumber\f[R]. All functions that can return a \f[B]BclNumber\f[R] can encode an error in the number, and this function will return the error, if any. @@ -444,7 +447,7 @@ The actual number type is not exposed; the \f[B]BclNumber\f[R] handle is the only way clients can refer to instances of arbitrary-precision numbers. .TP -\f[B]BclNumber bcl_num_create(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]BclNumber bcl_num_create(\f[R]\f[I]void\f[R]\f[B])\f[R] Creates and returns a \f[B]BclNumber\f[R]. .RS .PP @@ -457,19 +460,19 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]void bcl_num_free(BclNumber\f[R] \f[I]n\f[R]**)** +\f[B]void bcl_num_free(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] Frees \f[I]n\f[R]. It is undefined behavior to use \f[I]n\f[R] after calling this function. .TP -\f[B]bool bcl_num_neg(BclNumber\f[R] \f[I]n\f[R]**)** +\f[B]bool bcl_num_neg(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] Returns \f[B]true\f[R] if \f[I]n\f[R] is negative, \f[B]false\f[R] otherwise. .TP -\f[B]void bcl_num_setNeg(BclNumber\f[R] \f[I]n\f[R]**, bool** \f[I]neg\f[R]**)** +\f[B]void bcl_num_setNeg(BclNumber\f[R] \f[I]n\f[R]\f[B], bool\f[R] \f[I]neg\f[R]\f[B])\f[R] Sets \f[I]n\f[R]\[cq]s sign to \f[I]neg\f[R], where \f[B]true\f[R] is negative, and \f[B]false\f[R] is positive. .TP -\f[B]size_t bcl_num_scale(BclNumber\f[R] \f[I]n\f[R]**)** +\f[B]size_t bcl_num_scale(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] Returns the \f[I]scale\f[R] of \f[I]n\f[R]. .RS .PP @@ -477,7 +480,7 @@ The \f[I]scale\f[R] of a number is the number of decimal places it has after the radix (decimal point). .RE .TP -\f[B]BclError bcl_num_setScale(BclNumber\f[R] \f[I]n\f[R]**, size_t** \f[I]scale\f[R]**)** +\f[B]BclError bcl_num_setScale(BclNumber\f[R] \f[I]n\f[R]\f[B], size_t\f[R] \f[I]scale\f[R]\f[B])\f[R] Sets the \f[I]scale\f[R] of \f[I]n\f[R] to the argument \f[I]scale\f[R]. If the argument \f[I]scale\f[R] is greater than the \f[I]scale\f[R] of \f[I]n\f[R], \f[I]n\f[R] is extended. @@ -495,7 +498,7 @@ Otherwise, this function can return: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]size_t bcl_num_len(BclNumber\f[R] \f[I]n\f[R]**)** +\f[B]size_t bcl_num_len(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] Returns the number of \f[I]significant decimal digits\f[R] in \f[I]n\f[R]. .SS Conversion @@ -506,7 +509,7 @@ All procedures in this section consume the given \f[B]BclNumber\f[R] arguments that are not given to pointer arguments. See the \f[B]Consumption and Propagation\f[R] subsection below. .TP -\f[B]BclNumber bcl_parse(const char *restrict\f[R] \f[I]val\f[R]**)** +\f[B]BclNumber bcl_parse(const char *restrict\f[R] \f[I]val\f[R]\f[B])\f[R] Parses a number string according to the current context\[cq]s \f[B]ibase\f[R] and returns the resulting number. .RS @@ -528,7 +531,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]char* bcl_string(BclNumber\f[R] \f[I]n\f[R]**)** +\f[B]char* bcl_string(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] Returns a string representation of \f[I]n\f[R] according the the current context\[cq]s \f[B]ibase\f[R]. The string is dynamically allocated and must be freed by the caller. @@ -538,7 +541,7 @@ The string is dynamically allocated and must be freed by the caller. See the \f[B]Consumption and Propagation\f[R] subsection below. .RE .TP -\f[B]BclError bcl_bigdig(BclNumber\f[R] \f[I]n\f[R]**, BclBigDig *\f[I]\f[BI]result\f[I]\f[R])** +\f[B]BclError bcl_bigdig(BclNumber\f[R] \f[I]n\f[R]\f[B], BclBigDig *\f[R]\f[I]result\f[R]\f[B])\f[R] Converts \f[I]n\f[R] into a \f[B]BclBigDig\f[R] and returns the result in the space pointed to by \f[I]result\f[R]. .RS @@ -559,7 +562,7 @@ Otherwise, this function can return: See the \f[B]Consumption and Propagation\f[R] subsection below. .RE .TP -\f[B]BclNumber bcl_bigdig2num(BclBigDig\f[R] \f[I]val\f[R]**)** +\f[B]BclNumber bcl_bigdig2num(BclBigDig\f[R] \f[I]val\f[R]\f[B])\f[R] Creates a \f[B]BclNumber\f[R] from \f[I]val\f[R]. .RS .PP @@ -583,7 +586,7 @@ All procedures in this section can return the following errors: .IP \[bu] 2 \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .TP -\f[B]BclNumber bcl_add(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** \f[I]b\f[R]**)** +\f[B]BclNumber bcl_add(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Adds \f[I]a\f[R] and \f[I]b\f[R] and returns the result. The \f[I]scale\f[R] of the result is the max of the \f[I]scale\f[R]s of \f[I]a\f[R] and \f[I]b\f[R]. @@ -606,7 +609,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_sub(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** \f[I]b\f[R]**)** +\f[B]BclNumber bcl_sub(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Subtracts \f[I]b\f[R] from \f[I]a\f[R] and returns the result. The \f[I]scale\f[R] of the result is the max of the \f[I]scale\f[R]s of \f[I]a\f[R] and \f[I]b\f[R]. @@ -629,7 +632,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_mul(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** \f[I]b\f[R]**)** +\f[B]BclNumber bcl_mul(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Multiplies \f[I]a\f[R] and \f[I]b\f[R] and returns the result. If \f[I]ascale\f[R] is the \f[I]scale\f[R] of \f[I]a\f[R] and \f[I]bscale\f[R] is the \f[I]scale\f[R] of \f[I]b\f[R], the @@ -655,7 +658,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_div(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** \f[I]b\f[R]**)** +\f[B]BclNumber bcl_div(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Divides \f[I]a\f[R] by \f[I]b\f[R] and returns the result. The \f[I]scale\f[R] of the result is the \f[I]scale\f[R] of the current context. @@ -682,7 +685,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_mod(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** \f[I]b\f[R]**)** +\f[B]BclNumber bcl_mod(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Divides \f[I]a\f[R] by \f[I]b\f[R] to the \f[I]scale\f[R] of the current context, computes the modulus \f[B]a-(a/b)*b\f[R], and returns the modulus. @@ -709,7 +712,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_pow(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** \f[I]b\f[R]**)** +\f[B]BclNumber bcl_pow(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Calculates \f[I]a\f[R] to the power of \f[I]b\f[R] to the \f[I]scale\f[R] of the current context. \f[I]b\f[R] must be an integer, but can be negative. @@ -745,7 +748,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_lshift(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** \f[I]b\f[R]**)** +\f[B]BclNumber bcl_lshift(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Shifts \f[I]a\f[R] left (moves the radix right) by \f[I]b\f[R] places and returns the result. This is done in decimal. @@ -773,7 +776,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_rshift(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** \f[I]b\f[R]**)** +\f[B]BclNumber bcl_rshift(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Shifts \f[I]a\f[R] right (moves the radix left) by \f[I]b\f[R] places and returns the result. This is done in decimal. @@ -801,7 +804,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_sqrt(BclNumber\f[R] \f[I]a\f[R]**)** +\f[B]BclNumber bcl_sqrt(BclNumber\f[R] \f[I]a\f[R]\f[B])\f[R] Calculates the square root of \f[I]a\f[R] and returns the result. The \f[I]scale\f[R] of the result is equal to the \f[B]scale\f[R] of the current context. @@ -825,7 +828,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclError bcl_divmod(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** \f[I]b\f[R]**, BclNumber *\f[I]\f[BI]c\f[I]\f[R], BclNumber *\f[I]\f[BI]d\f[I]\f[R])** +\f[B]BclError bcl_divmod(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B], BclNumber *\f[R]\f[I]c\f[R]\f[B], BclNumber *\f[R]\f[I]d\f[R]\f[B])\f[R] Divides \f[I]a\f[R] by \f[I]b\f[R] and returns the quotient in a new number which is put into the space pointed to by \f[I]c\f[R], and puts the modulus in a new number which is put into the space pointed to by @@ -853,7 +856,7 @@ Otherwise, this function can return: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_modexp(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** \f[I]b\f[R]**, BclNumber** \f[I]c\f[R]**)** +\f[B]BclNumber bcl_modexp(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B], BclNumber\f[R] \f[I]c\f[R]\f[B])\f[R] Computes a modular exponentiation where \f[I]a\f[R] is the base, \f[I]b\f[R] is the exponent, and \f[I]c\f[R] is the modulus, and returns the result. @@ -887,19 +890,19 @@ Possible errors include: .RE .SS Miscellaneous .TP -\f[B]void bcl_zero(BclNumber\f[R] \f[I]n\f[R]**)** +\f[B]void bcl_zero(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] Sets \f[I]n\f[R] to \f[B]0\f[R]. .TP -\f[B]void bcl_one(BclNumber\f[R] \f[I]n\f[R]**)** +\f[B]void bcl_one(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] Sets \f[I]n\f[R] to \f[B]1\f[R]. .TP -\f[B]ssize_t bcl_cmp(BclNumber\f[R] \f[I]a\f[R]**, BclNumber** \f[I]b\f[R]**)** +\f[B]ssize_t bcl_cmp(BclNumber\f[R] \f[I]a\f[R]\f[B], BclNumber\f[R] \f[I]b\f[R]\f[B])\f[R] Compares \f[I]a\f[R] and \f[I]b\f[R] and returns \f[B]0\f[R] if \f[I]a\f[R] and \f[I]b\f[R] are equal, \f[B]<0\f[R] if \f[I]a\f[R] is less than \f[I]b\f[R], and \f[B]>0\f[R] if \f[I]a\f[R] is greater than \f[I]b\f[R]. .TP -\f[B]BclError bcl_copy(BclNumber\f[R] \f[I]d\f[R]**, BclNumber** \f[I]s\f[R]**)** +\f[B]BclError bcl_copy(BclNumber\f[R] \f[I]d\f[R]\f[B], BclNumber\f[R] \f[I]s\f[R]\f[B])\f[R] Copies \f[I]s\f[R] into \f[I]d\f[R]. .RS .PP @@ -913,7 +916,7 @@ Otherwise, this function can return: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_dup(BclNumber\f[R] \f[I]s\f[R]**)** +\f[B]BclNumber bcl_dup(BclNumber\f[R] \f[I]s\f[R]\f[B])\f[R] Creates and returns a new \f[B]BclNumber\f[R] that is a copy of \f[I]s\f[R]. .RS @@ -949,9 +952,9 @@ functions: .IP \[bu] 2 \f[B]bcl_rand_seedWithNum(BclNumber)\f[R] .IP \[bu] 2 -\f[B]bcl_rand_seed(unsigned char[BC_SEED_SIZE])\f[R] +\f[B]bcl_rand_seed(unsigned char[\f[R]\f[I]BC_SEED_SIZE\f[R]\f[B]])\f[R] .IP \[bu] 2 -\f[B]bcl_rand_reseed(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]bcl_rand_reseed(\f[R]\f[I]void\f[R]\f[B])\f[R] .PP The following items allow clients to use the pseudo-random number generator. @@ -972,7 +975,7 @@ bcl(3)\[cq]s overflow type (see the \f[B]PERFORMANCE\f[R] section). An unsigned integer type returned by bcl(3)\[cq]s random number generator. .TP -\f[B]BclNumber bcl_irand(BclNumber\f[R] \f[I]a\f[R]**)** +\f[B]BclNumber bcl_irand(BclNumber\f[R] \f[I]a\f[R]\f[B])\f[R] Returns a random number that is not larger than \f[I]a\f[R] in a new number. If \f[I]a\f[R] is \f[B]0\f[R] or \f[B]1\f[R], the new number is equal to @@ -1005,7 +1008,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_frand(size_t\f[R] \f[I]places\f[R]**)** +\f[B]BclNumber bcl_frand(size_t\f[R] \f[I]places\f[R]\f[B])\f[R] Returns a random number between \f[B]0\f[R] (inclusive) and \f[B]1\f[R] (exclusive) that has \f[I]places\f[R] decimal digits after the radix (decimal point). @@ -1023,7 +1026,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclNumber bcl_ifrand(BclNumber\f[R] \f[I]a\f[R]**, size_t** \f[I]places\f[R]**)** +\f[B]BclNumber bcl_ifrand(BclNumber\f[R] \f[I]a\f[R]\f[B], size_t\f[R] \f[I]places\f[R]\f[B])\f[R] Returns a random number less than \f[I]a\f[R] with \f[I]places\f[R] decimal digits after the radix (decimal point). There are no limits on \f[I]a\f[R] or \f[I]places\f[R]. @@ -1051,7 +1054,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclError bcl_rand_seedWithNum(BclNumber\f[R] \f[I]n\f[R]**)** +\f[B]BclError bcl_rand_seedWithNum(BclNumber\f[R] \f[I]n\f[R]\f[B])\f[R] Seeds the PRNG with \f[I]n\f[R]. .RS .PP @@ -1066,13 +1069,13 @@ Otherwise, this function can return: .IP \[bu] 2 \f[B]BCL_ERROR_INVALID_CONTEXT\f[R] .PP -Note that if \f[B]bcl_rand_seed2num(\f[BI]\f[I]void\f[BI]\f[B])\f[R] or +Note that if \f[B]bcl_rand_seed2num(\f[R]\f[I]void\f[R]\f[B])\f[R] or \f[B]bcl_rand_seed2num_err(BclNumber)\f[R] are called right after this function, they are not guaranteed to return a number equal to \f[I]n\f[R]. .RE .TP -\f[B]BclError bcl_rand_seed(unsigned char\f[R] \f[I]seed\f[R]**[\f[I]\f[BI]BC_SEED_SIZE\f[I]\f[R]])** +\f[B]BclError bcl_rand_seed(unsigned char\f[R] \f[I]seed\f[R]\f[B][\f[R]\f[I]BC_SEED_SIZE\f[R]\f[B]])\f[R] Seeds the PRNG with the bytes in \f[I]seed\f[R]. .RS .PP @@ -1082,7 +1085,7 @@ Otherwise, this function can return: \f[B]BCL_ERROR_INVALID_CONTEXT\f[R] .RE .TP -\f[B]void bcl_rand_reseed(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]void bcl_rand_reseed(\f[R]\f[I]void\f[R]\f[B])\f[R] Reseeds the PRNG with the default reseeding behavior. First, it attempts to read data from \f[B]/dev/urandom\f[R] and falls back to \f[B]libc\f[R]\[cq]s \f[B]rand()\f[R]. @@ -1091,7 +1094,7 @@ back to \f[B]libc\f[R]\[cq]s \f[B]rand()\f[R]. This procedure cannot fail. .RE .TP -\f[B]BclNumber bcl_rand_seed2num(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]BclNumber bcl_rand_seed2num(\f[R]\f[I]void\f[R]\f[B])\f[R] Returns the current seed of the PRNG as a \f[B]BclNumber\f[R]. .RS .PP @@ -1106,7 +1109,7 @@ Possible errors include: \f[B]BCL_ERROR_FATAL_ALLOC_ERR\f[R] .RE .TP -\f[B]BclRandInt bcl_rand_int(\f[BI]\f[I]void\f[BI]\f[B])\f[R] +\f[B]BclRandInt bcl_rand_int(\f[R]\f[I]void\f[R]\f[B])\f[R] Returns a random integer between \f[B]0\f[R] and \f[B]BC_RAND_MAX\f[R] (inclusive). .RS @@ -1114,7 +1117,7 @@ Returns a random integer between \f[B]0\f[R] and \f[B]BC_RAND_MAX\f[R] This procedure cannot fail. .RE .TP -\f[B]BclRandInt bcl_rand_bounded(BclRandInt\f[R] \f[I]bound\f[R]**)** +\f[B]BclRandInt bcl_rand_bounded(BclRandInt\f[R] \f[I]bound\f[R]\f[B])\f[R] Returns a random integer between \f[B]0\f[R] and \f[I]bound\f[R] (exclusive). Bias is removed before returning the integer. @@ -1244,7 +1247,7 @@ this behavior. .RE .SH ATTRIBUTES .PP -When \f[B]bcl_handleSignal(\f[BI]\f[I]void\f[BI]\f[B])\f[R] is used +When \f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] is used properly, bcl(3) is async-signal-safe. .PP bcl(3) is \f[I]MT-Unsafe\f[R]: it is unsafe to call any functions from @@ -1323,7 +1326,7 @@ In fact, memory should be exhausted before these limits should be hit. .SH SIGNAL HANDLING .PP If a signal handler calls -\f[B]bcl_handleSignal(\f[BI]\f[I]void\f[BI]\f[B])\f[R] from the same +\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] from the same thread that there are bcl(3) functions executing in, it will cause all execution to stop as soon as possible, interrupting long-running calculations, if necessary and cause the function that was executing to @@ -1331,11 +1334,11 @@ return. If possible, the error code \f[B]BC_ERROR_SIGNAL\f[R] is returned. .PP If execution \f[I]is\f[R] interrupted, -\f[B]bcl_handleSignal(\f[BI]\f[I]void\f[BI]\f[B])\f[R] does -\f[I]not\f[R] return to its caller. +\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] does \f[I]not\f[R] +return to its caller. .PP It is undefined behavior if -\f[B]bcl_handleSignal(\f[BI]\f[I]void\f[BI]\f[B])\f[R] is called from a +\f[B]bcl_handleSignal(\f[R]\f[I]void\f[R]\f[B])\f[R] is called from a thread that is not executing bcl(3) functions, if bcl(3) functions are executing. .SH SEE ALSO diff --git a/manuals/bcl.3.md b/manuals/bcl.3.md index 76cd54de..09cdb49f 100644 --- a/manuals/bcl.3.md +++ b/manuals/bcl.3.md @@ -45,23 +45,23 @@ Link with *-lbcl*. This procedure will allow clients to use signals to interrupt computations running in bcl(3). -**void bcl_handleSignal(***void***);** +**void bcl_handleSignal(**_void_**);** -**bool bcl_running(***void***);** +**bool bcl_running(**_void_**);** ## Setup These items allow clients to set up bcl(3). -**BclError bcl_init(***void***);** +**BclError bcl_init(**_void_**);** -**void bcl_free(***void***);** +**void bcl_free(**_void_**);** -**bool bcl_abortOnFatalError(***void***);** +**bool bcl_abortOnFatalError(**_void_**);** -**void bcl_setAbortOnFatalError(bool** *abrt***);** +**void bcl_setAbortOnFatalError(bool** _abrt_**);** -**void bcl_gc(***void***);** +**void bcl_gc(**_void_**);** ## Contexts @@ -72,29 +72,29 @@ other. This allows more than one client to use bcl(3) in the same program. **typedef struct BclCtxt\* BclContext;** -**BclContext bcl_ctxt_create(***void***);** +**BclContext bcl_ctxt_create(**_void_**);** -**void bcl_ctxt_free(BclContext** *ctxt***);** +**void bcl_ctxt_free(BclContext** _ctxt_**);** -**BclError bcl_pushContext(BclContext** *ctxt***);** +**BclError bcl_pushContext(BclContext** _ctxt_**);** -**void bcl_popContext(***void***);** +**void bcl_popContext(**_void_**);** -**BclContext bcl_context(***void***);** +**BclContext bcl_context(**_void_**);** -**void bcl_ctxt_freeNums(BclContext** *ctxt***);** +**void bcl_ctxt_freeNums(BclContext** _ctxt_**);** -**size_t bcl_ctxt_scale(BclContext** *ctxt***);** +**size_t bcl_ctxt_scale(BclContext** _ctxt_**);** -**void bcl_ctxt_setScale(BclContext** *ctxt***, size_t** *scale***);** +**void bcl_ctxt_setScale(BclContext** _ctxt_**, size_t** _scale_**);** -**size_t bcl_ctxt_ibase(BclContext** *ctxt***);** +**size_t bcl_ctxt_ibase(BclContext** _ctxt_**);** -**void bcl_ctxt_setIbase(BclContext** *ctxt***, size_t** *ibase***);** +**void bcl_ctxt_setIbase(BclContext** _ctxt_**, size_t** _ibase_**);** -**size_t bcl_ctxt_obase(BclContext** *ctxt***);** +**size_t bcl_ctxt_obase(BclContext** _ctxt_**);** -**void bcl_ctxt_setObase(BclContext** *ctxt***, size_t** *obase***);** +**void bcl_ctxt_setObase(BclContext** _ctxt_**, size_t** _obase_**);** ## Errors @@ -102,7 +102,7 @@ These items allow clients to handle errors. **typedef enum BclError BclError;** -**BclError bcl_err(BclNumber** *n***);** +**BclError bcl_err(BclNumber** _n_**);** ## Numbers @@ -111,71 +111,71 @@ numbers managed by bcl(3). **typedef struct { size_t i; } BclNumber;** -**BclNumber bcl_num_create(***void***);** +**BclNumber bcl_num_create(**_void_**);** -**void bcl_num_free(BclNumber** *n***);** +**void bcl_num_free(BclNumber** _n_**);** -**bool bcl_num_neg(BclNumber** *n***);** +**bool bcl_num_neg(BclNumber** _n_**);** -**void bcl_num_setNeg(BclNumber** *n***, bool** *neg***);** +**void bcl_num_setNeg(BclNumber** _n_**, bool** _neg_**);** -**size_t bcl_num_scale(BclNumber** *n***);** +**size_t bcl_num_scale(BclNumber** _n_**);** -**BclError bcl_num_setScale(BclNumber** *n***, size_t** *scale***);** +**BclError bcl_num_setScale(BclNumber** _n_**, size_t** _scale_**);** -**size_t bcl_num_len(BclNumber** *n***);** +**size_t bcl_num_len(BclNumber** _n_**);** ## Conversion These items allow clients to convert numbers into and from strings and integers. -**BclNumber bcl_parse(const char \*restrict** *val***);** +**BclNumber bcl_parse(const char \*restrict** _val_**);** -**char\* bcl_string(BclNumber** *n***);** +**char\* bcl_string(BclNumber** _n_**);** -**BclError bcl_bigdig(BclNumber** *n***, BclBigDig \****result***);** +**BclError bcl_bigdig(BclNumber** _n_**, BclBigDig \***_result_**);** -**BclNumber bcl_bigdig2num(BclBigDig** *val***);** +**BclNumber bcl_bigdig2num(BclBigDig** _val_**);** ## Math These items allow clients to run math on numbers. -**BclNumber bcl_add(BclNumber** *a***, BclNumber** *b***);** +**BclNumber bcl_add(BclNumber** _a_**, BclNumber** _b_**);** -**BclNumber bcl_sub(BclNumber** *a***, BclNumber** *b***);** +**BclNumber bcl_sub(BclNumber** _a_**, BclNumber** _b_**);** -**BclNumber bcl_mul(BclNumber** *a***, BclNumber** *b***);** +**BclNumber bcl_mul(BclNumber** _a_**, BclNumber** _b_**);** -**BclNumber bcl_div(BclNumber** *a***, BclNumber** *b***);** +**BclNumber bcl_div(BclNumber** _a_**, BclNumber** _b_**);** -**BclNumber bcl_mod(BclNumber** *a***, BclNumber** *b***);** +**BclNumber bcl_mod(BclNumber** _a_**, BclNumber** _b_**);** -**BclNumber bcl_pow(BclNumber** *a***, BclNumber** *b***);** +**BclNumber bcl_pow(BclNumber** _a_**, BclNumber** _b_**);** -**BclNumber bcl_lshift(BclNumber** *a***, BclNumber** *b***);** +**BclNumber bcl_lshift(BclNumber** _a_**, BclNumber** _b_**);** -**BclNumber bcl_rshift(BclNumber** *a***, BclNumber** *b***);** +**BclNumber bcl_rshift(BclNumber** _a_**, BclNumber** _b_**);** -**BclNumber bcl_sqrt(BclNumber** *a***);** +**BclNumber bcl_sqrt(BclNumber** _a_**);** -**BclError bcl_divmod(BclNumber** *a***, BclNumber** *b***, BclNumber \****c***, BclNumber \****d***);** +**BclError bcl_divmod(BclNumber** _a_**, BclNumber** _b_**, BclNumber \***_c_**, BclNumber \***_d_**);** -**BclNumber bcl_modexp(BclNumber** *a***, BclNumber** *b***, BclNumber** *c***);** +**BclNumber bcl_modexp(BclNumber** _a_**, BclNumber** _b_**, BclNumber** _c_**);** ## Miscellaneous These items are miscellaneous. -**void bcl_zero(BclNumber** *n***);** +**void bcl_zero(BclNumber** _n_**);** -**void bcl_one(BclNumber** *n***);** +**void bcl_one(BclNumber** _n_**);** -**ssize_t bcl_cmp(BclNumber** *a***, BclNumber** *b***);** +**ssize_t bcl_cmp(BclNumber** _a_**, BclNumber** _b_**);** -**BclError bcl_copy(BclNumber** *d***, BclNumber** *s***);** +**BclError bcl_copy(BclNumber** _d_**, BclNumber** _s_**);** -**BclNumber bcl_dup(BclNumber** *s***);** +**BclNumber bcl_dup(BclNumber** _s_**);** ## Pseudo-Random Number Generator @@ -190,30 +190,30 @@ generator in bcl(3). **typedef unsigned long BclRandInt;** -**BclNumber bcl_irand(BclNumber** *a***);** +**BclNumber bcl_irand(BclNumber** _a_**);** -**BclNumber bcl_frand(size_t** *places***);** +**BclNumber bcl_frand(size_t** _places_**);** -**BclNumber bcl_ifrand(BclNumber** *a***, size_t** *places***);** +**BclNumber bcl_ifrand(BclNumber** _a_**, size_t** _places_**);** -**BclError bcl_rand_seedWithNum(BclNumber** *n***);** +**BclError bcl_rand_seedWithNum(BclNumber** _n_**);** -**BclError bcl_rand_seed(unsigned char** *seed***[***BC_SEED_SIZE***]);** +**BclError bcl_rand_seed(unsigned char** _seed_**[**_BC_SEED_SIZE_**]);** -**void bcl_rand_reseed(***void***);** +**void bcl_rand_reseed(**_void_**);** -**BclNumber bcl_rand_seed2num(***void***);** +**BclNumber bcl_rand_seed2num(**_void_**);** -**BclRandInt bcl_rand_int(***void***);** +**BclRandInt bcl_rand_int(**_void_**);** -**BclRandInt bcl_rand_bounded(BclRandInt** *bound***);** +**BclRandInt bcl_rand_bounded(BclRandInt** _bound_**);** # DESCRIPTION bcl(3) is a library that implements arbitrary-precision decimal math, as [standardized by POSIX][1] in bc(1). -bcl(3) is async-signal-safe if **bcl_handleSignal(***void***)** is used +bcl(3) is async-signal-safe if **bcl_handleSignal(**_void_**)** is used properly. (See the **SIGNAL HANDLING** section.) All of the items in its interface are described below. See the documentation for @@ -221,7 +221,7 @@ each function for what each function can return. ## Signals -**void bcl_handleSignal(***void***)** +**void bcl_handleSignal(**_void_**)** : An async-signal-safe function that can be called from a signal handler. If called from a signal handler on the same thread as any executing bcl(3) @@ -230,26 +230,26 @@ each function for what each function can return. *not* executing any bcl(3) functions while any bcl(3) functions are executing. - If execution *is* interrupted, **bcl_handleSignal(***void***)** does *not* + If execution *is* interrupted, **bcl_handleSignal(**_void_**)** does *not* return to its caller. See the **SIGNAL HANDLING** section. -**bool bcl_running(***void***)** +**bool bcl_running(**_void_**)** : An async-signal-safe function that can be called from a signal handler. It will return **true** if any bcl(3) procedures are running, which means it is - safe to call **bcl_handleSignal(***void***)**. Otherwise, it returns + safe to call **bcl_handleSignal(**_void_**)**. Otherwise, it returns **false**. See the **SIGNAL HANDLING** section. ## Setup -**BclError bcl_init(***void***)** +**BclError bcl_init(**_void_**)** : Initializes this library. This function can be called multiple times, but - each call must be matched by a call to **bcl_free(***void***)**. This is to + each call must be matched by a call to **bcl_free(**_void_**)**. This is to make it possible for multiple libraries and applications to initialize bcl(3) without problem. @@ -261,7 +261,7 @@ each function for what each function can return. This function must be the first one clients call. Calling any other function without calling this one first is undefined behavior. -**void bcl_free(***void***)** +**void bcl_free(**_void_**)** : Decrements bcl(3)'s reference count and frees the data associated with it if the reference count is **0**. @@ -269,7 +269,7 @@ each function for what each function can return. This function must be the last one clients call. Calling this function before calling any other function is undefined behavior. -**bool bcl_abortOnFatalError(***void***)** +**bool bcl_abortOnFatalError(**_void_**)** : Queries and returns the current state of calling **abort()** on fatal errors. If **true** is returned, bcl(3) will cause a **SIGABRT** if a fatal @@ -277,7 +277,7 @@ each function for what each function can return. If activated, clients do not need to check for fatal errors. -**void bcl_setAbortOnFatalError(bool** *abrt***)** +**void bcl_setAbortOnFatalError(bool** _abrt_**)** : Sets the state of calling **abort()** on fatal errors. If *abrt* is **false**, bcl(3) will not cause a **SIGABRT** on fatal errors after the @@ -286,7 +286,7 @@ each function for what each function can return. If activated, clients do not need to check for fatal errors. -**void bcl_gc(***void***)** +**void bcl_gc(**_void_**)** : Garbage collects cached instances of arbitrary-precision numbers. This only frees the memory of numbers that are *not* in use, so it is safe to call at @@ -331,19 +331,19 @@ an argument. are meant to isolate the numbers used by different clients in the same application. -**BclContext bcl_ctxt_create(***void***)** +**BclContext bcl_ctxt_create(**_void_**)** : Creates a context and returns it. Returns **NULL** if there was an error. -**void bcl_ctxt_free(BclContext** *ctxt***)** +**void bcl_ctxt_free(BclContext** _ctxt_**)** : Frees *ctxt*, after which it is no longer valid. It is undefined behavior to attempt to use an invalid context. -**BclError bcl_pushContext(BclContext** *ctxt***)** +**BclError bcl_pushContext(BclContext** _ctxt_**)** : Pushes *ctxt* onto bcl(3)'s stack of contexts. *ctxt* must have been created - with **bcl_ctxt_create(***void***)**. + with **bcl_ctxt_create(**_void_**)**. If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this function can return: @@ -352,44 +352,44 @@ an argument. There *must* be a valid context to do any arithmetic. -**void bcl_popContext(***void***)** +**void bcl_popContext(**_void_**)** : Pops the current context off of the stack, if one exists. -**BclContext bcl_context(***void***)** +**BclContext bcl_context(**_void_**)** : Returns the current context, or **NULL** if no context exists. -**void bcl_ctxt_freeNums(BclContext** *ctxt***)** +**void bcl_ctxt_freeNums(BclContext** _ctxt_**)** : Frees all numbers in use that are associated with *ctxt*. It is undefined behavior to attempt to use a number associated with *ctxt* after calling this procedure unless such numbers have been created with - **bcl_num_create(***void***)** after calling this procedure. + **bcl_num_create(**_void_**)** after calling this procedure. -**size_t bcl_ctxt_scale(BclContext** *ctxt***)** +**size_t bcl_ctxt_scale(BclContext** _ctxt_**)** : Returns the **scale** for given context. -**void bcl_ctxt_setScale(BclContext** *ctxt***, size_t** *scale***)** +**void bcl_ctxt_setScale(BclContext** _ctxt_**, size_t** _scale_**)** : Sets the **scale** for the given context to the argument *scale*. -**size_t bcl_ctxt_ibase(BclContext** *ctxt***)** +**size_t bcl_ctxt_ibase(BclContext** _ctxt_**)** : Returns the **ibase** for the given context. -**void bcl_ctxt_setIbase(BclContext** *ctxt***, size_t** *ibase***)** +**void bcl_ctxt_setIbase(BclContext** _ctxt_**, size_t** _ibase_**)** : Sets the **ibase** for the given context to the argument *ibase*. If the argument *ibase* is invalid, it clamped, so an *ibase* of **0** or **1** is clamped to **2**, and any values above **36** are clamped to **36**. -**size_t bcl_ctxt_obase(BclContext** *ctxt***)** +**size_t bcl_ctxt_obase(BclContext** _ctxt_**)** : Returns the **obase** for the given context. -**void bcl_ctxt_setObase(BclContext** *ctxt***, size_t** *obase***)** +**void bcl_ctxt_setObase(BclContext** _ctxt_**, size_t** _obase_**)** : Sets the **obase** for the given context to the argument *obase*. @@ -400,7 +400,7 @@ an argument. : An **enum** of possible error codes. See the **ERRORS** section for a complete listing the codes. -**BclError bcl_err(BclNumber** *n***)** +**BclError bcl_err(BclNumber** _n_**)** : Checks for errors in a **BclNumber**. All functions that can return a **BclNumber** can encode an error in the number, and this function will @@ -419,7 +419,7 @@ All procedures in this section require a valid current context. exposed; the **BclNumber** handle is the only way clients can refer to instances of arbitrary-precision numbers. -**BclNumber bcl_num_create(***void***)** +**BclNumber bcl_num_create(**_void_**)** : Creates and returns a **BclNumber**. @@ -429,27 +429,27 @@ All procedures in this section require a valid current context. * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** -**void bcl_num_free(BclNumber** *n***)** +**void bcl_num_free(BclNumber** _n_**)** : Frees *n*. It is undefined behavior to use *n* after calling this function. -**bool bcl_num_neg(BclNumber** *n***)** +**bool bcl_num_neg(BclNumber** _n_**)** : Returns **true** if *n* is negative, **false** otherwise. -**void bcl_num_setNeg(BclNumber** *n***, bool** *neg***)** +**void bcl_num_setNeg(BclNumber** _n_**, bool** _neg_**)** : Sets *n*'s sign to *neg*, where **true** is negative, and **false** is positive. -**size_t bcl_num_scale(BclNumber** *n***)** +**size_t bcl_num_scale(BclNumber** _n_**)** : Returns the *scale* of *n*. The *scale* of a number is the number of decimal places it has after the radix (decimal point). -**BclError bcl_num_setScale(BclNumber** *n***, size_t** *scale***)** +**BclError bcl_num_setScale(BclNumber** _n_**, size_t** _scale_**)** : Sets the *scale* of *n* to the argument *scale*. If the argument *scale* is greater than the *scale* of *n*, *n* is extended. If the argument *scale* is @@ -462,7 +462,7 @@ All procedures in this section require a valid current context. * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** -**size_t bcl_num_len(BclNumber** *n***)** +**size_t bcl_num_len(BclNumber** _n_**)** : Returns the number of *significant decimal digits* in *n*. @@ -474,7 +474,7 @@ All procedures in this section consume the given **BclNumber** arguments that are not given to pointer arguments. See the **Consumption and Propagation** subsection below. -**BclNumber bcl_parse(const char \*restrict** *val***)** +**BclNumber bcl_parse(const char \*restrict** _val_**)** : Parses a number string according to the current context's **ibase** and returns the resulting number. @@ -491,7 +491,7 @@ subsection below. * **BCL_ERROR_PARSE_INVALID_STR** * **BCL_ERROR_FATAL_ALLOC_ERR** -**char\* bcl_string(BclNumber** *n***)** +**char\* bcl_string(BclNumber** _n_**)** : Returns a string representation of *n* according the the current context's **ibase**. The string is dynamically allocated and must be freed by the @@ -500,7 +500,7 @@ subsection below. *n* is consumed; it cannot be used after the call. See the **Consumption and Propagation** subsection below. -**BclError bcl_bigdig(BclNumber** *n***, BclBigDig \****result***)** +**BclError bcl_bigdig(BclNumber** _n_**, BclBigDig \***_result_**)** : Converts *n* into a **BclBigDig** and returns the result in the space pointed to by *result*. @@ -517,7 +517,7 @@ subsection below. *n* is consumed; it cannot be used after the call. See the **Consumption and Propagation** subsection below. -**BclNumber bcl_bigdig2num(BclBigDig** *val***)** +**BclNumber bcl_bigdig2num(BclBigDig** _val_**)** : Creates a **BclNumber** from *val*. @@ -537,7 +537,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_add(BclNumber** *a***, BclNumber** *b***)** +**BclNumber bcl_add(BclNumber** _a_**, BclNumber** _b_**)** : Adds *a* and *b* and returns the result. The *scale* of the result is the max of the *scale*s of *a* and *b*. @@ -554,7 +554,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_sub(BclNumber** *a***, BclNumber** *b***)** +**BclNumber bcl_sub(BclNumber** _a_**, BclNumber** _b_**)** : Subtracts *b* from *a* and returns the result. The *scale* of the result is the max of the *scale*s of *a* and *b*. @@ -571,7 +571,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_mul(BclNumber** *a***, BclNumber** *b***)** +**BclNumber bcl_mul(BclNumber** _a_**, BclNumber** _b_**)** : Multiplies *a* and *b* and returns the result. If *ascale* is the *scale* of *a* and *bscale* is the *scale* of *b*, the *scale* of the result is equal @@ -590,7 +590,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_div(BclNumber** *a***, BclNumber** *b***)** +**BclNumber bcl_div(BclNumber** _a_**, BclNumber** _b_**)** : Divides *a* by *b* and returns the result. The *scale* of the result is the *scale* of the current context. @@ -610,7 +610,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_mod(BclNumber** *a***, BclNumber** *b***)** +**BclNumber bcl_mod(BclNumber** _a_**, BclNumber** _b_**)** : Divides *a* by *b* to the *scale* of the current context, computes the modulus **a-(a/b)\*b**, and returns the modulus. @@ -630,7 +630,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_pow(BclNumber** *a***, BclNumber** *b***)** +**BclNumber bcl_pow(BclNumber** _a_**, BclNumber** _b_**)** : Calculates *a* to the power of *b* to the *scale* of the current context. *b* must be an integer, but can be negative. If it is negative, *a* must @@ -655,7 +655,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_lshift(BclNumber** *a***, BclNumber** *b***)** +**BclNumber bcl_lshift(BclNumber** _a_**, BclNumber** _b_**)** : Shifts *a* left (moves the radix right) by *b* places and returns the result. This is done in decimal. *b* must be an integer. @@ -675,7 +675,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_NON_INTEGER** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_rshift(BclNumber** *a***, BclNumber** *b***)** +**BclNumber bcl_rshift(BclNumber** _a_**, BclNumber** _b_**)** : Shifts *a* right (moves the radix left) by *b* places and returns the result. This is done in decimal. *b* must be an integer. @@ -695,7 +695,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_NON_INTEGER** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_sqrt(BclNumber** *a***)** +**BclNumber bcl_sqrt(BclNumber** _a_**)** : Calculates the square root of *a* and returns the result. The *scale* of the result is equal to the **scale** of the current context. @@ -713,7 +713,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_NEGATIVE** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclError bcl_divmod(BclNumber** *a***, BclNumber** *b***, BclNumber \****c***, BclNumber \****d***)** +**BclError bcl_divmod(BclNumber** _a_**, BclNumber** _b_**, BclNumber \***_c_**, BclNumber \***_d_**)** : Divides *a* by *b* and returns the quotient in a new number which is put into the space pointed to by *c*, and puts the modulus in a new number which @@ -735,7 +735,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_MATH_DIVIDE_BY_ZERO** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_modexp(BclNumber** *a***, BclNumber** *b***, BclNumber** *c***)** +**BclNumber bcl_modexp(BclNumber** _a_**, BclNumber** _b_**, BclNumber** _c_**)** : Computes a modular exponentiation where *a* is the base, *b* is the exponent, and *c* is the modulus, and returns the result. The *scale* of the @@ -759,20 +759,20 @@ All procedures in this section can return the following errors: ## Miscellaneous -**void bcl_zero(BclNumber** *n***)** +**void bcl_zero(BclNumber** _n_**)** : Sets *n* to **0**. -**void bcl_one(BclNumber** *n***)** +**void bcl_one(BclNumber** _n_**)** : Sets *n* to **1**. -**ssize_t bcl_cmp(BclNumber** *a***, BclNumber** *b***)** +**ssize_t bcl_cmp(BclNumber** _a_**, BclNumber** _b_**)** : Compares *a* and *b* and returns **0** if *a* and *b* are equal, **<0** if *a* is less than *b*, and **>0** if *a* is greater than *b*. -**BclError bcl_copy(BclNumber** *d***, BclNumber** *s***)** +**BclError bcl_copy(BclNumber** _d_**, BclNumber** _s_**)** : Copies *s* into *d*. @@ -783,7 +783,7 @@ All procedures in this section can return the following errors: * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_dup(BclNumber** *s***)** +**BclNumber bcl_dup(BclNumber** _s_**)** : Creates and returns a new **BclNumber** that is a copy of *s*. @@ -810,8 +810,8 @@ remaining fairly portable. If necessary, the PRNG can be reseeded with one of the following functions: * **bcl_rand_seedWithNum(BclNumber)** -* **bcl_rand_seed(unsigned char[BC_SEED_SIZE])** -* **bcl_rand_reseed(***void***)** +* **bcl_rand_seed(unsigned char[**_BC_SEED_SIZE_**])** +* **bcl_rand_reseed(**_void_**)** The following items allow clients to use the pseudo-random number generator. All procedures require a valid current context. @@ -833,7 +833,7 @@ procedures require a valid current context. : An unsigned integer type returned by bcl(3)'s random number generator. -**BclNumber bcl_irand(BclNumber** *a***)** +**BclNumber bcl_irand(BclNumber** _a_**)** : Returns a random number that is not larger than *a* in a new number. If *a* is **0** or **1**, the new number is equal to **0**. The bound is unlimited, @@ -857,7 +857,7 @@ procedures require a valid current context. * **BCL_ERROR_MATH_NON_INTEGER** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_frand(size_t** *places***)** +**BclNumber bcl_frand(size_t** _places_**)** : Returns a random number between **0** (inclusive) and **1** (exclusive) that has *places* decimal digits after the radix (decimal point). There are no @@ -871,7 +871,7 @@ procedures require a valid current context. * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclNumber bcl_ifrand(BclNumber** *a***, size_t** *places***)** +**BclNumber bcl_ifrand(BclNumber** _a_**, size_t** _places_**)** : Returns a random number less than *a* with *places* decimal digits after the radix (decimal point). There are no limits on *a* or *places*. @@ -892,7 +892,7 @@ procedures require a valid current context. * **BCL_ERROR_MATH_NON_INTEGER** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclError bcl_rand_seedWithNum(BclNumber** *n***)** +**BclError bcl_rand_seedWithNum(BclNumber** _n_**)** : Seeds the PRNG with *n*. @@ -906,11 +906,11 @@ procedures require a valid current context. * **BCL_ERROR_INVALID_NUM** * **BCL_ERROR_INVALID_CONTEXT** - Note that if **bcl_rand_seed2num(***void***)** or + Note that if **bcl_rand_seed2num(**_void_**)** or **bcl_rand_seed2num_err(BclNumber)** are called right after this function, they are not guaranteed to return a number equal to *n*. -**BclError bcl_rand_seed(unsigned char** *seed***[***BC_SEED_SIZE***])** +**BclError bcl_rand_seed(unsigned char** _seed_**[**_BC_SEED_SIZE_**])** : Seeds the PRNG with the bytes in *seed*. @@ -919,14 +919,14 @@ procedures require a valid current context. * **BCL_ERROR_INVALID_CONTEXT** -**void bcl_rand_reseed(***void***)** +**void bcl_rand_reseed(**_void_**)** : Reseeds the PRNG with the default reseeding behavior. First, it attempts to read data from **/dev/urandom** and falls back to **libc**'s **rand()**. This procedure cannot fail. -**BclNumber bcl_rand_seed2num(***void***)** +**BclNumber bcl_rand_seed2num(**_void_**)** : Returns the current seed of the PRNG as a **BclNumber**. @@ -938,13 +938,13 @@ procedures require a valid current context. * **BCL_ERROR_INVALID_CONTEXT** * **BCL_ERROR_FATAL_ALLOC_ERR** -**BclRandInt bcl_rand_int(***void***)** +**BclRandInt bcl_rand_int(**_void_**)** : Returns a random integer between **0** and **BC_RAND_MAX** (inclusive). This procedure cannot fail. -**BclRandInt bcl_rand_bounded(BclRandInt** *bound***)** +**BclRandInt bcl_rand_bounded(BclRandInt** _bound_**)** : Returns a random integer between **0** and *bound* (exclusive). Bias is removed before returning the integer. @@ -1062,7 +1062,7 @@ codes defined in **BclError**. The complete list of codes is the following: # ATTRIBUTES -When **bcl_handleSignal(***void***)** is used properly, bcl(3) is +When **bcl_handleSignal(**_void_**)** is used properly, bcl(3) is async-signal-safe. bcl(3) is *MT-Unsafe*: it is unsafe to call any functions from more than one @@ -1140,16 +1140,16 @@ be hit. # SIGNAL HANDLING -If a signal handler calls **bcl_handleSignal(***void***)** from the same thread +If a signal handler calls **bcl_handleSignal(**_void_**)** from the same thread that there are bcl(3) functions executing in, it will cause all execution to stop as soon as possible, interrupting long-running calculations, if necessary and cause the function that was executing to return. If possible, the error code **BC_ERROR_SIGNAL** is returned. -If execution *is* interrupted, **bcl_handleSignal(***void***)** does *not* +If execution *is* interrupted, **bcl_handleSignal(**_void_**)** does *not* return to its caller. -It is undefined behavior if **bcl_handleSignal(***void***)** is called from +It is undefined behavior if **bcl_handleSignal(**_void_**)** is called from a thread that is not executing bcl(3) functions, if bcl(3) functions are executing. |