'\"
'\" 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