1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
'\"
'\" Copyright (c) 1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetBytesFromObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate a Tcl value as an array of bytes
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewByteArrayObj\fR(\fIbytes, numBytes\fR)
.sp
void
\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, numBytes\fR)
.sp
.VS TIP568
unsigned char *
\fBTcl_GetBytesFromObj\fR(\fIinterp, objPtr, numBytesPtr\fR)
.VE TIP568
.sp
unsigned char *
\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, numBytesPtr\fR)
.sp
unsigned char *
\fBTcl_SetByteArrayLength\fR(\fIobjPtr, numBytes\fR)
.SH ARGUMENTS
.AS "const unsigned char" *numBytesPtr in/out
.AP "const unsigned char" *bytes in
The array of bytes used to initialize or set a byte-array value. May be NULL
even if \fInumBytes\fR is non-zero.
.AP int numBytes in
The number of bytes in the array. It must be >= 0.
.AP Tcl_Obj *objPtr in/out
For \fBTcl_SetByteArrayObj\fR, this points to an unshared value to be
overwritten by a byte-array value. For \fBTcl_GetBytesFromObj\fR,
\fBTcl_GetByteArrayFromObj\fR and \fBTcl_SetByteArrayLength\fR, this points
to the value from which to extract an array of bytes.
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP "size_t | int" *numBytesPtr out
Points to space where the number of bytes in the array may be written.
Caller may pass NULL when it does not need this information.
.BE
.SH DESCRIPTION
.PP
These procedures are used to create, modify, and read Tcl byte-array values
from C code. Byte-array values are typically used to hold the
results of binary IO operations, data structures created with the
\fBbinary\fR command, or other information, such as encrypted data,
represented as arbitrary binary data.
A byte-array is an array of 8-bit quantities (the integer range 0 - 255)
with no inherent meaning. When a byte-array value must be processed as
a string, the sequence of \fBN\fR bytes is transformed into the corresponding
sequence of \fBN\fR 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
\fBTcl_GetStringFromObj\fR) produces this string in Tcl's usual
Modified UTF-8 encoding.
.PP
\fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR
create a new value or overwrite an existing unshared value, respectively,
to hold a byte-array value of \fInumBytes\fR bytes. \fBTcl_NewByteArrayObj\fR
returns a pointer to the created value with a reference count of zero.
\fBTcl_SetByteArrayObj\fR overwrites and invalidates any old contents
as appropriate, and keeps the same reference count (0 or 1). When
the \fIbytes\fR argument passed to either routine is not NULL, \fInumBytes\fR
bytes are copied from \fIbytes\fR into the new value. When
the \fIbytes\fR argument passed to either routine is NULL, the
contents of the resulting byte array value are undefined. A \fIbytes\fR
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. Such manipulation must be performed
only on unshared values, and accompanied by all appropriate invalidations.
.PP
\fBTcl_GetByteArrayFromObj\fR converts a Tcl value to byte-array type and
returns a pointer to the value's new internal representation as an array of
bytes. The number of bytes in this array is stored in \fInumBytesPtr\fR if
\fInumBytesPtr\fR is non-NULL. The storage for the array of bytes is owned by
the value and should not be freed. The contents of the array may be
modified by the caller only if the value is not shared and the caller
invalidates the string representation.
.PP
\fBTcl_GetBytesFromObj\fR does almost the same as \fBTcl_GetByteArrayFromObj\fR,
the difference is that this function can error if the object contains
characters > 255. If \fBinterp\fR is not NULL, an error-message will be left there.
.PP
\fBTcl_SetByteArrayLength\fR converts the Tcl value to byte-array type
and changes the number of bytes in the value's internal representation as an
array of bytes. If \fInumBytes\fR is greater than the space currently
allocated for the array, the array is reallocated be large enough to store
the larger number of bytes; the newly allocated bytes at the end of the
array have arbitrary values. If
\fInumBytes\fR is less than the space currently allocated for the array,
the length of array is reduced to the new length. The return value is a
pointer to the value's new array of bytes.
.SH "REFERENCE COUNT MANAGEMENT"
.PP
\fBTcl_NewByteArrayObj\fR always returns a zero-reference object, much
like \fBTcl_NewObj\fR.
.PP
\fBTcl_SetByteArrayObj\fR and \fBTcl_SetByteArrayLength\fR do not modify the
reference count of their \fIobjPtr\fR arguments, but do require that the
object be unshared.
.PP
\fBTcl_GetByteArrayFromObj\fR does not modify the reference count of its
\fIobjPtr\fR argument; it only reads.
.SH "SEE ALSO"
Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
.SH KEYWORDS
value, binary data, byte array, utf, unicode, internationalization
|
