2 '\" Copyright (c) 1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH proc n "" Tcl "Tcl Built-In Commands"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .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
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
277 '\" Note: do not modify the .SH NAME line immediately below!
279 proc \- Create a Tcl procedure
281 \fBproc \fIname args body\fR
285 The \fBproc\fR command creates a new Tcl procedure named
286 \fIname\fR, replacing
287 any existing command or procedure there may have been by that name.
288 Whenever the new command is invoked, the contents of \fIbody\fR will
289 be executed by the Tcl interpreter.
290 Normally, \fIname\fR is unqualified
291 (does not include the names of any containing namespaces),
292 and the new procedure is created in the current namespace.
293 If \fIname\fR includes any namespace qualifiers,
294 the procedure is created in the specified namespace.
295 \fIArgs\fR specifies the formal arguments to the
296 procedure. It consists of a list, possibly empty, each of whose
298 one argument. Each argument specifier is also a list with either
299 one or two fields. If there is only a single field in the specifier
300 then it is the name of the argument; if there are two fields, then
301 the first is the argument name and the second is its default value.
302 Arguments with default values that are followed by non-defaulted
303 arguments become required arguments. In 8.6 this will be considered an
306 When \fIname\fR is invoked a local variable
307 will be created for each of the formal arguments to the procedure; its
308 value will be the value of corresponding argument in the invoking command
309 or the argument's default value.
310 Actual arguments are assigned to formal arguments strictly in order.
311 Arguments with default values need not be
312 specified in a procedure invocation. However, there must be enough
313 actual arguments for all the
314 formal arguments that do not have defaults, and there must not be any extra
316 Arguments with default values that are followed by non-defaulted
317 arguments become required arguments (in 8.6 it will be considered an
319 There is one special case to permit procedures with
320 variable numbers of arguments. If the last formal argument has the name
321 \fBargs\fR, then a call to the procedure may contain more actual arguments
322 than the procedure has formal arguments. In this case, all of the actual arguments
323 starting at the one that would be assigned to \fBargs\fR are combined into
324 a list (as if the \fBlist\fR command had been used); this combined value
325 is assigned to the local variable \fBargs\fR.
327 When \fIbody\fR is being executed, variable names normally refer to
328 local variables, which are created automatically when referenced and
329 deleted when the procedure returns. One local variable is automatically
330 created for each of the procedure's arguments.
331 Other variables can only be accessed by invoking one of the \fBglobal\fR,
332 \fBvariable\fR, \fBupvar\fR or \fBnamespace upvar\fR commands.
333 The current namespace when \fIbody\fR is executed will be the
334 namespace that the procedure's name exists in, which will be the
335 namespace that it was created in unless it has been changed with
337 '\" We may change this! It makes [variable] unstable when renamed and is
338 '\" frankly pretty crazy, but doing it right is harder than it looks.
340 The \fBproc\fR command returns an empty string. When a procedure is
341 invoked, the procedure's return value is the value specified in a
342 \fBreturn\fR command. If the procedure does not execute an explicit
343 \fBreturn\fR, then its return value is the value of the last command
344 executed in the procedure's body.
345 If an error occurs while executing the procedure
346 body, then the procedure-as-a-whole will return that same error.
349 This is a procedure that accepts arbitrarily many arguments and prints
350 them out, one by one.
353 \fBproc\fR printArguments args {
360 This procedure is a bit like the \fBincr\fR command, except it
361 multiplies the contents of the named variable by the value, which
365 \fBproc\fR mult {varName {multiplier 2}} {
367 set var [expr {$var * $multiplier}]