diff options
Diffstat (limited to 'doc')
| -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/chan.n | 84 | ||||
| -rw-r--r-- | doc/close.n | 2 | ||||
| -rw-r--r-- | doc/eof.n | 2 | ||||
| -rw-r--r-- | doc/fblocked.n | 2 | ||||
| -rw-r--r-- | doc/fconfigure.n | 6 | ||||
| -rw-r--r-- | doc/fileevent.n | 4 | ||||
| -rw-r--r-- | doc/flush.n | 2 | ||||
| -rw-r--r-- | doc/format.n | 3 | ||||
| -rw-r--r-- | doc/gets.n | 2 | ||||
| -rw-r--r-- | doc/interp.n | 8 | ||||
| -rw-r--r-- | doc/namespace.n | 31 | ||||
| -rw-r--r-- | doc/puts.n | 2 | ||||
| -rw-r--r-- | doc/read.n | 4 | ||||
| -rw-r--r-- | doc/refchan.n | 66 | ||||
| -rw-r--r-- | doc/return.n | 5 | ||||
| -rw-r--r-- | doc/scan.n | 25 | ||||
| -rw-r--r-- | doc/seek.n | 2 | ||||
| -rw-r--r-- | doc/tell.n | 2 | ||||
| -rw-r--r-- | doc/transchan.n | 2 |
22 files changed, 143 insertions, 137 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 @@ -23,19 +23,19 @@ the process's standard input, output and error streams respectively). abbreviation for \fIoption\fR is acceptable. Valid options are: .\" METHOD: blocked .TP -\fBchan blocked \fIchannelId\fR +\fBchan blocked \fIchannel\fR . This tests whether the last input operation on the channel called -\fIchannelId\fR failed because it would have otherwise caused the +\fIchannel\fR failed because it would have otherwise caused the process to block, and returns 1 if that was the case. It returns 0 otherwise. Note that this only ever returns 1 when the channel has been configured to be non-blocking; all Tcl channels have blocking turned on by default. .\" METHOD: close .TP -\fBchan close \fIchannelId\fR ?\fIdirection\fR? +\fBchan close \fIchannel\fR ?\fIdirection\fR? . -Close and destroy the channel called \fIchannelId\fR. Note that this +Close and destroy the channel called \fIchannel\fR. Note that this deletes all existing file-events registered on the channel. If the \fIdirection\fR argument (which must be \fBread\fR or \fBwrite\fR or any unique abbreviation of them) is present, the channel will only be @@ -51,7 +51,7 @@ write-only channel for reading. As part of closing the channel, all buffered output is flushed to the channel's output device (only if the channel is ceasing to be writable), any buffered input is discarded (only if the channel is ceasing to be readable), -the underlying operating system resource is closed and \fIchannelId\fR becomes +the underlying operating system resource is closed and \fIchannel\fR becomes unavailable for future use (both only if the channel is being completely closed). .PP @@ -61,11 +61,11 @@ non-blocking and there is unflushed output, the channel remains open and the command returns immediately; output will be flushed in the background and the channel will be closed when all the flushing is complete. .PP -If \fIchannelId\fR is a blocking channel for a command pipeline then +If \fIchannel\fR is a blocking channel for a command pipeline then \fBchan close\fR waits for the child processes to complete. .PP If the channel is shared between interpreters, then \fBchan close\fR -makes \fIchannelId\fR unavailable in the invoking interpreter but has +makes \fIchannel\fR unavailable in the invoking interpreter but has no other effect until all of the sharing interpreters have closed the channel. When the last interpreter in which the channel is registered invokes \fBchan close\fR (or \fBclose\fR), the cleanup actions @@ -101,10 +101,10 @@ restores the previous behavior. .RE .\" METHOD: configure .TP -\fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... +\fBchan configure \fIchannel\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... . Query or set the configuration options of the channel named -\fIchannelId\fR. +\fIchannel\fR. .RS .PP If no \fIoptionName\fR or \fIvalue\fR arguments are supplied, the @@ -391,18 +391,18 @@ within the safe interpreter. .RE .\" METHOD: eof .TP -\fBchan eof \fIchannelId\fR +\fBchan eof \fIchannel\fR . Test whether the last input operation on the channel called -\fIchannelId\fR failed because the end of the data stream was reached, +\fIchannel\fR failed because the end of the data stream was reached, returning 1 if end-of-file was reached, and 0 otherwise. .\" METHOD: event .TP -\fBchan event \fIchannelId event\fR ?\fIscript\fR? +\fBchan event \fIchannel event\fR ?\fIscript\fR? . Arrange for the Tcl script \fIscript\fR to be installed as a \fIfile event handler\fR to be called whenever the channel called -\fIchannelId\fR enters the state described by \fIevent\fR (which must +\fIchannel\fR enters the state described by \fIevent\fR (which must be either \fBreadable\fR or \fBwritable\fR); only one such handler may be installed per event per channel at a time. If \fIscript\fR is the empty string, the current handler is deleted (this also happens if the @@ -468,9 +468,9 @@ loops due to buggy handlers. .RE .\" METHOD: flush .TP -\fBchan flush \fIchannelId\fR +\fBchan flush \fIchannel\fR . -Ensures that all pending output for the channel called \fIchannelId\fR +Ensures that all pending output for the channel called \fIchannel\fR is written. .RS .PP @@ -483,7 +483,7 @@ it. .RE .\" METHOD: gets .TP -\fBchan gets \fIchannelId\fR ?\fIvarName\fR? +\fBchan gets \fIchannel\fR ?\fIvarName\fR? . Reads a line from the channel consisting of all characters up to the next end-of-line sequence or until end of file is seen. The line feed character @@ -536,12 +536,12 @@ only those channel names that match it (according to the rules of \fBstring match\fR) will be returned. .\" METHOD: pending .TP -\fBchan pending \fImode channelId\fR +\fBchan pending \fImode channel\fR . Depending on whether \fImode\fR is \fBinput\fR or \fBoutput\fR, returns the number of bytes of input or output (respectively) currently buffered -internally for \fIchannelId\fR (especially useful in a readable event +internally for \fIchannel\fR (especially useful in a readable event callback to impose application-specific limits on input line lengths to avoid a potential denial-of-service attack where a hostile user crafts an extremely long line that exceeds the available memory to buffer it). @@ -572,20 +572,20 @@ allowed for. .RE .\" METHOD: pop .TP -\fBchan pop \fIchannelId\fR +\fBchan pop \fIchannel\fR . -Removes the topmost transformation from the channel \fIchannelId\fR, if there -is any. If there are no transformations added to \fIchannelId\fR, this is +Removes the topmost transformation from the channel \fIchannel\fR, if there +is any. If there are no transformations added to \fIchannel\fR, this is equivalent to \fBchan close\fR of that channel. The result is normally the empty string, but can be an error in some situations (i.e. where the underlying system stream is closed and that results in an error). .\" METHOD: postevent .TP -\fBchan postevent \fIchannelId eventSpec\fR +\fBchan postevent \fIchannel eventSpec\fR . This subcommand is used by command handlers specified with \fBchan create\fR. It notifies the channel represented by the handle -\fIchannelId\fR that the event(s) listed in the \fIeventSpec\fR have +\fIchannel\fR that the event(s) listed in the \fIeventSpec\fR have occurred. The argument has to be a list containing any of the strings \fBread\fR and \fBwrite\fR. The list must contain at least one element as it does not make sense to invoke the command if there are @@ -618,9 +618,9 @@ executed in the interpreter that set them up. .RE .\" METHOD: push .TP -\fBchan push \fIchannelId cmdPrefix\fR +\fBchan push \fIchannel cmdPrefix\fR . -Adds a new transformation on top of the channel \fIchannelId\fR. The +Adds a new transformation on top of the channel \fIchannel\fR. The \fIcmdPrefix\fR argument describes a list of one or more words which represent a handler that will be used to implement the transformation. The command prefix must provide the API described in the \fBtranschan\fR manual page. @@ -630,11 +630,11 @@ channel mode that it is used with or this can make the channel neither readable nor writable. .\" METHOD: puts .TP -\fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR +\fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannel\fR? \fIstring\fR . -Writes \fIstring\fR to the channel named \fIchannelId\fR followed by a +Writes \fIstring\fR to the channel named \fIchannel\fR followed by a newline character. A trailing newline character is written unless the -optional flag \fB\-nonewline\fR is given. If \fIchannelId\fR is +optional flag \fB\-nonewline\fR is given. If \fIchannel\fR is omitted, the string is written to the standard output channel, \fBstdout\fR. .RS @@ -654,7 +654,7 @@ flush\fR command. .PP When the output buffer fills up, the \fBchan puts\fR command will normally block until all the buffered data has been accepted for -output by the operating system. If \fIchannelId\fR is in non-blocking +output by the operating system. If \fIchannel\fR is in non-blocking mode then the \fBchan puts\fR command will not block even if the operating system cannot accept the data. Instead, Tcl continues to buffer the data and writes it in the background as fast as the @@ -675,12 +675,12 @@ may be partially written to the channel in this case. .RE .\" METHOD: read .TP -\fBchan read \fIchannelId\fR ?\fInumChars\fR? +\fBchan read \fIchannel\fR ?\fInumChars\fR? .TP -\fBchan read \fR?\fB\-nonewline\fR? \fIchannelId\fR +\fBchan read \fR?\fB\-nonewline\fR? \fIchannel\fR . In the first form, the result will be the next \fInumChars\fR -characters read from the channel named \fIchannelId\fR; if +characters read from the channel named \fIchannel\fR; if \fInumChars\fR is omitted, all characters up to the point when the channel would signal a failure (whether an end-of-file, blocked or other error condition) are read. In the second form (i.e. when @@ -689,7 +689,7 @@ given to indicate that any trailing newline in the string that has been read should be trimmed. .RS .PP -If \fIchannelId\fR is in non-blocking mode, \fBchan read\fR may not +If \fIchannel\fR is in non-blocking mode, \fBchan read\fR may not read as many characters as requested: once all available input has been read, the command will return the data that is available rather than blocking for more input. If the channel is configured to use a @@ -708,7 +708,7 @@ When reading from a serial port, most applications should configure the serial port channel to be non-blocking, like this: .PP .CS -\fBchan configure \fIchannelId \fB\-blocking \fI0\fR. +\fBchan configure \fIchannel \fB\-blocking \fI0\fR. .CE .PP Then \fBchan read\fR behaves much like described above. Note that @@ -716,12 +716,12 @@ most serial ports are comparatively slow; it is entirely possible to get a \fBreadable\fR event for each character read from them. Care must be taken when using \fBchan read\fR on blocking serial ports: .TP -\fBchan read \fIchannelId numChars\fR +\fBchan read \fIchannel numChars\fR . In this form \fBchan read\fR blocks until \fInumChars\fR have been received from the serial port. .TP -\fBchan read \fIchannelId\fR +\fBchan read \fIchannel\fR . In this form \fBchan read\fR blocks until the reception of the end-of-file character, see \fBchan configure -eofchar\fR. If there no @@ -745,10 +745,10 @@ changing the encoding in use. See \fBENCODING ERROR EXAMPLES\fR later. .RE .\" METHOD: seek .TP -\fBchan seek \fIchannelId offset\fR ?\fIorigin\fR? +\fBchan seek \fIchannel offset\fR ?\fIorigin\fR? . Sets the current access position within the underlying data stream for -the channel named \fIchannelId\fR to be \fIoffset\fR bytes relative to +the channel named \fIchannel\fR to be \fIoffset\fR bytes relative to \fIorigin\fR. \fIOffset\fR must be an integer (which may be negative) and \fIorigin\fR must be one of the following: .RS @@ -779,20 +779,20 @@ not characters, unlike \fBchan read\fR. .RE .\" METHOD: tell .TP -\fBchan tell \fIchannelId\fR +\fBchan tell \fIchannel\fR . Returns a number giving the current access position within the -underlying data stream for the channel named \fIchannelId\fR. This +underlying data stream for the channel named \fIchannel\fR. This value returned is a byte offset that can be passed to \fBchan seek\fR in order to set the channel to a particular position. Note that this value is in terms of bytes, not characters like \fBchan read\fR. The value returned is -1 for channels that do not support seeking. .\" METHOD: truncate .TP -\fBchan truncate \fIchannelId\fR ?\fIlength\fR? +\fBchan truncate \fIchannel\fR ?\fIlength\fR? . Sets the byte length of the underlying data stream for the channel -named \fIchannelId\fR to be \fIlength\fR (or to the current byte +named \fIchannel\fR to be \fIlength\fR (or to the current byte offset within the underlying data stream if \fIlength\fR is omitted). The channel is flushed before truncation. . diff --git a/doc/close.n b/doc/close.n index f3a61be..eecc48f 100644 --- a/doc/close.n +++ b/doc/close.n @@ -12,7 +12,7 @@ .SH NAME close \- Close an open channel .SH SYNOPSIS -\fBclose \fIchannelId\fR ?\fBr\fR(\fBead\fR)|\fBw\fR(\fBrite\fR)? +\fBclose \fIchannel\fR ?\fBr\fR(\fBead\fR)|\fBw\fR(\fBrite\fR)? .BE .SH DESCRIPTION .PP @@ -12,7 +12,7 @@ .SH NAME eof \- Check for end of file condition on channel .SH SYNOPSIS -\fBeof \fIchannelId\fR +\fBeof \fIchannel\fR .BE .SH DESCRIPTION .PP diff --git a/doc/fblocked.n b/doc/fblocked.n index 239c465..00fe7a7 100644 --- a/doc/fblocked.n +++ b/doc/fblocked.n @@ -10,7 +10,7 @@ .SH NAME fblocked \- Test whether the last input operation exhausted all available input .SH SYNOPSIS -\fBfblocked \fIchannelId\fR +\fBfblocked \fIchannel\fR .BE .SH DESCRIPTION .PP diff --git a/doc/fconfigure.n b/doc/fconfigure.n index 2870d54..e185122 100644 --- a/doc/fconfigure.n +++ b/doc/fconfigure.n @@ -12,9 +12,9 @@ fconfigure \- Set and get options on a channel .SH SYNOPSIS .nf -\fBfconfigure \fIchannelId\fR -\fBfconfigure \fIchannelId name\fR -\fBfconfigure \fIchannelId name value \fR?\fIname value ...\fR? +\fBfconfigure \fIchannel\fR +\fBfconfigure \fIchannel name\fR +\fBfconfigure \fIchannel name value \fR?\fIname value ...\fR? .fi .BE .SH DESCRIPTION diff --git a/doc/fileevent.n b/doc/fileevent.n index 4ba534a..d90e376 100644 --- a/doc/fileevent.n +++ b/doc/fileevent.n @@ -13,9 +13,9 @@ .SH NAME fileevent \- Execute a script when a channel becomes readable or writable .SH SYNOPSIS -\fBfileevent \fIchannelId \fBreadable \fR?\fIscript\fR? +\fBfileevent \fIchannel \fBreadable \fR?\fIscript\fR? .sp -\fBfileevent \fIchannelId \fBwritable \fR?\fIscript\fR? +\fBfileevent \fIchannel \fBwritable \fR?\fIscript\fR? .BE .SH DESCRIPTION .PP diff --git a/doc/flush.n b/doc/flush.n index 259f4cb..956750e 100644 --- a/doc/flush.n +++ b/doc/flush.n @@ -12,7 +12,7 @@ .SH NAME flush \- Flush buffered output for a channel .SH SYNOPSIS -\fBflush \fIchannelId\fR +\fBflush \fIchannel\fR .BE .SH DESCRIPTION .PP diff --git a/doc/format.n b/doc/format.n index 59774fc..b1e204a 100644 --- a/doc/format.n +++ b/doc/format.n @@ -141,8 +141,7 @@ element of the \fBtcl_platform\fR array. If it is \fBL\fR it specifies that an integer or double value is taken without truncation for conversion to a formatted substring. If neither of those are present, the integer value is -truncated to the range determined by the value of the -\fBwordSize\fR element of the \fBtcl_platform\fR array). +truncated to a 32-bit range. .SS "MANDATORY CONVERSION TYPE" .PP The last thing in a conversion specifier is an alphabetic character @@ -12,7 +12,7 @@ .SH NAME gets \- Read a line from a channel .SH SYNOPSIS -\fBgets \fIchannelId\fR ?\fIvarName\fR? +\fBgets \fIchannel\fR ?\fIvarName\fR? .BE .SH DESCRIPTION .PP diff --git a/doc/interp.n b/doc/interp.n index 2c08533..74745be 100644 --- a/doc/interp.n +++ b/doc/interp.n @@ -392,9 +392,9 @@ the maximum size of the C stack. .RE .\" METHOD: share .TP -\fBinterp share\fI srcPath channelId destPath\fR +\fBinterp share\fI srcPath channel destPath\fR . -Causes the IO channel identified by \fIchannelId\fR to become shared +Causes the IO channel identified by \fIchannel\fR to become shared between the interpreter identified by \fIsrcPath\fR and the interpreter identified by \fIdestPath\fR. Both interpreters have the same permissions on the IO channel. @@ -415,9 +415,9 @@ invoking interpreter or one of its descendants then an error is generated. The target command does not have to be defined at the time of this invocation. .\" METHOD: transfer .TP -\fBinterp transfer\fI srcPath channelId destPath\fR +\fBinterp transfer\fI srcPath channel destPath\fR . -Causes the IO channel identified by \fIchannelId\fR to become available in +Causes the IO channel identified by \fIchannel\fR to become available in the interpreter identified by \fIdestPath\fR and unavailable in the interpreter identified by \fIsrcPath\fR. .SH "CHILD COMMAND" diff --git a/doc/namespace.n b/doc/namespace.n index 5f02082..c19791c 100644 --- a/doc/namespace.n +++ b/doc/namespace.n @@ -495,8 +495,10 @@ However, if the name does not start with a \fB::\fR (i.e., is \fIrelative\fR), Tcl follows basic rules for looking it up: .IP \(bu -\fBVariable names\fR are always resolved by looking first in the current -namespace, and then in the global namespace. +\fBVariable names\fR are always resolved starting in the current +namespace. In the absence of special resolvers, foo::bar::baz refers to +a variable named "baz" in a namespace named "bar" that is a child of a +namespace named "foo" that is a child of the current namespace of the interpreter. .IP \(bu \fBCommand names\fR are always resolved by looking in the current namespace first. If not found there, they are searched for in every namespace on the @@ -516,10 +518,9 @@ set traceLevel 0 } .CE .PP -Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR -and then in the global namespace. +Tcl looks for \fBtraceLevel\fR in the namespace \fBDebug\fR. It looks up the command \fBprintTrace\fR in the same way. -If a variable or command name is not found in either context, +If a variable or command name is not found, the name is undefined. To make this point absolutely clear, consider the following example: .PP @@ -534,11 +535,9 @@ set traceLevel 0 } .CE .PP -Here Tcl looks for \fBtraceLevel\fR first in the namespace \fBFoo::Debug\fR. -Since it is not found there, Tcl then looks for it -in the global namespace. -The variable \fBFoo::traceLevel\fR is completely ignored -during the name resolution process. +Here Tcl looks for \fBtraceLevel\fR in the namespace \fBFoo::Debug\fR. +The variables \fBFoo::traceLevel\fR and \fBFoo::Debug::traceLevel\fR +are completely ignored during the name resolution process. .PP You can use the \fBnamespace which\fR command to clear up any question about name resolution. @@ -548,19 +547,19 @@ For example, the command: \fBnamespace eval\fR Foo::Debug {\fBnamespace which\fR -variable traceLevel} .CE .PP -returns \fB::traceLevel\fR. -On the other hand, the command, +returns the empty string. +The command, .PP .CS \fBnamespace eval\fR Foo {\fBnamespace which\fR -variable traceLevel} .CE .PP -returns \fB::Foo::traceLevel\fR. +returns the empty string as well. .PP As mentioned above, -namespace names are looked up differently -than the names of variables and commands. -Namespace names are always resolved in the current namespace. +namespace names and variables are looked up differently +than the names of commands. +Namespace names and variables are always resolved in the current namespace. This means, for example, that a \fBnamespace eval\fR command that creates a new namespace always creates a child of the current namespace @@ -12,7 +12,7 @@ .SH NAME puts \- Write to a channel .SH SYNOPSIS -\fBputs \fR?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR +\fBputs \fR?\fB\-nonewline\fR? ?\fIchannel\fR? \fIstring\fR .BE .SH DESCRIPTION .PP @@ -12,9 +12,9 @@ .SH NAME read \- Read from a channel .SH SYNOPSIS -\fBread \fR?\fB\-nonewline\fR? \fIchannelId\fR +\fBread \fR?\fB\-nonewline\fR? \fIchannel\fR .sp -\fBread \fIchannelId numChars\fR +\fBread \fIchannel numChars\fR .BE .SH DESCRIPTION .PP diff --git a/doc/refchan.n b/doc/refchan.n index b997ddb..4f78a7b 100644 --- a/doc/refchan.n +++ b/doc/refchan.n @@ -14,16 +14,16 @@ refchan \- command handler API of reflected channels .nf \fBchan create \fImode cmdPrefix\fR -\fIcmdPrefix \fBblocking\fI channelId mode\fR -\fIcmdPrefix \fBcget\fI channelId option\fR -\fIcmdPrefix \fBcgetall\fI channelId\fR -\fIcmdPrefix \fBconfigure\fI channelId option value\fR -\fIcmdPrefix \fBfinalize\fI channelId\fR -\fIcmdPrefix \fBinitialize\fI channelId mode\fR -\fIcmdPrefix \fBread\fI channelId count\fR -\fIcmdPrefix \fBseek\fI channelId offset base\fR -\fIcmdPrefix \fBwatch\fI channelId eventspec\fR -\fIcmdPrefix \fBwrite\fI channelId data\fR +\fIcmdPrefix \fBblocking\fI channel mode\fR +\fIcmdPrefix \fBcget\fI channel option\fR +\fIcmdPrefix \fBcgetall\fI channel\fR +\fIcmdPrefix \fBconfigure\fI channel option value\fR +\fIcmdPrefix \fBfinalize\fI channel\fR +\fIcmdPrefix \fBinitialize\fI channel mode\fR +\fIcmdPrefix \fBread\fI channel count\fR +\fIcmdPrefix \fBseek\fI channel offset base\fR +\fIcmdPrefix \fBwatch\fI channel eventspec\fR +\fIcmdPrefix \fBwrite\fI channel data\fR .fi .BE .SH DESCRIPTION @@ -44,10 +44,10 @@ other subcommands is optional. .SS "MANDATORY SUBCOMMANDS" .\" METHOD: initialize .TP -\fIcmdPrefix \fBinitialize \fIchannelId mode\fR +\fIcmdPrefix \fBinitialize \fIchannel mode\fR . An invocation of this subcommand will be the first call the -\fIcmdPrefix\fR will receive for the specified new \fIchannelId\fR. It +\fIcmdPrefix\fR will receive for the specified new \fIchannel\fR. It is the responsibility of this subcommand to set up any internal data structures required to keep track of the channel and its state. .RS @@ -75,13 +75,13 @@ supported by the \fIcmdPrefix\fR. .RE .\" METHOD: finalize .TP -\fIcmdPrefix \fBfinalize \fIchannelId\fR +\fIcmdPrefix \fBfinalize \fIchannel\fR . An invocation of this subcommand will be the last call the -\fIcmdPrefix\fR will receive for the specified \fIchannelId\fR. It will +\fIcmdPrefix\fR will receive for the specified \fIchannel\fR. It will be generated just before the destruction of the data structures of the channel held by the Tcl core. The command handler \fImust not\fR -access the \fIchannelId\fR anymore in no way. Upon this subcommand being +access the \fIchannel\fR anymore in no way. Upon this subcommand being called, any internal resources allocated to this channel must be cleaned up. .RS @@ -98,10 +98,10 @@ aborted during \fBinitialize\fR (See above). .RE .\" METHOD: watch .TP -\fIcmdPrefix \fBwatch \fIchannelId eventspec\fR +\fIcmdPrefix \fBwatch \fIchannel eventspec\fR . This subcommand notifies the \fIcmdPrefix\fR that the specified -\fIchannelId\fR is interested in the events listed in the +\fIchannel\fR is interested in the events listed in the \fIeventspec\fR. This argument is a list containing any of \fBread\fR and \fBwrite\fR. The list may be empty, which signals that the channel does not wish to be notified of any events. In that situation, @@ -119,10 +119,10 @@ event which was not listed in the last call to \fBwatch\fR will cause .SS "OPTIONAL SUBCOMMANDS" .\" METHOD: read .TP -\fIcmdPrefix \fBread \fIchannelId count\fR +\fIcmdPrefix \fBread \fIchannel count\fR . This \fIoptional\fR subcommand is called when the user requests data from the -channel \fIchannelId\fR. \fIcount\fR specifies how many \fIbytes\fR have been +channel \fIchannel\fR. \fIcount\fR specifies how many \fIbytes\fR have been requested. If the subcommand is not supported then it is not possible to read from the channel handled by the command. .RS @@ -176,10 +176,10 @@ etc.) is treated as and converted to an error. .RE .\" METHOD: write .TP -\fIcmdPrefix \fBwrite \fIchannelId data\fR +\fIcmdPrefix \fBwrite \fIchannel data\fR . This \fIoptional\fR subcommand is called when the user writes data to -the channel \fIchannelId\fR. The \fIdata\fR argument contains \fIbytes\fR, not +the channel \fIchannel\fR. The \fIdata\fR argument contains \fIbytes\fR, not characters. Any type of transformation (EOL, encoding) configured for the channel has already been applied at this point. If this subcommand is not supported then it is not possible to write to the channel @@ -234,11 +234,11 @@ as and converted to an error. .RE .\" METHOD: seek .TP -\fIcmdPrefix \fBseek \fIchannelId offset base\fR +\fIcmdPrefix \fBseek \fIchannel offset base\fR . This \fIoptional\fR subcommand is responsible for the handling of \fBchan seek\fR and \fBchan tell\fR requests on the channel -\fIchannelId\fR. If it is not supported then seeking will not be possible for +\fIchannel\fR. If it is not supported then seeking will not be possible for the channel. .RS .PP @@ -271,10 +271,10 @@ the new location identical to the current one, which is then returned. .RE .\" METHOD: configure .TP -\fIcmdPrefix \fBconfigure \fIchannelId option value\fR +\fIcmdPrefix \fBconfigure \fIchannel option value\fR . This \fIoptional\fR subcommand is for setting the type-specific options of -channel \fIchannelId\fR. The \fIoption\fR argument indicates the option to be +channel \fIchannel\fR. The \fIoption\fR argument indicates the option to be written, and the \fIvalue\fR argument indicates the value to set the option to. .RS .PP @@ -291,10 +291,10 @@ converted to an error. .RE .\" METHOD: cget .TP -\fIcmdPrefix \fBcget \fIchannelId option\fR +\fIcmdPrefix \fBcget \fIchannel option\fR . This \fIoptional\fR subcommand is used when reading a single type-specific -option of channel \fIchannelId\fR. If this subcommand is supported then the +option of channel \fIchannel\fR. If this subcommand is supported then the subcommand \fBcgetall\fR must be supported as well. .RS .PP @@ -307,10 +307,10 @@ will appear to have thrown this error. Any exception beyond \fIerror\fR .RE .\" METHOD: cgetall .TP -\fIcmdPrefix \fBcgetall \fIchannelId\fR +\fIcmdPrefix \fBcgetall \fIchannel\fR . This \fIoptional\fR subcommand is used for reading all type-specific options -of channel \fIchannelId\fR. If this subcommand is supported then the +of channel \fIchannel\fR. If this subcommand is supported then the subcommand \fBcget\fR has to be supported as well. .RS .PP @@ -324,10 +324,10 @@ will appear to have thrown this error. Any exception beyond \fBerror\fR .RE .\" METHOD: blocking .TP -\fIcmdPrefix \fBblocking \fIchannelId mode\fR +\fIcmdPrefix \fBblocking \fIchannel mode\fR . This \fIoptional\fR subcommand handles changes to the blocking mode of the -channel \fIchannelId\fR. The \fImode\fR is a boolean flag. A true value means +channel \fIchannel\fR. The \fImode\fR is a boolean flag. A true value means that the channel has to be set to blocking, and a false value means that the channel should be non-blocking. .RS @@ -341,10 +341,10 @@ etc.) is treated as and converted to an error. .RE .\" METHOD: truncate .TP -\fIcmdPrefix \fBtruncate\fI channelId length\fR +\fIcmdPrefix \fBtruncate\fI channel length\fR . This \fIoptional\fR subcommand handles changing the length of the -underlying data stream for the channel \fIchannelId\fR. Its length +underlying data stream for the channel \fIchannel\fR. Its length gets set to \fIlength\fR. .RS .PP 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 @@ -73,17 +73,18 @@ The size modifier field is used only when scanning a substring into one of Tcl's integer values. The size modifier field dictates the integer range acceptable to be stored in a variable, or, for the inline case, in a position in the result list. -The syntactically valid values for the size modifier are \fBh\fR, \fBL\fR, -\fBl\fR, \fBz\fR, \fBt\fR, and \fBll\fR. The \fBh\fR size -modifier value is equivalent -to the absence of a size modifier in the the conversion specifier. -Either one indicates the integer range to be stored is limited to the range -determined by the value of the \fBwordSize\fR element of the \fBtcl_platform\fR -array). The \fBL\fR, \fBq\fR or \fBj\fR size modifiers are equivalent to the -\fBl\fR size modifier. Either of them indicates the integer range to be stored is -limited to the same range produced by the \fBwide()\fR function of -the \fBexpr\fR command. The \fBll\fR size modifier indicates that -the integer range to be stored is unlimited. +The syntactically valid values for the size modifier are \fBh\fR, +\fBl\fR, \fBz\fR, \fBt\fR, \fBq\fR, \fBj\fR, \fBll\fR, and \fBL\fR. +The \fBh\fR size modifier value is equivalent to the absence of a size +modifier in the the conversion specifier. Either one indicates the +integer range to be stored is limited to the 32-bit range. The \fBL\fR +size modifier is equivalent to the \fBll\fR size modifier. Either one +indicates the integer range to be stored is unlimited. The \fBl\fR (or +\fBq\fR or \fBj\fR) size modifier indicates that the integer range to be +stored is limited to the same range produced by the \fBwide()\fR function +of the \fBexpr\fR command. The \fBz\fR and \fBt\fR modifiers indicate the +integer range to be the same as for either \fBh\fR or \fBl\fR, depending +on the value of the \fBpointerSize\fR element of the \fBtcl_platform\fR array. .SS "MANDATORY CONVERSION CHARACTER" .PP The following conversion characters are supported: @@ -248,8 +249,6 @@ An interactive session demonstrating the truncation of integer values determined by size modifiers: .PP .CS -\fI%\fR set tcl_platform(wordSize) -4 \fI%\fR scan 20000000000000000000 %d 2147483647 \fI%\fR scan 20000000000000000000 %ld @@ -12,7 +12,7 @@ .SH NAME seek \- Change the access position for an open channel .SH SYNOPSIS -\fBseek \fIchannelId offset \fR?\fIorigin\fR? +\fBseek \fIchannel offset \fR?\fIorigin\fR? .BE .SH DESCRIPTION .PP @@ -12,7 +12,7 @@ .SH NAME tell \- Return current access position for an open channel .SH SYNOPSIS -\fBtell \fIchannelId\fR +\fBtell \fIchannel\fR .BE .SH DESCRIPTION .PP diff --git a/doc/transchan.n b/doc/transchan.n index abae7b9..d174d23 100644 --- a/doc/transchan.n +++ b/doc/transchan.n @@ -12,7 +12,7 @@ transchan \- command handler API of channel transforms .SH SYNOPSIS .nf -\fBchan push \fIchannelId cmdPrefix\fR +\fBchan push \fIchannel cmdPrefix\fR \fIcmdPrefix \fBclear \fIhandle\fR \fIcmdPrefix \fBdrain \fIhandle\fR |