return man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

return(n)		     Tcl Built-In Commands		     return(n)

______________________________________________________________________________

NAME
       return - Return from a procedure, or set return code of a script

SYNOPSIS
       return ?result?

       return ?-code code? ?result?

       return ?option value ...? ?result?
_________________________________________________________________

DESCRIPTION
       In  its	simplest  usage, the return command is used without options in
       the body of a procedure to immediately return control to the caller  of
       the procedure.  If a result argument is provided, its value becomes the
       result of the procedure passed back to the caller.  If  result  is  not
       specified  then	an  empty string will be returned to the caller as the
       result of the procedure.

       The return command serves a similar function within script  files  that
       are  evaluated  by  the source command.	When source evaluates the con‐
       tents of a file as a script, an invocation of the return	 command  will
       cause  script evaluation to immediately cease, and the value result (or
       an empty string) will be returned as the result of the source command.

EXCEPTIONAL RETURN CODES
       In addition to the result of a procedure, the return code of  a	proce‐
       dure may also be set by return through use of the -code option.	In the
       usual case where the -code option is not specified the  procedure  will
       return  normally.  However, the -code option may be used to generate an
       exceptional return from the procedure.  Code may have any of  the  fol‐
       lowing values:

       ok (or 0)    Normal  return:   same  as	if the option is omitted.  The
		    return code of the procedure is 0 (TCL_OK).

       error (1)    Error return: the  return  code  of	 the  procedure	 is  1
		    (TCL_ERROR).  The procedure command behaves in its calling
		    context as if it were the command error result.  See below
		    for additional options.

       return (2)   The	 return	 code of the procedure is 2 (TCL_RETURN).  The
		    procedure command behaves in its calling context as if  it
		    were the command return (with no arguments).

       break (3)    The	 return	 code  of the procedure is 3 (TCL_BREAK).  The
		    procedure command behaves in its calling context as if  it
		    were the command break.

       continue (4) The return code of the procedure is 4 (TCL_CONTINUE).  The
		    procedure command behaves in its calling context as if  it
		    were the command continue.

       value	    Value  must	 be  an	 integer;   it will be returned as the
		    return code for the current procedure.

       When a procedure wants to signal that it has received invalid arguments
       from  its  caller,  it  may use return -code error with result set to a
       suitable error message.	Otherwise usage of the return -code option  is
       mostly limited to procedures that implement a new control structure.

       The  return  -code  command acts similarly within script files that are
       evaluated by the source command.	 During the evaluation of the contents
       of a file as a script by source, an invocation of the return -code code
       command will cause the return code of source to be code.

RETURN OPTIONS
       In addition to a result and a return code, evaluation of a  command  in │
       Tcl  also  produces  a dictionary of return options.  In general usage, │
       all option value pairs given as arguments to return become  entries  in │
       the  return  options  dictionary,  and any values at all are acceptable │
       except as noted below.  The catch command may be used to capture all of │
       this  information — the return code, the result, and the return options │
       dictionary — that arise from evaluation of a script.

       As documented above, the -code entry in the return  options  dictionary
       receives special treatment by Tcl.  There are other return options also
       recognized and treated specially by Tcl.	 They are:

       -errorcode list
	      The -errorcode option receives special treatment only  when  the
	      value  of the -code option is TCL_ERROR.	Then the list value is
	      meant to be additional information about the error, presented as
	      a Tcl list for further processing by programs.  If no -errorcode
	      option is provided to return when the -code error option is pro‐
	      vided,  Tcl  will	 set  the value of the -errorcode entry in the
	      return options dictionary to the default	value  of  NONE.   The
	      -errorcode return option will also be stored in the global vari‐
	      able errorCode.

       -errorinfo info
	      The -errorinfo option receives special treatment only  when  the
	      value  of	 the -code option is TCL_ERROR.	 Then info is the ini‐
	      tial stack trace, meant to provide to a human reader  additional
	      information  about the context in which the error occurred.  The
	      stack trace will also be stored in the  global  variable	error‐
	      Info.   If  no  -errorinfo option is provided to return when the
	      -code error option is provided, Tcl will provide its own initial
	      stack  trace  value  in the entry for -errorinfo.	 Tcl's initial
	      stack trace will include only the call  to  the  procedure,  and
	      stack  unwinding will append information about higher stack lev‐
	      els, but there will be no information about the context  of  the
	      error  within  the  procedure.  Typically the info value is sup‐
	      plied from the value of -errorinfo in a return  options  dictio‐
	      nary  captured  by  the  catch command (or from the copy of that
	      information stored in the global variable errorInfo).

       -level level
	      The -level and -code options work together  to  set  the	return │
	      code to be returned by one of the commands currently being eval‐ │
	      uated.  The level value must be a	 non-negative  integer	repre‐ │
	      senting  a  number  of levels on the call stack.	It defines the │
	      number of levels up the stack at which the return code of a com‐ │
	      mand  currently  being  evaluated	 should be code.  If no -level │
	      option is provided, the default value of level  is  1,  so  that │
	      return  sets  the return code that the current procedure returns │
	      to its caller, 1 level up the  call  stack.   The	 mechanism  by │
	      which these options work is described in more detail below.

       -options options
	      The  value  options  must be a valid dictionary.	The entries of │
	      that dictionary are treated as additional option value pairs for │
	      the return command.

