NAME
       proc - Create a Tcl procedure

SYNOPSIS
       proc name args body


DESCRIPTION
       The  proc command creates a new Tcl procedure named name, replacing any
       existing command or procedure there may have been by that name.   When-
       ever  the new command is invoked, the contents of body will be executed
       by the Tcl  interpreter.   Normally,  name  is  unqualified  (does  not
       include  the names of any containing namespaces), and the new procedure
       is created in the current namespace.  If name  includes  any  namespace
       qualifiers,  the procedure is created in the specified namespace.  Args
       specifies the formal arguments to the  procedure.   It  consists  of  a
       list,  possibly  empty,  each of whose elements specifies one argument.
       Each argument specifier is also a list with either one or  two  fields.
       If there is only a single field in the specifier then it is the name of
       the argument; if there are two fields, then the first is  the  argument
       name and the second is its default value.

       When  name  is invoked a local variable will be created for each of the
       formal arguments to the procedure; its value will be the value of  cor-
       responding  argument  in the invoking command or the argument's default
       value.  Arguments with default values need not be specified in a proce-
       dure  invocation.   However,  there must be enough actual arguments for
       all the formal arguments that don't have defaults, and there  must  not
       be  any  extra  actual  arguments.  There is one special case to permit
       procedures with variable numbers of  arguments.   If  the  last  formal
       argument  has  the  name args, then a call to the procedure may contain
       more actual arguments than the procedure has formals.   In  this  case,
       all  of the actual arguments starting at the one that would be assigned
       to args are combined into a list (as  if  the  list  command  had  been
       used); this combined value is assigned to the local variable args.

       When  body  is  being  executed, variable names normally refer to local
       variables, which are created automatically when referenced and  deleted
       when  the  procedure returns.  One local variable is automatically cre-
       ated for each of the procedure's arguments.  Global variables can  only
       be  accessed  by  invoking  the  global  command  or the upvar command.
       Namespace variables can only be accessed by invoking the variable  com-
       mand or the upvar command.

       The proc command returns an empty string.  When a procedure is invoked,
       the procedure's return value is the value specified in  a  return  com-
       mand.   If  the  procedure doesn't execute an explicit return, then its
       return value is the value of the last command executed  in  the  proce-
       dure's  body.   If  an error occurs while executing the procedure body,
       then the procedure-as-a-whole will return that same error.

EXAMPLES
       This is a procedure that accepts arbitrarily many arguments and  prints
       them out, one by one.
              proc printArguments args {
                 foreach arg $args {
                    puts $arg
                 }
              }

       This procedure is a bit like the incr command, except it multiplies the
       contents of the named variable by the value, which defaults to 2:
              proc mult {varName {multiplier 2}} {
                 upvar 1 $varName var
                 set var [expr {$var * $multiplier}]
              }


SEE ALSO
       info(n), unknown(n)


KEYWORDS
