diff options
| -rw-r--r-- | doc/CrtCommand.3 | 9 | ||||
| -rw-r--r-- | doc/CrtObjCmd.3 | 7 | ||||
| -rw-r--r-- | doc/catch.n | 10 | ||||
| -rw-r--r-- | doc/return.n | 5 | ||||
| -rw-r--r-- | generic/tcl.h | 4 |
5 files changed, 24 insertions, 11 deletions
diff --git a/doc/CrtCommand.3 b/doc/CrtCommand.3 index d15a920..5d25667 100644 --- a/doc/CrtCommand.3 +++ b/doc/CrtCommand.3 @@ -102,9 +102,12 @@ version 8.1 of Tcl. .PP \fIProc\fR must return an integer code that is expected to be one of \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or -\fBTCL_CONTINUE\fR. See the Tcl overview man page -for details on what these codes mean. Most normal commands will only -return \fBTCL_OK\fR or \fBTCL_ERROR\fR. In addition, \fIproc\fR must set +\fBTCL_CONTINUE\fR. See the \fBreturn\fR man page for details on +what these codes mean and the use of extended values for an extension's +private use. Most normal commands will only return \fBTCL_OK\fR +or \fBTCL_ERROR\fR. +.PP +In addition, \fIproc\fR must set the interpreter result; in the case of a \fBTCL_OK\fR return code this gives the result of the command, and in the case of \fBTCL_ERROR\fR it gives an error message. diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3 index 522f903..b28d901 100644 --- a/doc/CrtObjCmd.3 +++ b/doc/CrtObjCmd.3 @@ -132,9 +132,10 @@ that \fIobjv\fR[\fB2\fR] points at, but will not change where .PP \fIproc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR. -See the Tcl overview man page -for details on what these codes mean. Most normal commands will only -return \fBTCL_OK\fR or \fBTCL_ERROR\fR. +See the \fBreturn\fR man page for details on what these codes mean and the +use of extended values for an extension's private use. Most normal commands +will only return \fBTCL_OK\fR or \fBTCL_ERROR\fR. +.PP In addition, if \fIproc\fR needs to return a non-empty result, it can call \fBTcl_SetObjResult\fR to set the interpreter's result. In the case of a \fBTCL_OK\fR return code this gives the result diff --git a/doc/catch.n b/doc/catch.n index 8d885d4..0a2c513 100644 --- a/doc/catch.n +++ b/doc/catch.n @@ -30,10 +30,12 @@ return codes: 1 (\fBTCL_ERROR\fR), 2 (\fBTCL_RETURN\fR), 3 (\fBTCL_BREAK\fR), and 4 (\fBTCL_CONTINUE\fR). Errors during evaluation of a script are indicated by a return code of \fBTCL_ERROR\fR. The other exceptional return codes are returned by the \fBreturn\fR, \fBbreak\fR, and \fBcontinue\fR commands -and in other special situations as documented. Tcl packages can define -new commands that return other integer values as return codes as well, -and scripts that make use of the \fBreturn \-code\fR command can also -have return codes other than the five defined by Tcl. +and in other special situations as documented. +New commands defined by Tcl packages as well as scripts that make +use of the \fBreturn \-code\fR command can return other integer +values as the return code. These must however lie outside the range +reserved for Tcl as documented for the \fBreturn\fR command. + .PP If the \fIresultVarName\fR argument is given, then the variable it names is set to the result of the script evaluation. When the return code from the diff --git a/doc/return.n b/doc/return.n index 9bf1ae2..d285e87 100644 --- a/doc/return.n +++ b/doc/return.n @@ -78,7 +78,10 @@ were the command \fBcontinue\fR. \fIvalue\fR . \fIValue\fR must be an integer; it will be returned as the -return code for the current procedure. +return code for the current procedure. Applications +and packages should use values in the range 5 to 1073741823 (0x3fffffff) +for their own purposes. Values outside this range are reserved +for use by Tcl. .LP When a procedure wants to signal that it has received invalid arguments from its caller, it may use \fBreturn -code error\fR diff --git a/generic/tcl.h b/generic/tcl.h index b5630cc..c3f3516 100644 --- a/generic/tcl.h +++ b/generic/tcl.h @@ -515,6 +515,8 @@ typedef struct stat *Tcl_OldStat_; * exited; the interpreter's result is meaningless. * TCL_CONTINUE Go on to the next iteration of the current loop; the * interpreter's result is meaningless. + * Integer return codes in the range TCL_CODE_USER_MIN to TCL_CODE_USER_MAX are + * reserved for the use of packages. */ #define TCL_OK 0 @@ -522,6 +524,8 @@ typedef struct stat *Tcl_OldStat_; #define TCL_RETURN 2 #define TCL_BREAK 3 #define TCL_CONTINUE 4 +#define TCL_CODE_USER_MIN 5 +#define TCL_CODE_USER_MAX 0x3fffffff /* 1073741823 */ /* *---------------------------------------------------------------------------- |