RETURN CODE HANDLING MECHANISMS
       Return  codes are used in Tcl to control program flow.  A Tcl script is
       a sequence of Tcl commands.  So long as each command evaluation returns
       a  return  code of TCL_OK, evaluation will continue to the next command
       in the script.  Any exceptional return code (non-TCL_OK) returned by  a
       command	evaluation causes the flow on to the next command to be inter‐
       rupted.	Script evaluation ceases, and the exceptional return code from
       the  command  becomes  the  return  code of the full script evaluation.
       This is the mechanism by which errors during script evaluation cause an
       interruption and unwinding of the call stack.  It is also the mechanism
       by which commands like break, continue, and return cause script evalua‐
       tion to terminate without evaluating all commands in sequence.

       Some of Tcl's built-in commands evaluate scripts as part of their func‐
       tioning.	 These commands can make use of exceptional  return  codes  to
       enable  special	features.  For example, the built-in Tcl commands that
       provide loops — such as while, for, and foreach	—  evaluate  a	script
       that  is	 the body of the loop.	If evaluation of the loop body returns
       the return code of TCL_BREAK or	TCL_CONTINUE,  the  loop  command  can
       react  in  such	a way as to give the break and continue commands their
       documented interpretation in loops.

       Procedure invocation also involves evaluation of a script, the body  of │
       the  procedure.	 Procedure  invocation provides special treatment when │
       evaluation of the procedure body returns the  return  code  TCL_RETURN. │
       In that circumstance, the -level entry in the return options dictionary │
       is decremented.	If after decrementing, the value of the	 -level	 entry │
       is  0, then the value of the -code entry becomes the return code of the │
       procedure.  If after decrementing, the value of	the  -level  entry  is │
       greater than zero, then the return code of the procedure is TCL_RETURN. │
       If the procedure invocation occurred during the evaluation of the  body │
       of another procedure, the process will repeat itself up the call stack, │
       decrementing the value of the -level entry at each level, so  that  the │
       code will be the return code of the current command level levels up the │
       call stack.  The source command	performs  the  same  handling  of  the │
       TCL_RETURN return code, which explains the similarity of return invoca‐ │
       tion during a source to return invocation within a procedure.	       │

       The return code of the return command itself triggers this special han‐ │
       dling by procedure invocation.  If return is provided the option -level │
       0, then the return code of the return command itself will be the	 value │
       code  of	 the -code option (or TCL_OK by default).  Any other value for │
       the -level option (including the default value of  1)  will  cause  the │
       return code of the return command itself to be TCL_RETURN, triggering a │
       return from the enclosing procedure.

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

       Next,  an example of using return to set the value returned by the pro‐
       cedure.
	      proc returnX {} {return X}
	      puts [returnX]	;# prints "X"

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

       Next, a procedure replacement for break.
	      proc myBreak {} {
		 return -code break
	      }

       With  the -level 0 option, return itself can serve as a replacement for │
       break.								       │
	      interp alias {} Break {} return -level 0 -code break	       │

       An example of using catch and return  -options  to  re-raise  a	caught │
       error:								       │
	      proc doSomething {} {					       │
		 set resource [allocate]				       │
		 catch {						       │
		    # Long script of operations				       │
		    # that might raise an error				       │
		 } result options					       │
		 deallocate $resource					       │
		 return -options $options $result			       │
	      }								       │

       Finally	an  example  of advanced use of the return options to create a │
       procedure replacement for return itself:				       │
	      proc myReturn {args} {					       │
		 set result ""						       │
		 if {[llength $args] % 2} {				       │
		    set result [lindex $args end]			       │
		    set args [lrange $args 0 end-1]			       │
		 }							       │
		 set options [dict merge {-level 1} $args]		       │
		 dict incr options -levelreturn -options $options $result			       │
	      }								       │

SEE ALSO
       break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n),
       tclvars(n)

KEYWORDS
       break, catch, continue, error, procedure, return

Tcl				      8.5			     return(n)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net