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> © 1993 The Regents of the University of California. 79<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc. 80<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE> 81</BODY></HTML> 82