'\"
'\" Copyright (c) 1997 by 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: binary.n,v 1.2 2003/11/24 05:09:59 bbbush Exp $
'\" 
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: binary.n,v 1.2 2003/11/24 05:09:59 bbbush Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH binary 3tcl 8.0 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
binary \- 從(向)二進制串插入和提取字段
.SH 總覽 SYNOPSIS
\fBbinary format \fIformatString \fR?\fIarg arg ...\fR?
.br
\fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR?
.BE

.SH 描述 DESCRIPTION
.PP
 這個命令提供操縱二進制數據的設施。第一種形式是 \fBbinary format\fR，從普通的 Tcl 值來建立一個二進制串。例如，給出值 16 和 22，可以產生一個8字節的二進制串，由兩個4字節的整數組成。第二種形式是 \fBbinary scan\fR，做相反的事: 從一個二進制串中提取出數據並作爲通常的 Tcl 字符串值而返回。

.SH "二進制化 BINARY FORMAT"
.PP
\fBbinary format\fR 命令生成一個二進制串，其格式由 \fIformatString\fR 指定，它的內容來(自在後面)增添的參數。返回結果二進制值。
.PP
\fIformatString\fR 由零個或多個字段說明符(specifier)的序列組成，用零個或多個空格分隔。每個說明符都是一個單獨的類型字符，跟隨着一個可選的數值 \fIcount\fR。多數字段說明符消耗(consume)一個參數來獲取被格式化的值。類型字符指定如何格式化值。\fIcount\fR 典型的指示從值中接受了多少個指定類型的單項(item)。如果\fIcount\fR 存在，則是一個非負十進制整數或 \fB*\fR，星號通常指示使用在值中所有的單項。如果參數的個數不匹配在消耗參數的這些格式串中的字段的個數，則產生一個錯誤。
.PP
每個類型-數目(type-count)對在二進制串上移動一個假想的遊標，在當前的位置上存儲一些字節並且遊標前進到最近存儲的字節的緊後面。遊標初始在位置 0 也就是在數據的開始(端)。類型可以是下列字符中的任意一個:
.IP \fBa\fR 5
在輸出串中存儲長度是 \fIcount\fR 的一個字符串。如果 \fIarg\fR 比 \fIcount\fR 的字節數少，則有增補的零字節來填充字段。如果 \fIarg\fR 比指定長度多，忽略額外的字符。如果 \fIcount\fR 是 \fB*\fR, 則格式化在 \fIarg\fR 中的所有字節。如果省略了 \fIcount\fR ，則格式化一個字符。例如，
.RS
.CS
\fBbinary format a7a*a alpha bravo charlie\fR
.CE
將返回等價於 \fBalpha\\000\\000bravoc\fR的一個串。
.RE
.IP \fBA\fR 5
除了使用空格而不是空字符來填充之外，這種形式同於 \fBa\fR。例如，
.RS
.CS
\fBbinary format A6A*A alpha bravo charlie\fR
.CE
將返回 \fBalpha bravoc\fR.
.RE
.IP \fBb\fR 5
在輸出串中存儲 \fIcount\fR 個二進制數字的一個串，並且在每個字節中以從低到高的次序(來排序)。\fIArg\fR 必須包含一個 \fB1\fR 和 \fB0\fR 字符的一個序列。以從最先到最後的次序散佈(emit)結果字節，並且以在每個字節中以從低到高的次序格式化每位。如果 \fIarg\fR 比 \fIcount\fR 的位數少，則剩餘的位使用零。如果 \fIarg\fR 比指定的位數多，忽略額外的位。如果 \fIcount\fR 是 \fB*\fR, 則格式化在 \fIarg\fR 中所有的位。如果省略了 \fIcount\fR，則格式化一位。如果如果格式化的位數不結束在字節邊界上，最後的字節的剩餘的位將是零。例如，
.RS
.CS
\fBbinary format b5b* 11100 111000011010\fR
.CE
將返回等價於 \fB\\x07\\x87\\x05\fR的一個串。
.RE
.IP \fBB\fR 5
除了在每個字節中以從高到低的次序(來排序)之外，這種形式同於 \fBb\fR。例如，
.RS
.CS
\fBbinary format B5B* 11100 111000011010\fR
.CE
將返回等價於 \fB\\xe0\\xe1\\xa0\fR的一個串。
.RE
.IP \fBh\fR 5
在輸出串中存儲 \fIcount\fR 個十六進制的數字的一個串，並且在每個字節中以從低到高的次序(來排序)。\fIArg\fR  必須包含在“0123456789abcdefABCDEF”(字符)集中的字符的一個序列。以從最先到最後的次序散佈(emit)結果字節，並且在每個字節中以從低到高的次序格式化十六進制數字。如果 \fIarg\fR 比 \fIcount\fR 的數字個數少，則剩餘的數字使用零。如果 \fIarg\fR 比指定的數字的個數多，忽略額外的數字。如果 \fIcount\fR 是 \fB*\fR，則格式化在 \fIarg\fR 中所有的數字。如果省略了 \fIcount\fR ，則格式化一個數字。如果格式化的數字的個數不結束在一個字節的邊界上，最後的字節的剩餘的位將是零。例如，
.RS
.CS
\fBbinary format h3h* AB def\fR
.CE
將返回等價於 \fB\\xba\\x00\\xed\\x0f\fR的一個串。
.RE
.IP \fBH\fR 5
除了在每個字節中以從高到低的次序(來排序)之外，這種形式同於 \fBh\fR 。例如，
.RS
.CS
\fBbinary format H3H* ab DEF\fR
.CE
將返回等價於 \fB\\xab\\x00\\xde\\xf0\fR的一個串。
.RE
.IP \fBc\fR 5
在輸出串中存儲一個或多個8位整數值。如果未指定 \fIcount\fR，則 \fIarg\fR 必須包含一個整數值；否則 \fIarg\fR 必須包含至少有一個整數元素的一個列表。在當前的位置上把每個整數的低位(low-order)的 8 位存儲成一個一字節的值。如果 \fIcount\fR 是 \fB*\fR，則格式化在列表中所有的整數。如果在列表中的元素的個數比 \fIcount\fR 少，則產生一個錯誤。 如果在列表中的元素的個數比 \fIcount\fR 多，則忽略額外的元素。例如，
.RS
.CS
\fBbinary format c3cc* {3 -3 128 1} 260 {2 5}\fR
.CE
將返回等價於 \fB\\x03\\xfd\\x80\\x04\\x02\\x05\fR 的一個串。而
.CS
\fBbinary format c {2 5}\fR
.CE
將產生一個錯誤。
.RE
.IP \fBs\fR 5
除了以小端(little-endian)字節序在輸出串中存儲一個或多個16位整數之外，這種形式同於 \fBc\fR。在當前位置上把每個整數的低位的16位存儲成一個兩字節的值，並且首先存儲最低有效(significant)字節。例如，
.RS
.CS
\fBbinary format s3 {3 -3 258 1}\fR
.CE
將返回等價於 \fB\\x03\\x00\\xfd\\xff\\x02\\x01\fR 的一個字串。
.RE
.IP \fBS\fR 5
除了以大端(big-endian)字節序在輸出串中存儲一個或多個16位整數之外，這種形式同於 \fBs\fR 。例如，
.RS
.CS
\fBbinary format S3 {3 -3 258 1}\fR
.CE
將返回等價於 \fB\\x00\\x03\\xff\\xfd\\x01\\x02\fR 的一個串。
.RE
.IP \fBi\fR 5
 除了以小端(little-endian)字節序在輸出串中存儲一個或多個32位整數之外，這種形式同於 \fBc\fR。在當前位置上把每個整數的低位的32位存儲成一個四字節的值，並且首先存儲最低有效字節。例如，
