1<HTML><HEAD><TITLE>Built-In Commands - proc manual page</TITLE></HEAD><BODY>
2<H3><A NAME="M2">NAME</A></H3>
3proc - Create a Tcl procedure
4<H3><A NAME="M3">SYNOPSIS</A></H3>
5<B>proc </B><I>name args body</I><BR>
6<H3><A NAME="M4">DESCRIPTION</A></H3>
7The <B>proc</B> command creates a new Tcl procedure named
8<I>name</I>, replacing
9any existing command or procedure there may have been by that name.
10Whenever the new command is invoked, the contents of <I>body</I> will
11be executed by the Tcl interpreter.
12Normally, <I>name</I> is unqualified
13(does not include the names of any containing namespaces),
14and the new procedure is created in the current namespace.
15If <I>name</I> includes any namespace qualifiers,
16the procedure is created in the specified namespace.
17<I>Args</I> specifies the formal arguments to the
18procedure.  It consists of a list, possibly empty, each of whose
19elements specifies
20one argument.  Each argument specifier is also a list with either
21one or two fields.  If there is only a single field in the specifier
22then it is the name of the argument; if there are two fields, then
23the first is the argument name and the second is its default value.
24<P>
25When <I>name</I> is invoked a local variable
26will be created for each of the formal arguments to the procedure; its
27value will be the value of corresponding argument in the invoking command
28or the argument's default value.
29Arguments with default values need not be
30specified in a procedure invocation.  However, there must be enough
31actual arguments for all the
32formal arguments that don't have defaults, and there must not be any extra
33actual arguments.  There is one special case to permit procedures with
34variable numbers of arguments.  If the last formal argument has the name
35<B>args</B>, then a call to the procedure may contain more actual arguments
36than the procedure has formals.  In this case, all of the actual arguments
37starting at the one that would be assigned to <B>args</B> are combined into
38a list (as if the <B><A HREF="../TclCmd/list.htm">list</A></B> command had been used); this combined value
39is assigned to the local variable <B>args</B>.
40<P>
41When <I>body</I> is being executed, variable names normally refer to
42local variables, which are created automatically when referenced and
43deleted when the procedure returns.  One local variable is automatically
44created for each of the procedure's arguments.
45Global variables can only be accessed by invoking
46the <B><A HREF="../TclCmd/global.htm">global</A></B> command or the <B><A HREF="../TclCmd/upvar.htm">upvar</A></B> command.
47Namespace variables can only be accessed by invoking
48the <B><A HREF="../TclCmd/variable.htm">variable</A></B> command or the <B><A HREF="../TclCmd/upvar.htm">upvar</A></B> command.
49<P>
50The <B>proc</B> command returns an empty string.  When a procedure is
51invoked, the procedure's return value is the value specified in a
52<B><A HREF="../TclCmd/return.htm">return</A></B> command.  If the procedure doesn't execute an explicit
53<B><A HREF="../TclCmd/return.htm">return</A></B>, then its return value is the value of the last command
54executed in the procedure's body.
55If an error occurs while executing the procedure
56body, then the procedure-as-a-whole will return that same error.
57<H3><A NAME="M5">EXAMPLES</A></H3>
58This is a procedure that accepts arbitrarily many arguments and prints
59them out, one by one.
60<PRE><B>proc</B> printArguments args {
61   foreach arg $args {
62      puts $arg
63   }
64}</PRE>
65<P>
66This procedure is a bit like the <B><A HREF="../TclCmd/incr.htm">incr</A></B> command, except it
67multiplies the contents of the named variable by the value, which
68defaults to <B>2</B>:
69<PRE><B>proc</B> mult {varName {multiplier 2}} {
70   upvar 1 $varName var
71   set var [expr {$var * $multiplier}]
72}</PRE>
73<H3><A NAME="M6">SEE ALSO</A></H3>
74<B><A HREF="../TclCmd/info.htm">info</A></B>, <B><A HREF="../TclCmd/unknown.htm">unknown</A></B>
75<H3><A NAME="M7">KEYWORDS</A></H3>
76<A href="../Keywords/A.htm#argument">argument</A>, <A href="../Keywords/P.htm#procedure">procedure</A>
77<HR><PRE>
78<A HREF="../copyright.htm">Copyright</A> &#169; 1993 The Regents of the University of California.
79<A HREF="../copyright.htm">Copyright</A> &#169; 1994-1996 Sun Microsystems, Inc.
80<A HREF="../copyright.htm">Copyright</A> &#169; 1995-1997 Roger E. Critchlow Jr.</PRE>
81</BODY></HTML>
82