home | help 
Tcl_ByteArrayObj(3)	     Tcl Library Procedures	     Tcl_ByteArrayObj(3)

________________________________________________________________________________

NAME
     Tcl_NewByteArrayObj,   Tcl_SetByteArrayObj,  Tcl_GetBytesFromObj,	Tcl_Get-
     ByteArrayFromObj, Tcl_SetByteArrayLength - manipulate a Tcl value as an ar-
     ray of bytes

SYNOPSIS
     #include <tcl.h>

     Tcl_Obj *
     Tcl_NewByteArrayObj(bytes, numBytes)

     Tcl_SetByteArrayObj(objPtr, bytes, numBytes)

     unsigned char *								 2
     Tcl_GetBytesFromObj(interp, objPtr, numBytesPtr)				 2

     unsigned char *
     Tcl_GetByteArrayFromObj(objPtr, numBytesPtr)

     unsigned char *
     Tcl_SetByteArrayLength(objPtr, numBytes)

ARGUMENTS
     const unsigned char *bytes (in)		    The array of bytes	used  to
						    initialize or set a byte-ar-
						    ray  value. May be NULL even
						    if numBytes is non-zero.

     Tcl_Size numBytes (in)			    The number of bytes  in  the
						    array.

     Tcl_Obj *objPtr (in/out)			    For     Tcl_SetByteArrayObj,
						    this points to  an	unshared
						    value to be overwritten by a
						    byte-array	  value.     For
						    Tcl_GetBytesFromObj,
						    Tcl_GetByteArrayFromObj  and
						    Tcl_SetByteArrayLength, this
						    points  to	the  value  from
						    which to extract an array of
						    bytes.

     Tcl_Interp *interp (in)			    Interpreter to use for error
						    reporting.

     Tcl_Size | int *numBytesPtr (out)		    Points to  space  where  the
						    number of bytes in the array
						    may   be  written.	 May  be
						    (Tcl_Size  *)NULL  when  not
						    used.  If  it  points  to  a
						    variable which type  is  not
						    Tcl_Size, a compiler warning
						    will  be generated.  If your
						    extensions is compiled  with
						    -DTCL_8_API,  this	function
						    will return  NULL  for  byte
						    arrays  larger  than INT_MAX
						    (which should trigger proper
						    error-handling),   otherwise
						    expect it to crash.
________________________________________________________________________________