.RS
.CS
\fBbinary format i3 {3 -3 65536 1}\fR
.CE
將返回等價於 \fB\\x03\\x00\\x00\\x00\\xfd\\xff\\xff\\xff\\x00\\x00\\x01\\x00\fR 的一個串。
.RE
.IP \fBI\fR 5
除了以大端(big-endian)字節序在輸出串中存儲一個或多個32位整數之外，這種形式同於 \fBi\fR。例如，
.RS
.CS
\fBbinary format I3 {3 -3 65536 1}\fR
.CE
將返回等價於 \fB\\x00\\x00\\x00\\x03\\xff\\xff\\xff\\xfd\\x00\\x01\\x00\\x00\fR 的一個串。
.RE
.IP \fBf\fR 5
除了以機器的本地表示在輸出串中存儲一個或多個單精度浮點數之外，這種形式同於 \fBc\fR。這種表示是不能跨體系移植的，所以不應用於在網絡上交流浮點數。浮點數的大小在體系間可能不同，所以生成的字節數也可能不同。如果值溢出了機器的本地表示，則使用系統定義的 FLT_MAX 的值。因爲 Tcl 在內部使用雙精度浮點數，在轉換成單精度時可能損失些精度。例如，運行在 Intel Pentium 處理器的一個 Windows 系統上，
.RS
.CS
\fBbinary format f2 {1.6 3.4}\fR
.CE
將返回等價於 \fB\\xcd\\xcc\\xcc\\x3f\\x9a\\x99\\x59\\x40\fR 的一個串。
.RE
.IP \fBd\fR 5
除了以機器的本地表示在輸出串中存儲一個或多個雙精度浮點數之外，這種形式同於 \fBf\fR。例如，運行在 Intel Pentium 處理器的一個 Windows 系統上，
.RS
.CS
\fBbinary format d1 {1.6}\fR
.CE
將返回等價於 \fB\\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f\fR 的一個串。
.RE
.IP \fBx\fR 5
Stores \fIcount\fR null bytes in the output string.  If \fIcount\fR is
not specified, stores one null byte.  If \fIcount\fR is \fB*\fR,
generates an error.  This type does not consume an argument.  For
example,
.RS
.CS
\fBbinary format a3xa3x2a3 abc def ghi\fR
.CE
將返回等價於 \fBabc\\000def\\000\\000ghi\fR 的一個串。
.RE
.IP \fBX\fR 5
在輸出串中反向移動遊標 \fIcount\fR 字節。如果 \fIcount\fR 是 \fB*\fR 或比當前遊標位置大，則遊標定位到位置 0，這樣下個存儲的字節將是結果串中的第一個字節。如果省略了\fIcount\fR，則遊標反向移動一字節。 這種形式不使用參數。例如，
.RS
.CS
\fBbinary format a3X*a3X2a3 abc def ghi\fR
.CE
將返回 \fBdghi\fR.
.RE
.IP \fB@\fR 5
在輸出串中把遊標移動到由 \fIcount\fR 指定的絕對位置上。位置 0 參照在輸出串中的第一個字節。如果 \fIcount\fR 參照的位置超出至今所存儲的最後的字節，則在空擋的(unitialized ?)位置上放置空字節並把遊標放置到指定位置。如果 \fIcount\fR 是 \fB*\fR，則遊標將被移動到輸出串的末端。如果省略了 \fIcount\fR，則產生一個錯誤。這種類型不使用參數。例如，
.RS
.CS
\fBbinary format a5@2a1@*a3@10a1 abcde f ghi j\fR
.CE
將返回 \fBabfdeghi\\000\\000j\fR.
.RE

