Utility ownership C reference

See Allocation, strings and interned names for lifetime and failure policy.

void *Rbc_Calloc(size_t nElem, size_t size)

Allocate a zero-initialized Tcl-owned block.

Check nElem * size for size_t overflow and panic on overflow. A zero logical size allocates one zero byte, preserving a non-NULL ckalloc-style result. The caller releases the allocation with ckfree. Allocation failure is fatal, not a recoverable NULL result.

Parameters:
  • nElem – [in] Logical element count; multiplication by size is checked for size_t overflow.

  • size – [in] Bytes per element; either zero argument still yields a one-byte zeroed allocation.

char *Rbc_Strdup(const char *ptr)

Copy a non-NULL NUL-terminated string into Tcl-owned storage.

Borrow the input and copy through its first NUL, including the terminator. The caller releases the result with ckfree, not libc free. Uses ckalloc failure policy; this is not a binary-data or length-delimited copy.

Parameters:
  • ptr – [in] Borrowed non-NULL NUL-terminated source; the result owns a separate copy through its first NUL.

Rbc_Uid Rbc_GetUid(const char *string)

Acquire a reference to an interned NUL-terminated name.

Equal strings share a stable pointer while references remain. Do not modify the returned characters despite the historical mutable typedef. Pair each acquisition with Rbc_FreeUid. The process-static table is neither interpreter local nor protected by locks; this is not a cross-thread sharing API.

Parameters:
  • string – [in] Borrowed non-NULL NUL-terminated spelling; acquires one reference to the interned result.

void Rbc_FreeUid(Rbc_Uid uid)

Release one acquired UID reference, deleting its key at zero.

Require a still-valid UID acquired through Rbc_GetUid. Do not free the string with ckfree or release a merely borrowed Rbc_FindUid result. Unknown valid strings produce a stderr diagnostic; NULL or dangling pointers are not safe.

Parameters:
  • uid – [inout] Live acquired UID reference to release; the string becomes invalid if this was its final reference.

Rbc_Uid Rbc_FindUid(char *string)

Borrow an existing interned name without increasing its reference count.

Return NULL when absent. The pointer remains valid only while an acquiring owner keeps a reference. Lookup lazily initializes the shared table but does not insert a missing name. Use Rbc_GetUid when independent ownership is needed.

Parameters:
  • string – [in] Borrowed non-NULL NUL-terminated lookup spelling; bytes are not modified and no reference is acquired.

char *Rbc_Itoa(int value)

Format an int into borrowed shared scratch storage.

Return a pointer to the same process-static buffer used by Rbc_Utoa and Rbc_Dtoa. A subsequent call to any of them overwrites it. Do not free or retain it without copying; concurrent calls are not synchronized.

Parameters:
  • value – [in] Signed integer to format in decimal; the returned shared buffer is overwritten by the next numeric formatting call.

char *Rbc_Utoa(unsigned int value)

Format an unsigned int into borrowed shared scratch storage.

Shares the buffer and overwrite/threading restrictions of Rbc_Itoa. The returned decimal string is not caller-owned.

Parameters:
  • value – [in] Unsigned integer to format in decimal; no separate result allocation is made.

char *Rbc_Dtoa(Tcl_Interp *interp, double value)

Format a double through Tcl_PrintDouble into shared scratch storage.

Borrow interp. Shares the buffer with Rbc_Itoa and Rbc_Utoa; copy the result before another formatting call and never free the returned pointer.

Parameters:
  • interp – [in] Borrowed Tcl numeric-formatting context passed to Tcl_PrintDouble; not retained.

  • value – [in] Double to format using Tcl rules into the shared numeric scratch buffer.

void Rbc_DStringAppendElements(Tcl_DString *dsPtr, ...)

Append NUL-terminated strings as Tcl list elements.

Borrow the initialized DString and arguments, ending varargs with a NULL string pointer. Tcl_DStringAppendElement supplies list quoting. Existing contents remain; the caller owns the DString and eventually frees it.

Parameters:
  • dsPtr – [inout] Required initialized caller-owned DString; quoted list elements are appended without clearing it.

  • ... – [in] Borrowed NUL-terminated element strings, terminated by a NULL string pointer; no lengths are supplied.

void Rbc_AppendResultStrings(Tcl_Interp *interp, ...)

Append raw string fragments to a duplicate of the interpreter result.

Borrow interp and NUL-terminated arguments ending with a NULL string pointer. Duplicate the current object before appending, then install and release the local reference. Shared original objects remain unchanged. Fragments are not list-quoted, and this helper does not set structured Tcl error metadata.

