Source Files

• portions of tclBinary.c

Public Interface

• Tcl_NewByteArrayObj
• Tcl_DbNewByteArrayObj
• Tcl_SetByteArrayObj
• Tcl_GetByteArrayFromObj
• Tcl_SetByteArrayLength

Private Interface

• TclAppendBytesToByteArray
• tclByteArrayType

Directly Depends On Public Interface Of

• Tcl_Obj System
• Panic
• UTF-8 String
• Allocation

Directly Depends On Private Interface of

• Tcl_Obj System

Discussion

The rest of the file implements the binary command.

The public routines have similar INT_MAX size limitations to other parts of Tcl.

The type is implemented by a pointer in the ptr1 field of the internalRep; that points to a ByteArray structure with the following declaration (NB: normative declaration is in the code).

typedef struct ByteArray {
    int used;			/* The number of bytes used in the byte
				 * array. */
    int allocated;		/* The amount of space actually allocated
				 * minus 1 byte. */
    unsigned char bytes[];	/* The array of bytes. The actual size of this
				 * field depends on the 'allocated' field
				 * above. */
} ByteArray;

The buffer is allocated contiguously with this structure, and is managed with the usual buffer growth strategy when appends are being done. However, it's also reasonably common for buffers to be shrunk. Because buffers can be reallocated, it is important for pointers to ByteArrays to be not kept by code other than the tclBinary.c core. It's also important to not assume that the pointer returned by Tcl_GetByteArrayFromObj or Tcl_SetByteArrayLength will never be switched out from under your feet.

On the other hand, it's a common pattern to get a buffer of the right size from an unshared bytearray object and to write into it to make the contents right. This is a supported usage pattern.