.SH "二進制檢索 BINARY SCAN"
.PP
\fBbinary scan\fR 命令從一個二進制串分析字段、返回完成的轉換的數目。\fIString\fR 給出要被分析的輸入而 \fIformatString\fR 指示如何分析它。每個 \fIvarName\fR 給出一個變量的名字；當從 \fIstring\fR 檢索出一個字段時，結果被賦給相應的變量。
.PP
如同 \fBbinary format\fR 那樣，\fIformatString\fR 由零個或多個字段說明符(specifier)的序列組成，用零個或多個空格分隔。每個說明符都是一個單獨的類型字符，跟隨着一個可選的數值 \fIcount\fR。多數字段說明符消耗(consume)一個參數來獲取檢索出的值要放置在其中的那個變量。類型字符指定如何解釋二進制串。\fIcount\fR 典型的指定從數據中接受指定類型的多少個單項(item)。如果存在，\fIcount\fR 是一個非負數的十進制整數或 \fB*\fR，星號通常指示要用到在數據中所有的剩餘的單項。如果在滿足當前字段說明符的當前位置之後沒有剩下足夠的字節，則相應的變量保持不動(untouch)而 \fBbinary scan\fR 立即返回設置了的變量的個數。如果沒有足夠的參數給所有這些消耗參數的格式串中的字段，則產生一個錯誤。
.PP
着重 (\fBimportant\fR) 注意 \fBc\fR, \fBs\fR 和 \fBS\fR(還有在64位系統上的 \fBi\fR 和 \fBI\fRI)將被檢索成一個長整型 (long) 大小的值。在這種情況下，(最)高位設置(爲1)的值(對於char 是 0x80，對於 short 是 0x8000，對於 int 是 0x80000000)，將被符號擴展。所以下列情況將發生:
.CS
\fBset signShort [binary format s1 0x8000]\fR
\fBbinary scan $signShort s1 val; \fI# val == 0xFFFF8000\fR
.CE
如果你打算生成一個無符號值，那麼你可以把返回值屏蔽(mask)成需要的大小。例如，要生成一個無符號  short 值:
.CS
\fBset val [expr {$val & 0xFFFF}]; \fI# val == 0x8000\fR
.CE
.PP
每個類型-數目(type-count)對在二進制串上移動一個假想的遊標，從當前的位置上讀一些字節。遊標的初始在位置 0 也就是數據的開始(端)。類型可以是下列字符中的任意一個:
.IP \fBa\fR 5
數據是長度是 \fIcount\fR 的一個字符串。如果 \fIcount\fR 是 \fB*\fR，則在 string 中所有的剩餘的字節將被檢索到變量中。如果省略了 \fIcount\fR，則將檢索一個字符。例如，
.RS
.CS
\fBbinary scan abcde\\000fghi a6a10 var1 var2\fR
.CE
將返回 \fB1\fR 並把等價於 \fBabcde\\000\fR 的一個字符串存儲到 \fBvar1\fR 而 \fBvar2\fR 保持不變。
.RE
.IP \fBA\fR 5
除了在存儲到變量之前從檢索到的值中去除(strip)尾隨的空白(blank)和空字符(null)之外，這種形式同於 \fBa\fR。例如
.RS
.CS
\fBbinary scan "abc efghi  \\000" A* var1\fR
.CE
將返回 \fB1\fR 並把 \fBabc efghi\fR 存儲到 \fBvar1\fR。
.RE
.IP \fBb\fR 5
把數據轉換成 \fIcount\fR 位二進制數字的一個字符串，以從低到高的次序表示成“1”和“0”字符的一個序列。數據字節按從最先到最後的次序被檢索，並且在每個字節中按從低到高的次序接受(每)位。忽略在最後的字節中的任何額外的位。如果 \fIcount\fR 是 \fB*\fR，則檢索在串中的所有的剩餘的位。 如果省略了 \fIcount\fR，則檢索一位。例如，
.RS
.CS
\fBbinary scan \\x07\\x87\\x05 b5b* var1 var2\fR
.CE
將返回 \fB2\fR 並把 \fB11100\fR 存儲到 \fBvar1\fR 且 \fB1110000110100000\fR 存儲到 \fBvar2\fR.
.RE
.IP \fBB\fR 5
除了在每字節中按從高到低的次序接受(每)位之外，這種形式同於 \fBb\fR。例如，
.RS
.CS
\fBbinary scan \\x70\\x87\\x05 B5B* var1 var2\fR
.CE
將返回 \fB2\fR 並把 \fB01110\fR 存儲到 \fBvar1\fR 且 \fB1000011100000101\fR 存儲到 \fBvar2\fR.
.RE
.IP \fBh\fR 5
把數據轉換成 \fIcount\fR 個十六進制數字的一個字符串，以從低到高的次序表示成一個在 “0123456789abcdefABCDEF” (字符)集中的字符的一個序列。按從最先到最後的次序檢索數據字節，並且在每個字節中以從低到高的次序接受十六進制數字。忽略最後的字節中的任何額外的位。如果 \fIcount\fR 是 \fB*\fR, 則檢索在串中所有剩餘的十六進制數字。如果省略了 \fIcount\fR，則檢索一位十六進制數字。例如，
.RS
.CS
\fBbinary scan \\x07\\x86\\x05 h3h* var1 var2\fR
.CE
將返回 \fB2\fR 並把 \fB706\fR 存儲到 \fBvar1\fR 且 \fB50\fR 存儲到n \fBvar2\fR.
.RE
.IP \fBH\fR 5
除了在每個字節中以從高到低的次序接受數字之外，這種形式同於 \fBh\fR。例如，
.RS
.CS
\fBbinary scan \\x07\\x86\\x05 H3H* var1 var2\fR
.CE
將返回 \fB2\fR 並把 \fB078\fR 存儲到\fBvar1\fR 且 \fB05\fR 存儲到 \fBvar2\fR.
.RE
.IP \fBc\fR 5
把數據轉換成 \fIcount\fR 個8位有符號整數並作爲一個列表存儲到相應的變量中。如果 \fIcount\fR 是 \fB*\fR，則檢索在串中所有剩餘的字節。如果省略了 \fIcount\fR，則檢索一個8位整數。例如，
.RS
.CS
\fBbinary scan \\x07\\x86\\x05 c2c* var1 var2\fR
.CE
將返回\fB2\fR 並把 \fB7 -122\fR 存儲到 \fBvar1\fR 且 \fB5\fR 存儲到 \fBvar2\fR.  注意返回的整數是有符號的，但它們是類似下面這樣的表達式來轉換成無符號的8位數量(quantity):
.CS
\fBexpr ( $num + 0x100 ) % 0x100\fR
.CE
.RE
.IP \fBs\fR 5
把數據解釋成 \fIcount\fR 個表示爲小端字節序的16位有符號整數。 整數被作爲一個列表存儲到相應的變量中。如果 \fIcount\fR 是 \fB*\fR，則檢索在串中所有剩餘的字節。如果省略了 \fIcount\fR，則檢索一個16位整數。例如，
.RS
.CS
\fBbinary scan \\x05\\x00\\x07\\x00\\xf0\\xff s2s* var1 var2\fR
.CE
將返回 \fB2\fR 並把 \fB5 7\fR 存儲到 \fBvar1\fR 且 \fB-16\fR 存儲到 \fBvar2\fR.  注意返回的整數是有符號的，但它們是類似下面這樣的表達式來轉換成無符號的16位數量(quantity):
.CS
\fBexpr ( $num + 0x10000 ) % 0x10000\fR
.CE
.RE
.IP \fBS\fR 5
除了把數據解釋成 \fIcount\fR 個表示爲大端字節序的16位有符號整數之外，這種形式同於 \fBs\fR。例如， 
.RS
.CS
\fBbinary scan \\x00\\x05\\x00\\x07\\xff\\xf0 S2S* var1 var2\fR
.CE
將返回 \fB2\fR 並把 \fB5 7\fR 存儲到 \fBvar1\fR 且 \fB-16\fR 存儲到 \fBvar2\fR. 
.RE
.IP \fBi\fR 5
把數據解釋成 \fIcount\fR 個表示爲小端字節序的32位有符號整數。 整數被作爲一個列表存儲到相應的變量中。如果 \fIcount\fR 是 \fB*\fR，則檢索在串中所有剩餘的字節。如果省略了 \fIcount\fR，則檢索一個32位整數。例如，
.RS
.CS
\fBbinary scan \\x05\\x00\\x00\\x00\\x07\\x00\\x00\\x00\\xf0\\xff\\xff\\xff i2i* var1 var2\fR
.CE
將返回 \fB2\fR ，並把 \fB5 7\fR 存儲到 \fBvar1\fR 且 \fB-16\fR 存儲到 \fBvar2\fR。注意返回的整數是有符號的並且不能被 Tcl 表示成無符號的值。
.RE
.IP \fBI\fR 5
除了把數據解釋成 \fIcount\fR 個表示爲大端字節序的32位有符號整數之外，這種形式同於 \fBi\fR。例如，
.RS
.CS
\fBbinary \\x00\\x00\\x00\\x05\\x00\\x00\\x00\\x07\\xff\\xff\\xff\\xf0 I2I* var1 var2\fR
.CE
將返回 \fB2\fR  ，並把 \fB5 7\fR 存儲到 \fBvar1\fR 且 \fB-16\fR 存儲到 \fBvar2\fR。
.RE
.IP \fBf\fR 5
把數據解釋成 \fIcount\fR 個機器本地表示的單精度浮點數，把浮點數作爲一個列表存儲到相應的變量中 。如果 \fIcount\fR 是 \fB*\fR，則檢索在串中所有剩餘的字節。如果省略了 \fIcount\fR，則檢索一個單精度浮點數。 浮點數的大小在體系間可能不同，所以檢索的字節數也可能不同。如果數據不表示一個有效的浮點數，結果值是未定義的並且依賴於編譯器。例如，運行在 Intel Pentium 處理器的一個 Windows 系統上，
.RS
.CS
\fBbinary scan \\x3f\\xcc\\xcc\\xcd f var1\fR
.CE
將返回 \fB1\fR，並把 \fB1.6000000238418579\fR 存儲到 \fBvar1\fR。
.RE
.IP \fBd\fR 5
除了把數據解釋成 \fIcount\fR 個機器本地表示的雙精度浮點數之外，這種形式同
於 \fBf\fR。例如，運行在 Intel Pentium 處理器的一個 Windows 系統上，
.RS
.CS
\fBbinary scan \\x9a\\x99\\x99\\x99\\x99\\x99\\xf9\\x3f d var1\fR
.CE
將返回 \fB1\fR ，並把 \fB1.6000000000000001\fR 存儲到 \fBvar1\fR1。
.RE
.IP \fBx\fR 5
在 \fIstring\fR 中正向移動遊標 \fIcount\fR 字節。如果 \fIcount\fR 是 \fB*\fR 或比當前遊標位置之後的字節數大，則遊標定位到位置 \fIstring\fR 中的最後一個字節之後。如果省略了\fIcount\fR，則遊標正向移動一字節。 注意 這種形式不消耗參數。例如，
.RS
.CS
\fBbinary scan \\x01\\x02\\x03\\x04 x2H* var1\fR
.CE
將返回 \fB1\fR，並把 \fB0304\fR 存儲到 \fBvar1\fR。
.RE
.IP \fBX\fR 5
在 \fIstring\fR 中反向移動遊標 \fIcount\fR 字節。如果 \fIcount\fR 是 \fB*\fR 或比當前遊標位置大，則遊標定位到位置 0，這樣下個檢索的字節將是 \fIstring\fR 中的第一個字節。如果省略了\fIcount\fR，則遊標反向移動一字節。 注意這種形式不消耗參數。例如，
.RS
.CS
\fBbinary scan \\x01\\x02\\x03\\x04 c2XH* var1 var2\fR
.CE
將返回 \fB2\fR，並把 \fB1 2\fR 存儲到 \fBvar1\fR 且 \fB020304\fR 存儲到 \fBvar2\fR。
.RE
.IP \fB@\fR 5
在數據串中把遊標移動到由 \fIcount\fRt 指定的絕對位置上。位置 0 參照在 \fIstring\fR 中的第一個字節。如果 \fIcount\fR 參照的位置超出 \fIstring\fR 的末端，則把遊標定位在最後的字節的後面。如果省略了 \fIcount\fR，則產生一個錯誤。例如， 　
.RS
.CS
\fBbinary scan \\x01\\x02\\x03\\x04 c2@1H* var1 var2\fR
.CE
將返回 2 ，並把 1 2 存儲到 var1 且 020304 存儲到 var2。
.RE

.SH "平臺相關事宜 PLATFORM ISSUES"
 有時希望以機器的本地字節序來格式化或檢索整數值。參照 \fBtcl_platform\fR  數組中的 \fBbyteOrder\fR 元素來決定在格式化或檢索整數時使用那種類型字符。

.SH "參見 SEE ALSO"
format(n), scan(n), tclvars(n)

.SH 關鍵字 KEYWORDS
binary, format, scan

.SH "[中文版維護人]"
.B 寒蟬退士
.SH "[中文版最新更新]"
.B 2001/06/21
.SH "《中國 Linux 論壇 man 手冊頁翻譯計劃》:"
.BI http://cmpp.linuxforum.net
.SH "跋"
.br
本頁面中文版由中文 man 手冊頁計劃提供。
.br
中文 man 手冊頁計劃：\fBhttps://github.com/man-pages-zh/manpages-zh\fR