Parameters:
  • interp – [inout] Borrowed interpreter whose result is copied and replaced; see Interpreter arguments.

  • ... – [in] Borrowed NUL-terminated raw fragments, terminated by a NULL string pointer; fragments are not list-quoted.

void Rbc_InitHexTable(char *table)

Set hexadecimal digit entries in a caller-owned character table.

Require storage addressable by the character codes for 0-9, a-f and A-F (typically 256 entries). Set only those slots to 0 through 15. All other slots keep their previous contents; callers initialize invalid-digit sentinels.

Parameters:
  • table – [inout] Caller-owned char array addressable at every hexadecimal digit character code; only those slots are overwritten.

double Rbc_RandomDouble(void)

Return a rand-derived value in the half-open interval [0, 1).

Consumes the C library PRNG state and does not seed it. No interpreter-local state, reproducibility across platforms or cryptographic quality is promised.

Ordering, stdio and fatal diagnostics

group rbcUtil helper contracts

Shared implementation helpers and legacy adapters.

Functions

void strtolower(char *s)

Lowercase a writable NUL-terminated byte string in place.

This fallback does not perform Tcl Unicode case conversion or change byte length.

Parameters:
  • s – [inout] Required writable byte string; each unsigned byte is converted with the current C locale tolower mapping.

int strcasecmp(const char *s1, const char *s2)

Compare byte strings using the fallback case-folding table.

Returns zero for equality, negative when s1 sorts before s2, or positive when s1 sorts after s2. Uses the fixed 256-entry table, not Tcl Unicode or the current C locale; neither input is modified. This fallback is compiled only when the platform lacks HAVE_STRCASECMP.

Parameters:
  • s1 – [in] Borrowed first byte string; readable through its terminating NUL.

  • s2 – [in] Borrowed second byte string with the same readability requirement.

int strncasecmp(const char *s1, const char *s2, size_t length)

Compare byte strings using the fallback case-folding table.

Returns zero for equality, negative when s1 sorts before s2, or positive when s1 sorts after s2. Uses the fixed 256-entry table, not Tcl Unicode or the current C locale; neither input is modified. This fallback is compiled only when the platform lacks HAVE_STRCASECMP.

Parameters:
  • s1 – [in] Borrowed first byte string; readable through its terminating NUL or the length bound.

  • s2 – [in] Borrowed second byte string with the same readability requirement.

  • length – [in] Maximum bytes compared; zero returns equality without reading either input.

int Rbc_DictionaryCompare(char *left, char *right)

Compare names using numeric runs and case-insensitive Unicode letters.

Parameters:
  • left – Borrowed NUL-terminated Tcl UTF string; not modified.

  • right – Borrowed NUL-terminated Tcl UTF string; not modified.

Returns:

Negative, zero or positive according to ordering; magnitude is unspecified. Compares digit runs without conversion to a bounded integer, skipping commas encountered while advancing those runs. More leading zeros sort later as a secondary difference. Uppercase sorts before lowercase when primary values match; the first secondary difference is retained. This is a legacy comparator, not locale collation or Unicode normalization. Allocates no storage.

void Rbc_Assert(char *testExpr, char *fileName, int lineNumber)

Report a failed internal assertion and abort the process.

Parameters:
  • testExpr – Borrowed expression text.

  • fileName – Borrowed source filename.

  • lineNumber – Source line of the assertion. Available only without NDEBUG. Writes and flushes stderr, optionally also reports through PurifyPrintf under WINDEBUG, then aborts. Does not return a Tcl error or perform normal resource cleanup.

void Rbc_Panic(char *format, ...)

Print a fatal formatted diagnostic and abort the process.

Parameters:
  • format – Borrowed printf-style format followed by matching arguments. Writes to stderr, appends a newline, flushes and calls abort. Never returns; this is not a recoverable Tcl error path and does not unwind resource owners.

FILE *Rbc_OpenUtfFile(char *fileName, char *mode)

Open a Tcl UTF filename through the C stdio interface.

Parameters:
  • fileName – Borrowed NUL-terminated Tcl UTF filename.

  • mode – Borrowed fopen mode string.

Returns:

FILE pointer owned by the caller, or NULL when fopen fails. Converts the filename using Tcl’s default external encoding and frees the temporary conversion buffer before returning. Close successful results with fclose. Does not use Tcl channels, VFS dispatch or an interpreter diagnostic; encoding conversion does not guarantee every filename is representable.