1mNAME0m
       return - Return from a procedure

1mSYNOPSIS0m
       1mreturn 22m?1m-code 4m22mcode24m? ?1m-errorinfo 4m22minfo24m? ?1m-errorcode 4m22mcode24m? ?4mstring24m?


1mDESCRIPTION0m
       Return  immediately from the current procedure (or top-level command or
       1msource 22mcommand), with 4mstring24m as the return value.   If  4mstring24m  is  not
       specified then an empty string will be returned as result.

1mEXCEPTIONAL RETURN CODES0m
       In  addition  to the result of a procedure, the return code of a proce-
       dure may also be set by 1mreturn 22mthrough use of the 1m-code 22moption.  In the
       usual  case  where  the 1m-code 22moption isn't specified the procedure will
       return normally.  However, the 1m-code 22moption may be used to generate  an
       exceptional  return  from the procedure.  4mCode24m may have any of the fol-
       lowing values:

       1mok (or 0)    22mNormal return:  same as if the  option  is  omitted.   The
                    return code of the procedure is 0 (1mTCL_OK22m).

       1merror (1)    22mError  return:  the  return  code  of  the  procedure is 1
                    (1mTCL_ERROR22m).  The procedure command behaves in its calling
                    context as if it were the command 1merror 4m22mresult24m.  See below
                    for additional options.

       1mreturn (2)   22mThe return code of the procedure is 2  (1mTCL_RETURN22m).   The
                    procedure  command behaves in its calling context as if it
                    were the command 1mreturn 22m(with no arguments).

       1mbreak (3)    22mThe return code of the procedure is  3  (1mTCL_BREAK22m).   The
                    procedure  command behaves in its calling context as if it
                    were the command 1mbreak22m.

       1mcontinue (4) 22mThe return code of the procedure is 4 (1mTCL_CONTINUE22m).  The
                    procedure  command behaves in its calling context as if it
                    were the command 1mcontinue22m.

       4mvalue24m        4mValue24m must be an integer;  it  will  be  returned  as  the
                    return code for the current procedure.

       The  1m-code  22moption  is  rarely used.  It is provided so that procedures
       that implement new control structures can  reflect  exceptional  condi-
       tions back to their callers.

       Two  additional options, 1m-errorinfo 22mand 1m-errorcode22m, may be used to pro-
       vide additional information during error returns.   These  options  are
       ignored unless 4mcode24m is 1merror22m.

       The  1m-errorinfo  22moption specifies an initial stack trace for the 1merror-0m
       1mInfo 22mvariable;  if it is not specified then the  stack  trace  left  in
       1merrorInfo  22mwill  include the call to the procedure and higher levels on
       the stack but it will not include any information about the context  of
       the  error  within the procedure.  Typically the 4minfo24m value is supplied
       from the value left in 1merrorInfo 22mafter a 1mcatch 22mcommand trapped an error
       within the procedure.

       If  the  1m-errorcode  22moption is specified then 4mcode24m provides a value for
       the 1merrorCode 22mvariable.  If the option is not specified then  1merrorCode0m
       will default to 1mNONE22m.

1mEXAMPLES0m
       First,  a  simple  example  of using 1mreturn 22mto return from a procedure,
       interrupting the procedure body.
              proc printOneLine {} {
                 puts "line 1"    ;# This line will be printed.
                 1mreturn0m
                 puts "line 2"    ;# This line will not be printed.
              }

       Next, an example of using 1mreturn 22mto set the value returned by the  pro-
       cedure.
              proc returnX {} {1mreturn 22mX}
              puts [returnX]    ;# prints "X"

       Next,  a  more  complete  example,  using  1mreturn -code error 22mto report
       invalid arguments.
              proc factorial {n} {
                 if {![string is integer $n] || ($n < 0)} {
                    1mreturn 22m-code error \
                          "expected non-negative integer,\
                           but got \"$n\""
                 }
                 if {$n < 2} {
                    1mreturn 22m1
                 }
                 set m [expr {$n - 1}]
                 set code [catch {factorial $m} factor]
                 if {$code != 0} {
                    1mreturn 22m-code $code $factor
                 }
                 set product [expr {$n * $factor}]
                 if {$product < 0} {
                    1mreturn 22m-code error \
                          "overflow computing factorial of $n"
                 }
                 1mreturn 22m$product
              }

       Next, a procedure replacement for 1mbreak22m.
              proc myBreak {} {
                 1mreturn 22m-code break
              }


1mSEE ALSO0m
       break(n),  catch(n),   continue(n),   error(n),   proc(n),   source(n),
       tclvars(n)


1mKEYWORDS0m
