'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 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: trace.n,v 1.2 2003/11/24 05:10:00 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: trace.n,v 1.2 2003/11/24 05:10:00 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 trace 3tcl "" Tcl "Tcl Built-In Commands"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
trace \- 監視變數訪問
.SH "總覽 SYNOPSIS"
\fBtrace \fIoption\fR ?\fIarg arg ...\fR?
.BE

.SH "描述 DESCRIPTION"
.PP
這個命令導致在呼叫了特定操作的時候執行 Tcl 命令。現在只實現了變數跟蹤。合法的 \fIoption\fR (選項) (可以是縮寫)有:
.TP
\fBtrace variable \fIname ops command\fR
安排 \fIcommand\fR 在變數 \fIname\fR 被以用 \fIops \fR給出的方式訪問的時候執行。\fIName\fR     可以引用一個普通變數、陣列的一個元素，或整個的一個數組(就是說，\fIname\fR     可以只是一個數組的名字，而不加在圓括號中的索引)。如果     \fIname\fR     引用整個的一個數組，則在操縱了這個陣列的任何元素的時候呼叫     \fIcommand\fR     。如果這個變數不存在，則建立它但不給它值，所以對 \fBnamespace     which\fR 查詢是可見的，但對 \fBinfo exists\fR     不是。
.RS
.PP
\fIOps\fR     指示要進行何種操作，它由下列字母中的一個或多個組成:
.TP
\fBr\fR
在讀這個變數的時候呼叫 \fIcommand\fR。
.TP
\fBw\fR
在寫這個變數的時候呼叫 \fIcommand\fR。
.TP
\fBu\fR
在刪除這個變數的時候呼叫 \fIcommand\fR。可以使用 \fBunset\fR  命令顯式的刪除變數，或者在過程返回的時候隱式的刪除(所有它們的區域性變數)。在刪除直譯器的時候也刪除變數，因為沒有在其中執行命令的直譯器所以不呼叫跟蹤。
.PP
當觸發跟蹤的時候，向 \fIcommand\fR     新增三個引數，所以實際上的命令如下:
.CS
\fIcommand name1 name2 op\fR
.CE
\fIName1\fR 和 \fIname2\fR 給出被訪問了的變數的名字:     如果這個變數是個標量，則 \fIname1\fR 給出變數的名字而 \fIname2\fR     是一個空串；如果變數是一個數組元素，則 \fIname1\fR     給出陣列的名字而 \fIname2\fR     給出在這個陣列中的索引；如果整個陣列被刪除並且跟蹤註冊在整個陣列上，而不是在一個單一元素上，則     \fIname1\fR 給出這個陣列的名字而 \fIname2\fR 是一個空串。\fIName1\fR     和 \fIname2\fR 不是必須與在 \fBtrace variable\fR     命令中使用的名字相同: \fBupvar\fR     命令允許一個過程在不同的名字下引用一個變數。\fIOp\fR     指示在這個變數上進行了何種操作，它是上面定義的 \fBr\fR、\fBw\fR、或     \fBu\fR 中的一個。
.PP
\fICommand\fR     在與呼叫跟蹤操作的程式碼的相同的上下文中執行:     如果被訪問的變數是一個 Tcl 過程的一部分，則 \fIcommand\fR     將訪問到與過程中的程式碼相同的區域性變數。這個上下文可能與在其中建立跟蹤的上下文不同。如果     \fIcommand\fR 呼叫一個過程(它經常這麼做)，則過程要想訪問被跟蹤的變數必須使用     \fBupvar\fR 或 \fBuplevel\fR。還要注意     \fIname1\fR     不是必須與用來在變數上設定跟蹤的那個名字相同；如果透過用     \fBupvar\fR     定義的一個變數進行訪問，則可能發生不同。
.PP
對於讀和寫跟蹤，\fIcommand\fR     可以修改變數來影響被跟蹤的操作的結果。如果\fIcommand\fR     在讀寫跟蹤期間修改了一個變數的值，則這個新值將被返回為跟蹤操作的結果。除非從     \fIcommand\fR     返回的值是一個某種錯誤，此時跟蹤的操作返回的錯誤與跟蹤命令返回的錯誤訊息相同，否則忽略它(例如，可使用這種機制實現只讀變數)。對於寫跟蹤，在這個變數的值被改變之後呼叫     \fIcommand\fR     ；它把一個新值寫到這個變數中來屏棄在這次寫操作中指定的原始值。要實現只讀變數，\fIcommand\fR     必須儲存這個變數的舊值。
.PP
當 \fIcommand\fR     在一個讀或寫跟蹤期間執行的時候，在變數上的跟蹤被暫時禁用。這意味著     \fIcommand\fR 呼叫的讀和寫將直接發生，不用再次呼叫 \fIcommand\fR     (或任何其他跟蹤)。但是，如果 \fIcommand\fR     刪除了這個變數則呼叫刪除跟蹤。
.PP
在呼叫一個刪除跟蹤的時候，這個變數已經被刪除了:     它將出現為未定義的而不加以跟蹤。如果因為一個過程返回而發生一個刪除，則在返回到的那個過程的變數上下文中呼叫跟蹤:     返回的過程的棧楨已經不存在了。在刪除跟蹤期間不禁止跟蹤，所以如果一個刪除跟蹤命令建立了一個新的跟蹤並訪問了這個變數，則呼叫這個跟蹤。忽略刪除跟蹤的任何錯誤。
.PP
如果在一個變數上有多個跟蹤，則以建立的次序呼叫它們，先處理最新的。如果一個跟蹤返回一個錯誤，則不對這個變數呼叫進一步的跟蹤。如果一個數組元素有一個跟蹤設定，並且還有一個在整個陣列上的跟蹤設定，呼叫在整個陣列上的跟蹤先於在這個元素上的跟蹤。
.PP
一旦建立了，跟蹤保持有效直到用下面描述的 \fBtrace vdelete\fR 命令刪除這個跟蹤、直到刪除了這個變數，或直到刪除了這個直譯器為止。刪除陣列的一個元素將刪除在這個元素上的任何跟蹤，但不刪除在整個陣列上的跟蹤。
.PP
這個命令返回一個空串。
.RE
.TP
\fBtrace vdelete \fIname ops command\fR
如果在變數 \fIname\fR 上設定了一個用 \fIops\fR     給出操作和用 \fIcommand\fR     給出命令的跟蹤，則刪除這個跟蹤，這樣將永不再次呼叫 \fIcommand\fR     。返回一個空串。
.TP
\fBtrace vinfo \fIname\fR
返回一個列表，為每個在變數 \fIname \fR設定的當前跟蹤包含一個元素。這個列表的每個元素自身是一個包含兩個元素的列表，它們是與這個跟蹤相關的     \fIops\fR 和 \fIcommand\fR 。如果 \fIname\fR     不存在或沒有跟蹤設定，則命令的結果是一個空串。

.SH "關鍵字 KEYWORDS"
read, variable, write, trace, unset

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