'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\" Copyright (c) 2000 Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: scan.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: scan.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 scan 3tcl 8.3 Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
scan \- 使用 sscanf 式樣的轉換指定符分析字串
.SH "總覽 SYNOPSIS"
\fBscan \fIstring format \fR?\fIvarName varName ...\fR?
.BE

.SH INTRODUCTION
.PP
這個命令用與 ANSI C \fBsscanf\fR 過程相同的方式從輸入字串中分析欄位並返回完成的轉換數目的總計，如果在任何轉換被完成之前到達了輸入字串的結束則返回 -1。\fIString\fR 給出要被分析的輸入而 \fIformat\fR 指示如何分析它，使用與 \fBsscanf\fR 相同的 \fB%\fR 轉換指定符。每個 \fIvarName\fR 給出一個變數的名字；在從 \fIstring\fR 中檢索出一個欄位的時候，結果被轉換回一個字串並賦值給相應的變數。
.VS 8.3
如果未指定 \fIvarName\fR 變數，則 \fBscan\fR 在行內(inline)方式下工作，返回的資料將是一個列表而不儲存在變數中。在行內方式下，如果在任何轉換被完成之前到達了輸入字串的結束則返回，則返回一個空串。
.VE 8.3

.SH "檢索細節 DETAILS ON SCANNING"
.PP
\fBScan\fR 操作一起檢索 \fIstring\fR 和 \fIformat\fR。如果在 \fIformat\fR 的下一個字元是一個空字元(blank)或跳格字元(tab)則它匹配在 \fIstring\fR 中任何數目(包括零個)的白空格字元。
如果它不是一個 \fB%\fR 字元則它必須匹配 \fIstring \fR的下一個字元。當在 \fIformat\fR 中遇到一個 \fB%\fR 的時候，它指示一個轉換指定符的開始。
一個轉換指定符包括 \fB% \fR和後面的最多四個欄位: 一個 \fB*\fR，它指示丟棄被轉換出的值而不是賦值到變數中；一個 XPG3 位置指定符；一個數指示最大的欄位寬度；和一個轉換字元。除了轉換字元之外所有這些欄位都是可選的。存在的欄位必須按照上面給出的次序出現。
.PP
當 \fBscan\fR 在 \fIformat \fR中發現一個轉換指定符的時候，它首先跳過 \fIstring\fR 中的所有白空格(除非指定符是 \fB[\fR 或 \fBc\fR)。接著它依據轉換指定符轉換下一組輸入字元，並把結果儲存到用給 \fBscan\fR 的下一個引數給出的變數中。
.PP
如果 \fB%\fR 跟隨著一個十進位制數和一個 \fB$\fR，比如``\fB%2$d\fR''，則使用的變數不取自下一個順序的引數。而是取自用這個數字指定的引數，這裡 1 對應著第一個 \fIvarName\fR。如果在 \fIformat\fR 中有任何位置指定符則所有指定符都必須被指定位置。每個在引數列表上的 \fIvarName\fR 必須準確的對應於一個轉換指定符，否則生成一個錯誤。在行內方式下，任何位置指定符可以指定最多一次，並且用空串填充空位置指定符。
.PP
支援下列轉換字元:
.TP 10
\fBd\fR
輸入欄位必須是一個十進位制整數。它被讀入並作為一個十進位制字串儲存到變數中。
.TP 10
\fBo\fR
輸入欄位必須是一個八進位制整數。它被讀入並作為一個八進位制字串儲存到變數中。
.VS 8.4
If the value exceeds MAX_INT (017777777777 on platforms using 32-bit
integers), it will be truncated to a signed integer.  Hence, 037777777777
will appear as -1 on a 32-bit machine.
.VE 8.4
.TP 10
\fBx\fR
輸入欄位必須是一個十六進位制整數。它被讀入並作為一個十六進位制字串儲存到變數中。
.VS 8.4
If the value exceeds MAX_INT (0x7FFFFFFF on platforms using 32-bit
integers), it will be truncated to a signed integer.  Hence, 0xFFFFFFFF
will appear as -1 on a 32-bit machine.
.VE 8.4
.TP 10
\fBu\fR
輸入欄位必須是一個十進位制整數。它被讀入並作為一個無符號十進位制字串儲存到變數中。
.TP 10
\fBi\fR 
輸入欄位必須是一個整數。使用與 \fBexpr\fR 中描述的相同方式確定基數(base)(例如，十進位制、八進位制、或十六進位制)。值被作為一個十進位制字串儲存到變數中。
.TP 10
\fBc\fR
讀入一個單一的字元並把它的二進位制值作為一個十進位制字串儲存到變數中。在這種情況下不跳過初始的白空格，這樣輸入欄位可以是一個白空格字元。這個轉換不同於  ANSI 標準的地方是輸入欄位總是由一個單一欄位組成並且不可以指定欄位寬度。
.TP 10
\fBs\fR
輸入欄位由到下一個白空格為止的所有字元組成；把這些字元複製到變數中。
.TP 10
\fBe\fR 或 \fBf\fR 或 \fBg\fR
輸入欄位必須是一個浮點數，其組成是一個可選的正負號，一個可能有小數點的十進位制數字的字串，和一個可選的指數，它由一個 \fBe\fR 或 \fBE\fR  並跟隨著一個可選的正負號和一個十進位制數字的字串組成。它被讀入並作為一個浮點數儲存到變數中。
.TP 10
\fB[\fIchars\fB]\fR
輸入欄位由任何數目的在 \fIchars \fR中的字元組成。把匹配的字串儲存到變數中。如果在方括號之間的第一個字元是\fB]\fR 則它被作為 \fIchars\fR 的一部分來對待而不是這個字元集合的閉合方括號。
如果 \fIchars\fR 包括一個 \fIa\fB\-\fIb\fR 形式的序列，則匹配在 \fIa\fR 和 \fIb\fR 之間(包括二者)的任何字元。如果在方括號之間的第一個或最後一個字元是一個 \fB-\fR，則它被作為 \fIchars\fR 的一部分來對待而不是指示一個範圍。
.TP 10
\fB[^\fIchars\fB]\fR
輸入欄位由任何數目的不在 \fIchars \fR中的字元組成。把匹配的字串儲存到變數中。如果緊隨在     \fB^\fR 後面的字元是一個 \fB]\fR 則它被作為 \fIchars\fR     的一部分來對待而不是這個字元集合的閉合方括號。
如果\fIchars\fR     包括一個 \fIa\fB\-\fIb\fR  形式的序列，則從字元的集合中排除在 \fIa\fR 和 \fIb\fR     之間(包括二者)的任何字元。如果在方括號之間的第一個或最後一個字元是一個     \fB-\fR，則它被作為 \fIchars\fR     的一部分來對待而不是指示一個範圍。
.TP 10
\fBn\fR
不從輸入字串中消耗輸入。而是把到現在為止從輸入字串中檢索到的字元總數儲存到變數中。
.LP
對於一個轉換從輸入中讀的字元數目應該是對特定轉換最大的數目(例如，對 \fB%d \fR是儘可能多的十進位制數字，對於 \fB%o \fR是儘可能多的八進位制數字，以此類推)。給一個給定轉換的輸入要麼終止於遇到一個白空格要麼終止於達到了最大的欄位寬度，只要其中一種情況滿足就終止。如果在轉換指定符中存在一個 \fB*\fR 則不賦值變數並且不消耗下一個檢索引數。

.SH "與ANSI SSCANF 的區別 DIFFERENCES FROM ANSI SSCANF"
.PP
除了下列區別之外 \fBscan\fR 命令的行為與 ANSI C \fBsscanf\fR 過程的行為相同:
.IP [1]
當前不支援 \fB%p\fR 轉換指定符。
.IP [2]
對於 \fB%c\fR  轉換，把一個單一字元轉換成一個十進位制字串，接著把它賦值給相應的  \fIvarName\fR；對於這個轉換不能指定欄位寬度。
.IP [3]
忽略 \fBl\fR、\fBh\fR、和 \fBL\fR  修飾符；轉換整數值總是如同不存在修飾符，而轉換實數值總是如同存在  \fBl\fR 修飾符(就是說，對於內部表示使用型別 \fBdouble\fR)。
.IP [4]
.VS 8.3
如果在任何轉換被完成之前到達了輸入字串的結束並且未給出變數，則返回一個空串。
.VE 8.3

.SH "參見 SEE ALSO"
format(n), sscanf(3)

.SH "關鍵字 KEYWORDS"
conversion specifier, parse, scan

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