* doc/binary.n: clarified docs on sign extension in binary scan

	[Bug: 3466]

1 files changed, 17 insertions, 1 deletions

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