1 files changed, 91 insertions, 0 deletions
diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3
new file mode 100644
index 0000000..b3ed34f
--- /dev/null
+++ b/doc/ByteArrObj.3
@@ -0,0 +1,91 @@
+'\"
+'\" 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.
+'\" 
+'\" RCS: @(#) $Id: ByteArrObj.3,v 1.2 1999/03/03 00:38:36 stanton Exp $
+'\" 
+.so man.macros
+.TH Tcl_ByteArrayObj 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_NewByteArrayObj, Tcl_SetByteArrayObj, Tcl_GetByteArrayFromObj, Tcl_SetByteArrayLength \- manipulate Tcl objects as a arrays of bytes 
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Obj *
+\fBTcl_NewByteArrayObj\fR(\fIbytes, length\fR)
+.sp
+void 
+\fBTcl_SetByteArrayObj\fR(\fIobjPtr, bytes, length\fR)
+.sp
+unsigned char *
+\fBTcl_GetByteArrayFromObj\fR(\fIobjPtr, lengthPtr\fR)
+.sp
+unsigned char *
+\fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR)
+.SH ARGUMENTS
+.AS "unsigned char" *lengthPtr in/out
+.AP "unsigned char" *bytes in
+The array of bytes used to initialize or set a byte-array object.
+.AP int length in
+The length of the array of bytes.  It must be >= 0.
+.AP Tcl_Obj *objPtr in/out
+For \fBTcl_SetByteArrayObj\fR, this points to the object to be converted to
+byte-array type.  For \fBTcl_GetByteArrayFromObj\fR and
+\fBTcl_SetByteArrayLength\fR, this points to the object from which to get
+the byte-array value; if \fIobjPtr\fR does not already point to a byte-array
+object, it will be converted to one.
+.AP int *lengthPtr out
+If non-NULL, filled with the length of the array of bytes in the object.
+.BE
+
+.SH DESCRIPTION
+.PP
+These procedures are used to create, modify, and read Tcl byte-array objects
+from C code.  Byte-array objects are typically used to hold the
+results of binary IO operations or data structures created with the
+\fBbinary\fR command.  In Tcl, an array of bytes is not equivalent to a
+string.  Conceptually, a string is an array of Unicode characters, while a
+byte-array is an array of 8-bit quantities with no implicit meaning.
+Accesser functions are provided to get the string representation of a
+byte-array or to convert an arbitrary object to a byte-array.  Obtaining the
+string representation of a byte-array object (by calling
+\fBTcl_GetStringFromObj\fR) produces a properly formed UTF-8 sequence with a
+one-to-one mapping between the bytes in the internal representation and the
+UTF-8 characters in the string representation.  
+.PP
+\fBTcl_NewByteArrayObj\fR and \fBTcl_SetByteArrayObj\fR will
+create a new object of byte-array type or modify an existing object to have a
+byte-array type.  Both of these procedures set the object's type to be
+byte-array and set the object's internal representation to a copy of the
+array of bytes given by \fIbytes\fR. \fBTcl_NewByteArrayObj\fR returns a
+pointer to a newly allocated object with a reference count of zero.
+\fBTcl_SetByteArrayObj\fR invalidates any old string representation and, if
+the object is not already a byte-array object, frees any old internal
+representation.
+.PP
+\fBTcl_GetByteArrayFromObj\fR converts a Tcl object to byte-array type and
+returns a pointer to the object's new internal representation as an array of
+bytes.  The length of this array is stored in \fIlengthPtr\fR if
+\fIlengthPtr\fR is non-NULL.  The storage for the array of bytes is owned by
+the object and should not be freed.  The contents of the array may be
+modified by the caller only if the object is not shared and the caller
+invalidates the string representation.  
+.PP
+\fBTcl_SetByteArrayLength\fR converts the Tcl object to byte-array type
+and changes the length of the object's internal representation as an
+array of bytes.  If \fIlength\fR is greater than the space currently
+allocated for the array, the array is reallocated to the new length; the
+newly allocated bytes at the end of the array have arbitrary values.  If
+\fIlength\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 object's new array of bytes.  
+
+.SH "SEE ALSO"
+Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
+
+.SH KEYWORDS
+object, byte array, utf, unicode, internationalization