Tcl Source Code

View Ticket
Login
Ticket UUID: 07000bd237c021d5bf7bcc721a6ab3570ecc4f08
Title: Bignum documentation needs to be clarified w.r.t mp_int handling
Type: Bug Created on: 2025-11-10 16:57:22
Submitter: apnadkarni Assigned to: nobody
Subsystem: 56. LibTomMath Severity: Minor
Priority: 5 Medium Last modified: 2026-01-14 14:56:51
Status: Open Closed by: nobody
Resolution: None Closed on:
Version:
Description:

The documentation for Tcl_{Set,Get,Take}BigNum needs to clarified with respect to handling of mp_int memory. At least,

  • Tcl_SetBignumObj should clarify that the passed mp_int is cleared by Tcl and will not hold it original value

  • Tcl_{Get,Take}BignumFromObj - mp_clear needs to be called on the returned mp_int values to free memory.

User Comments:
cdubois added on 2026-01-12 03:39:06:
Thanks for flagging this. Making the ownership/lifetime contract for mp_int explicit is important to prevent leaks and accidental misuse.

I agree the docs should be strict here. I will cross-check the current implementation (including Tcl_TakeBignumFromObj behaviour for shared vs unshared objects) and then propose a documentation patch.

Proposed doc clarifications (subject to confirming the implementation):

- Tcl_SetBignumObj: clarify whether the function clears/consumes the supplied mp_int (i.e., callers must treat it as cleared and not rely on its prior value after the call).

- Tcl_GetBignumFromObj / Tcl_TakeBignumFromObj: clarify whether the caller must call mp_clear on the mp_int they receive/populate to release internal allocations, and what postconditions apply to the source object in the Take case.

I can also add a minimal code snippet illustrating the correct cleanup pattern.

apnadkarni added on 2026-01-14 14:56:51:
@cdubois, Great, a documentation patch would be greatly appreciated. It is really quite confusing as it stands.