DESCRIPTION
     N.B.  Refer  to the Tcl_UniChar documentation page for a description of the
     TUTF-8 encoding and related terms referenced here.

     These routines are used to create, modify, store,	transfer,  and	retrieve
     arbitrary binary data in Tcl values.  Specifically, data that can be repre-
     sented  as a sequence of arbitrary byte values is supported.  This includes
     data read from binary channels, values created by the binary  command,  en-
     crypted data, or other information representable as a finite byte sequence.

     A	byte is an 8-bit quantity with no inherent meaning.  When the 8 bits are
     interpreted as an integer value, the range of possible values  is	(0-255).
     The  C  type best suited to store a byte is the unsigned char.  An unsigned
     char array of size N stores an arbitrary binary value of size N bytes.   We
     call  this representation a byte-array.  Here we document the routines that
     allow us to operate on Tcl values as byte-arrays.

     All Tcl values must correspond to a string representation.  When a byte-ar-
     ray value must be processed as a string, the sequence of N bytes is  trans-
     formed  into  the	corresponding  sequence of N characters, where each byte
     value transforms to the same character codepoint value in the range (U+0000
     - U+00FF).  Obtaining the string representation of a byte-array  value  (by
     calling Tcl_GetStringFromObj) produces this string in TUTF-8 encoding.

     Tcl_NewByteArrayObj and Tcl_SetByteArrayObj create a new value or overwrite
     an  existing  unshared  value,  respectively, to hold a byte-array value of
     numBytes bytes.  When a caller passes a non-NULL value of	bytes,	it  must
     point  to memory from which numBytes bytes can be read.  These routines al-
     locate numBytes bytes of memory, copy numBytes bytes from	bytes  into  it,
     and  keep the result in the internal representation of the new or overwrit-
     ten value.  When the caller passes a NULL value of bytes, the data  copying
     step  is skipped, and the bytes stored in the value are undefined.  A bytes
     value of NULL is useful only when the caller will arrange	to  write  known
     contents  into  the byte-array through a pointer retrieved by a call to one
     of the routines explained below.  Tcl_NewByteArrayObj returns a pointer  to
     the  created  value  with	a  reference count of zero.  Tcl_SetByteArrayObj
     overwrites and invalidates any old contents of the unshared objPtr  as  ap-
     propriate,  and  keeps  its  reference count (0 or 1) unchanged.  The value
     produced by these routines has no string representation.  Any memory  allo-
     cation failure may cause a panic.

     Tcl_GetBytesFromObj  performs the opposite function of Tcl_SetByteArrayObj,
     providing access to read a byte-array from a Tcl value that was  previously
     written  into  it.   When objPtr is a value previously produced by Tcl_New-
     ByteArrayObj or Tcl_SetByteArrayObj,  then  Tcl_GetBytesFromObj  returns  a
     pointer  to the byte-array kept in the value's internal representation.  If
     the caller provides a non-NULL value for numBytesPtr, it must point to mem-
     ory where Tcl_GetBytesFromObj can write the number of bytes in the  value's
     internal  byte-array.   With both pieces of information, the caller is able
     to retrieve any information about the contents of that byte-array	that  it
     seeks.   When  objPtr  does  not  already	contain  an internal byte-array,
     Tcl_GetBytesFromObj will try to create one from the value's  string  repre-
     sentation.  Any string value that does not include any character codepoints
     outside the range (U+0000 - U+00FF) will successfully translate to a unique
     byte-array  value.  With the created byte-array, the routine returns as be-
     fore.  For any string representation which does contain a forbidden charac-
     ter codepoint, the conversion fails, and Tcl_GetBytesFromObj  returns  NULL
     to  signal  that  failure.  On failure, nothing will be written to numByte-
     sPtr, and if the interp argument is non-NULL, then error messages and codes
     are left in it recording the error.

     Tcl_GetByteArrayFromObj performs exactly the same function as Tcl_GetBytes-
     FromObj does when called with the interp argument passed  the  value  NULL.
     This is incompatible with the way Tcl_GetByteArrayFromObj functioned in Tcl
     8.  Tcl_GetBytesFromObj is the more capable interface and should usually be
     favored for use over Tcl_GetByteArrayFromObj.

     On  success,  both Tcl_GetBytesFromObj and Tcl_GetByteArrayFromObj return a
     pointer into the internal representation of a Tcl_Obj.  That  pointer  must
     not  be  freed by the caller, and should not be retained for use beyond the
     known time the internal representation of the value has not been disturbed.
     The pointer may be used to overwrite the byte contents of the internal rep-
     resentation, so long as the value is unshared and any string representation
     is invalidated.

     On success, both Tcl_GetBytesFromObj and Tcl_GetByteArrayFromObj write  the
     number  of  bytes in the byte-array value of objPtr to the space pointed to
     by numBytesPtr.  This space may be of type Tcl_Size or of type int.  It  is
     recommended that callers provide a Tcl_Size space for this purpose.  If the
     caller provides only an int space and the number of bytes in the byte-array
     value of objPtr is greater than INT_MAX, the routine will fail due to being
     unable  to correctly report the byte-array size to the caller.  The ability
     to provide an int space is best considered a migration  aid  for  codebases
     constrained to continue operating with Tcl releases older than 9.0.

     Tcl_SetByteArrayLength  enables a caller to change the size of a byte-array
     in the internal representation of an unshared  objPtr  to	become	numBytes
     bytes.   This is most often useful after the bytes of the internal byte-ar-
     ray have been directly overwritten and it has been discovered that the  re-
     quired  size  differs  from  the  first  estimate	used  in the allocation.
     Tcl_SetByteArrayLength returns a pointer to the  resized  byte-array.   Be-
     cause resizing the byte-array changes the internal representation, Tcl_Set-
     ByteArrayLength  also  invalidates any string representation in objPtr.  If
     resizing grows the byte-array, the new byte values are undefined.	 If  ob-
     jPtr  does  not  already possess an internal byte-array, one is produced in
     the same way that Tcl_GetBytesFromObj does, also returning  NULL  when  any
     characters  of  the  value in objPtr (up to numBytes of them) are not valid
     bytes.

REFERENCE COUNT MANAGEMENT
     Tcl_NewByteArrayObj always  returns  a  zero-reference  object,  much  like
     Tcl_NewObj.

     Tcl_SetByteArrayObj  and Tcl_SetByteArrayLength do not modify the reference
     count of their objPtr arguments, but do require  that  the  object  be  un-
     shared.

     Tcl_GetBytesFromObj and Tcl_GetByteArrayFromObj do not modify the reference
     count of objPtr; they only read.

SEE ALSO
     Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount

KEYWORDS
     value, binary data, byte array, utf, unicode

Tcl				       9.0		     Tcl_ByteArrayObj(3)
home | help