From 76acf27a553213e962e6a4bc1567ffd348e981c4 Mon Sep 17 00:00:00 2001
From: hobbs <hobbs>
Date: Sat, 8 Apr 2000 02:35:17 +0000
Subject: 	* doc/binary.n: clarified docs on sign extension in binary
 scan 	[Bug: 3466]

---
 doc/binary.n | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/doc/binary.n b/doc/binary.n
index 8b20259..6609775 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: binary.n,v 1.3 1999/04/16 00:46:34 stanton Exp $
+'\" RCS: @(#) $Id: binary.n,v 1.4 2000/04/08 02:35:17 hobbs Exp $
 '\" 
 .so man.macros
 .TH binary n 8.0 Tcl "Tcl Built-In Commands"
@@ -297,6 +297,22 @@ immediately with the number of variables that were set.  If there are
 not enough arguments for all of the fields in the format string that
 consume arguments, then an error is generated.
 .PP
+It is \fBimportant\fR to note that the \fBc\fR, \fBs\fR, and \fBS\fR
+(and \fBi\fR and \fBI\fR on 64bit systems) will be scanned into
+long data size values.  In doing this, values that have their high
+bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints),
+will be sign extended.  Thus the following will occur:
+.CS
+\fBset signShort [binary format s1 0x8000]\fR
+\fBbinary scan $signShort s1 val; \fI# val == 0xFFFF8000\fR
+.CE
+If you want to produce an unsigned value, then you can mask the return 
+value to the desired size.  For example, to produce an unsigned short 
+value:
+.CS
+\fBset val [expr {$val & 0xFFFF}]; \fI# val == 0x8000\fR
+.CE
+.PP
 Each type-count pair moves an imaginary cursor through the binary data,
 reading bytes from the current position.  The cursor is initially
 at position 0 at the beginning of the data.  The type may be any one of
-- 
cgit v0.12