diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Access.3 | 2 | ||||
| -rw-r--r-- | doc/AddErrInfo.3 | 4 | ||||
| -rw-r--r-- | doc/Alloc.3 | 4 | ||||
| -rw-r--r-- | doc/Eval.3 | 4 | ||||
| -rw-r--r-- | doc/ObjectType.3 | 2 | ||||
| -rw-r--r-- | doc/Preserve.3 | 5 | ||||
| -rw-r--r-- | doc/SaveInterpState.3 | 57 | ||||
| -rw-r--r-- | doc/SetResult.3 | 243 | ||||
| -rw-r--r-- | doc/StringObj.3 | 13 | ||||
| -rw-r--r-- | doc/Thread.3 | 5 | ||||
| -rw-r--r-- | doc/chan.n | 862 | ||||
| -rw-r--r-- | doc/configurable.n | 2 | ||||
| -rw-r--r-- | doc/encoding.n | 218 | ||||
| -rw-r--r-- | doc/expr.n | 8 | ||||
| -rw-r--r-- | doc/http.n | 2 | ||||
| -rw-r--r-- | doc/safe.n | 24 | ||||
| -rw-r--r-- | doc/scan.n | 23 | ||||
| -rw-r--r-- | doc/socket.n | 2 | ||||
| -rw-r--r-- | doc/transchan.n | 2 |
19 files changed, 886 insertions, 596 deletions
diff --git a/doc/Access.3 b/doc/Access.3 index 5a32e08..aaca223 100644 --- a/doc/Access.3 +++ b/doc/Access.3 @@ -33,7 +33,7 @@ The structure that contains the result. .BE .SH DESCRIPTION .PP -As of Tcl 8.4, the object-based APIs \fBTcl_FSAccess\fR and \fBTcl_FSStat\fR +The object-based APIs \fBTcl_FSAccess\fR and \fBTcl_FSStat\fR should be used in preference to \fBTcl_Access\fR and \fBTcl_Stat\fR, wherever possible. Those functions also support Tcl's virtual filesystem layer, which these do not. diff --git a/doc/AddErrInfo.3 b/doc/AddErrInfo.3 index 05b20b8..2ed5eee 100644 --- a/doc/AddErrInfo.3 +++ b/doc/AddErrInfo.3 @@ -28,7 +28,7 @@ int .sp \fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR) .sp -\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fBNULL\fR) +\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *)NULL\fR) .sp int \fBTcl_GetErrorLine\fR(\fIinterp\fR) @@ -67,7 +67,7 @@ If negative, all bytes up to the first null byte are used. The \fB\-errorcode\fR return option will be set to this value. .AP "const char" *element in String to record as one element of the \fB\-errorcode\fR return option. -Last \fIelement\fR argument must be NULL. +Last \fIelement\fR argument must be (char *)NULL. .AP int lineNum The line number of a script where an error occurred. .AP "const char" *script in diff --git a/doc/Alloc.3 b/doc/Alloc.3 index 493eebc..999c1e8 100644 --- a/doc/Alloc.3 +++ b/doc/Alloc.3 @@ -13,7 +13,7 @@ Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, Tcl_GetM .nf \fB#include <tcl.h>\fR .sp -char * +void * \fBTcl_Alloc\fR(\fIsize\fR) .sp \fBTcl_Free\fR(\fIptr\fR) @@ -33,7 +33,7 @@ void * .AS char *size .AP "size_t" size in Size in bytes of the memory block to allocate. -.AP char *ptr in +.AP void *ptr in Pointer to memory block to free or realloc. .AP Tcl_DString *dsPtr in Initialized DString pointer. @@ -37,7 +37,7 @@ int \fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR) .sp int -\fBTcl_VarEval\fR(\fIinterp, part, part, ... \fBNULL\fR) +\fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *)NULL\fR) .fi .SH ARGUMENTS .AS Tcl_Interp **termPtr @@ -138,7 +138,7 @@ of any length, concatenates them into a single string, then calls \fBTcl_Eval\fR to execute that string as a Tcl command. It returns the result of the command and also modifies the interpreter result in the same way as \fBTcl_Eval\fR. -The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end +The last argument to \fBTcl_VarEval\fR must be (char *)NULL to indicate the end of arguments. .SH "FLAG BITS" diff --git a/doc/ObjectType.3 b/doc/ObjectType.3 index e9a38cc..ca9e0ce 100644 --- a/doc/ObjectType.3 +++ b/doc/ObjectType.3 @@ -154,7 +154,7 @@ This definition permits us to pass internal representations and pointers to them as arguments and results in public routines. .SH "THE TCL_OBJTYPE STRUCTURE" .PP -Extension writers can define new value types by defining four to eight +Extension writers can define new value types by defining four to twelve procedures and initializing a Tcl_ObjType structure to describe the type. Extension writers may also pass a pointer to their Tcl_ObjType structure to \fBTcl_RegisterObjType\fR if they wish to permit other diff --git a/doc/Preserve.3 b/doc/Preserve.3 index e01cf80..d676b9a 100644 --- a/doc/Preserve.3 +++ b/doc/Preserve.3 @@ -81,14 +81,11 @@ type \fBTcl_FreeProc\fR: .PP .CS typedef void \fBTcl_FreeProc\fR( - char *\fIblockPtr\fR); + void *\fIblockPtr\fR); .CE .PP The \fIblockPtr\fR argument to \fIfreeProc\fR will be the same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR. -The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the -\fIclientData\fR argument to \fBTcl_EventuallyFree\fR for historical -reasons, but the value is the same. .PP When the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR refers to storage allocated and returned by a prior call to diff --git a/doc/SaveInterpState.3 b/doc/SaveInterpState.3 index 96fecdb..619ff0b 100644 --- a/doc/SaveInterpState.3 +++ b/doc/SaveInterpState.3 @@ -1,7 +1,6 @@ '\" '\" Copyright (c) 1997 Sun Microsystems, Inc. '\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright) -'\" Copyright (c) 2018 Nathan Coulter. '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -10,8 +9,7 @@ .so man.macros .BS .SH NAME -Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState \- Save and restore the -state of an an interpreter. +Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState \- save and restore an interpreter's state .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -27,29 +25,50 @@ int .SH ARGUMENTS .AS Tcl_InterpState savedPtr .AP Tcl_Interp *interp in -The interpreter for the operation. +Interpreter for which state should be saved. .AP int status in -The return code for the state. +Return code value to save as part of interpreter state. .AP Tcl_InterpState state in -A token for saved state. +Saved state token to be restored or discarded. .BE .SH DESCRIPTION .PP -These routines save the state of an interpreter before a call to a routine such -as \fBTcl_Eval\fR, and restore the state afterwards. +These routines allows a C procedure to take a snapshot of the current +state of an interpreter so that it can be restored after a call +to \fBTcl_Eval\fR or some other routine that modifies the interpreter +state. .PP -\fBTcl_SaveInterpState\fR saves the parts of \fIinterp\fR that comprise the -result of a script, including the resulting value, the return code passed as -\fIstatus\fR, and any options such as \fB\-errorinfo\fR and \fB\-errorcode\fR. -It returns a token for the saved state. The interpreter result is not reset -and no interpreter state is changed. +\fBTcl_SaveInterpState\fR stores a snapshot of the interpreter state in +an opaque token returned by \fBTcl_SaveInterpState\fR. That token +value may then be passed back to one of \fBTcl_RestoreInterpState\fR +or \fBTcl_DiscardInterpState\fR, depending on whether the interp +state is to be restored. So long as one of the latter two routines +is called, Tcl will take care of memory management. .PP -\fBTcl_RestoreInterpState\fR restores the state indicated by \fIstate\fR and -returns the \fIstatus\fR originally passed in the corresponding call to -\fBTcl_SaveInterpState\fR. +\fBTcl_SaveInterpState\fR takes a snapshot of those portions of +interpreter state that make up the full result of script evaluation. +This include the interpreter result, the return code (passed in +as the \fIstatus\fR argument, and any return options, including +\fB\-errorinfo\fR and \fB\-errorcode\fR when an error is in progress. +This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR. +The call to \fBTcl_SaveInterpState\fR does not itself change the +state of the interpreter. .PP -If a saved state is not restored, \fBTcl_DiscardInterpState\fR must be called -to release it. A token used to discard or restore state must not be used -again. +\fBTcl_RestoreInterpState\fR accepts a \fBTcl_InterpState\fR token +previously returned by \fBTcl_SaveInterpState\fR and restores the +state of the interp to the state held in that snapshot. The return +value of \fBTcl_RestoreInterpState\fR is the status value originally +passed to \fBTcl_SaveInterpState\fR when the snapshot token was +created. +.PP +\fBTcl_DiscardInterpState\fR is called to release a \fBTcl_InterpState\fR +token previously returned by \fBTcl_SaveInterpState\fR when that +snapshot is not to be restored to an interp. +.PP +The \fBTcl_InterpState\fR token returned by \fBTcl_SaveInterpState\fR +must eventually be passed to either \fBTcl_RestoreInterpState\fR +or \fBTcl_DiscardInterpState\fR to avoid a memory leak. Once +the \fBTcl_InterpState\fR token is passed to one of them, the +token is no longer valid and should not be used anymore. .SH KEYWORDS result, state, interp diff --git a/doc/SetResult.3 b/doc/SetResult.3 index 4d0c9df..d3201aa 100644 --- a/doc/SetResult.3 +++ b/doc/SetResult.3 @@ -24,7 +24,7 @@ Tcl_Obj * const char * \fBTcl_GetStringResult\fR(\fIinterp\fR) .sp -\fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fBNULL\fR) +\fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fB(char *)NULL\fR) .sp \fBTcl_ResetResult\fR(\fIinterp\fR) .sp @@ -35,105 +35,210 @@ const char * .SH ARGUMENTS .AS Tcl_FreeProc sourceInterp out .AP Tcl_Interp *interp out -The interpreter get or set the result for. +Interpreter whose result is to be modified or read. .AP Tcl_Obj *objPtr in -A value to set the result to. +Tcl value to become result for \fIinterp\fR. .AP char *result in -The string value set the result to, or to append to the existing result. +String value to become result for \fIinterp\fR or to be +appended to the existing result. .AP "const char" *element in -The string value to append as a list element +String value to append as a list element to the existing result of \fIinterp\fR. .AP Tcl_FreeProc *freeProc in -Pointer to a procedure to call to release storage at -\fIresult\fR. +Address of procedure to call to release storage at +\fIresult\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or +\fBTCL_VOLATILE\fR. .AP Tcl_Interp *sourceInterp in -The interpreter to transfer the result and return options from. +Interpreter that the result and return options should be transferred from. .AP Tcl_Interp *targetInterp in -The interpreter to transfer the result and return options to. +Interpreter that the result and return options should be transferred to. .AP int code in Return code value that controls transfer of return options. .BE .SH DESCRIPTION .PP -These procedures manipulate the result of an interpreter. Some procedures -provide a Tcl_Obj interface while others provide a string interface. For -example, \fBTcl_SetObjResult\fR accepts a Tcl_Obj and \fBTcl_SetResult\fR -accepts a char *. Similarly, \fBTcl_GetObjResult\fR produces a Tcl_Obj * and -\fBTcl_GetStringResult\fR produces a char *. The procedures can be mixed and -matched. For example, if \fBTcl_SetObjResult\fR is called to set the result to -a Tcl_Obj value, and then \fBTcl_GetStringResult\fR is called, it returns a -char * (but see caveats below). +The procedures described here are utilities for manipulating the +result value in a Tcl interpreter. +The interpreter result may be either a Tcl value or a string. +For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR +set the interpreter result to, respectively, a value and a string. +Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR +return the interpreter result as a value and as a string. +The procedures always keep the string and value forms +of the interpreter result consistent. +For example, if \fBTcl_SetObjResult\fR is called to set +the result to a value, +then \fBTcl_GetStringResult\fR is called, +it will return the value's string representation. .PP -\fBTcl_SetObjResult\fR sets \fIobjPtr\fR as the result for \fIinterp\fR, +\fBTcl_SetObjResult\fR +arranges for \fIobjPtr\fR to be the result for \fIinterp\fR, replacing any existing result. +The result is left pointing to the value +referenced by \fIobjPtr\fR. +\fIobjPtr\fR's reference count is incremented +since there is now a new reference to it from \fIinterp\fR. +The reference count for any old result value +is decremented and the old result value is freed if no +references to it remain. .PP -\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR, without -incrementing its reference count. -.PP -\fBTcl_SetResult\fR sets \fIresult\fR as the result for \fIinterp\fR, replacing -any existing result, and calls \fIfreeProc\fR to free \fIresult\fR. See \fBTHE -TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below. If \fIresult\fR is -\fBNULL\fR, ignores \fIfreeProc\fR and sets the result for \fIinterp\fR to -point to the empty string. -.PP -\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string, i.e. -the bytes of the Tcl_Obj for the result, which can be decoded using -\fBTcl_UtfToExternal\fR. This value is freed when its corresponding Tcl_Obj is -freed.Programmers are encouraged to use the newer Tcl_Obj API procedures, e.g. -to call \fBTcl_GetObjResult\fR instead. -.PP -\fBTcl_ResetResult\fR sets the empty string as the result for \fIinterp\fR and -clears the error state managed by \fBTcl_AddErrorInfo\fR, -\fBTcl_AddObjErrorInfo\fR, and \fBTcl_SetErrorCode\fR. -.PP -\fBTcl_AppendResult\fR builds up a result from smaller pieces, appending each -\fIresult\fR in order to the current result for \fIinterp\fR. It may be called -repeatedly as additional pieces of the result are produced, and manages the -storage for the \fIinterp\fR's result, allocating a larger result area if -necessary. It also manages conversion to and from the \fIresult\fR field of -the \fIinterp\fR to handle backward-compatibility with old-style extensions. -Any number of \fIresult\fR arguments may be passed in a single call; the last -argument in the list must be a NULL pointer. -.PP -\fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR to -\fItargetInterp\fR, both of which must have been created in the same thread, -resets the result in \fIsourceInterp\fR, and moves the return options -dictionary as controlled by the return code value \fIcode\fR in the same manner -as \fBTcl_GetReturnOptions\fR. +\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as a value. +The value's reference count is not incremented; +if the caller needs to retain a long-term pointer to the value +they should use \fBTcl_IncrRefCount\fR to increment its reference count +in order to keep it from being freed too early or accidentally changed. +.PP +\fBTcl_SetResult\fR +arranges for \fIresult\fR to be the result for the current Tcl +command in \fIinterp\fR, replacing any existing result. +The \fIfreeProc\fR argument specifies how to manage the storage +for the \fIresult\fR argument; +it is discussed in the section +\fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below. +If \fIresult\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored +and \fBTcl_SetResult\fR +re-initializes \fIinterp\fR's result to point to an empty string. +.PP +\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string. +If the result was set to a value by a \fBTcl_SetObjResult\fR call, +the value form will be converted to a string and returned. +If the value's string representation contains null bytes, +this conversion will lose information. +For this reason, programmers are encouraged to +write their code to use the new value API procedures +and to call \fBTcl_GetObjResult\fR instead. +.PP +\fBTcl_ResetResult\fR clears the result for \fIinterp\fR +and leaves the result in its normal empty initialized state. +If the result is a value, +its reference count is decremented and the result is left +pointing to an unshared value representing an empty string. +If the result is a dynamically allocated string, its memory is free*d +and the result is left as a empty string. +\fBTcl_ResetResult\fR also clears the error state managed by +\fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR, +and \fBTcl_SetErrorCode\fR. .PP -If \fIsourceInterp\fR and \fItargetInterp\fR are the same, nothing is done. +\fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces. +It takes each of its \fIresult\fR arguments and appends them in order +to the current result associated with \fIinterp\fR. +If the result is in its initialized empty state (e.g. a command procedure +was just invoked or \fBTcl_ResetResult\fR was just called), +then \fBTcl_AppendResult\fR sets the result to the concatenation of +its \fIresult\fR arguments. +\fBTcl_AppendResult\fR may be called repeatedly as additional pieces +of the result are produced. +\fBTcl_AppendResult\fR takes care of all the +storage management issues associated with managing \fIinterp\fR's +result, such as allocating a larger result area if necessary. +It also manages conversion to and from the \fIresult\fR field of the +\fIinterp\fR so as to handle backward-compatibility with old-style +extensions. +Any number of \fIresult\fR arguments may be passed in a single +call; the last argument in the list must be (char *)NULL. +.PP +\fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR +to \fItargetInterp\fR. The two interpreters must have been created in the +same thread. If \fIsourceInterp\fR and \fItargetInterp\fR are the same, +nothing is done. Otherwise, \fBTcl_TransferResult\fR moves the result +from \fIsourceInterp\fR to \fItargetInterp\fR, and resets the result +in \fIsourceInterp\fR. It also moves the return options dictionary as +controlled by the return code value \fIcode\fR in the same manner +as \fBTcl_GetReturnOptions\fR. .SH "DEPRECATED INTERFACES" .SS "OLD STRING PROCEDURES" .PP -The following procedures are deprecated since they manipulate the Tcl result as -a string. Procedures such as \fBTcl_SetObjResult\fR can be significantly more -efficient. -.PP -\fBTcl_AppendElement\fR is like \fBTcl_AppendResult\fR, but it appends only one -piece, and also appends that piece as a list item. -\fBTcl_AppendElement\fR adds backslashes or braces as necessary to ensure that -\fIelement\fR is properly formatted as a list item. Under normal conditions, -\fBTcl_AppendElement\fR adds a space character to \fIinterp\fR's result just -before adding the new list element, so that the list elements in the result are -properly separated. However if the new list element is the first item in the -list or sublist (i.e. \fIinterp\fR's current result is empty, or consists of -the single character +Use of the following procedures is deprecated +since they manipulate the Tcl result as a string. +Procedures such as \fBTcl_SetObjResult\fR +that manipulate the result as a value +can be significantly more efficient. +.PP +\fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in +that it allows results to be built up in pieces. +However, \fBTcl_AppendElement\fR takes only a single \fIelement\fR +argument and it appends that argument to the current result +as a proper Tcl list element. +\fBTcl_AppendElement\fR adds backslashes or braces if necessary +to ensure that \fIinterp\fR's result can be parsed as a list and that +\fIelement\fR will be extracted as a single element. +Under normal conditions, \fBTcl_AppendElement\fR will add a space +character to \fIinterp\fR's result just before adding the new +list element, so that the list elements in the result are properly +separated. +However if the new list element is the first in a list or sub-list +(i.e. \fIinterp\fR's current result is empty, or consists of the +single character .QW { , or ends in the characters .QW " {" ) then no space is added. .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT" .PP -\fIFreeProc\fR has the following type: +\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how +the Tcl system is to manage the storage for the \fIresult\fR argument. +If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called +at a time when \fIinterp\fR holds a string result, +they do whatever is necessary to dispose of the old string result +(see the \fBTcl_Interp\fR manual entry for details on this). +.PP +If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIresult\fR +refers to an area of static storage that is guaranteed not to be +modified until at least the next call to \fBTcl_Eval\fR. +If \fIfreeProc\fR +is \fBTCL_DYNAMIC\fR it means that \fIresult\fR was allocated with a call +to \fBTcl_Alloc\fR and is now the property of the Tcl system. +\fBTcl_SetResult\fR will arrange for the string's storage to be +released by calling \fBTcl_Free\fR when it is no longer needed. +If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIresult\fR +points to an area of memory that is likely to be overwritten when +\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame). +In this case \fBTcl_SetResult\fR will make a copy of the string in +dynamically allocated storage and arrange for the copy to be the +result for the current Tcl command. +.PP +If \fIfreeProc\fR is not one of the values \fBTCL_STATIC\fR, +\fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address +of a procedure that Tcl should call to free the string. +This allows applications to use non-standard storage allocators. +When Tcl no longer needs the storage for the string, it will +call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and +result that match the type \fBTcl_FreeProc\fR: .PP .CS typedef void \fBTcl_FreeProc\fR( - char *\fIblockPtr\fR); + void *\fIblockPtr\fR); .CE .PP -When \fIfreeProc\fR is called, \fIblockPtr\fR is the \fIresult\fR value passed -to \fBTcl_SetResult\fR. +When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to +the value of \fIresult\fR passed to \fBTcl_SetResult\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +The interpreter result is one of the main places that owns references to +values, along with the bytecode execution stack, argument lists, variables, +and the list and dictionary collection values. +.PP +\fBTcl_SetObjResult\fR takes a value with an arbitrary reference count +\fI(specifically including zero)\fR and guarantees to increment the reference +count. If code wishes to continue using the value after setting it as the +result, it should add its own reference to it with \fBTcl_IncrRefCount\fR. +.PP +\fBTcl_GetObjResult\fR returns the current interpreter result value. This will +have a reference count of at least 1. If the caller wishes to keep the +interpreter result value, it should increment its reference count. +.PP +\fBTcl_GetStringResult\fR does not manipulate reference counts, but the string +it returns is owned by (and has a lifetime controlled by) the current +interpreter result value; it should be copied instead of being relied upon to +persist after the next Tcl API call, as most Tcl operations can modify the +interpreter result. +.PP +\fBTcl_SetResult\fR, \fBTcl_AppendResult\fR, +\fBTcl_AppendElement\fR, and \fBTcl_ResetResult\fR all modify the interpreter +result. They may cause the old interpreter result to have its reference count +decremented and a new interpreter result to be allocated. After they have been +called, the reference count of the interpreter result is guaranteed to be 1. .SH "SEE ALSO" Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp, Tcl_GetReturnOptions diff --git a/doc/StringObj.3 b/doc/StringObj.3 index 6f7d359..4682cae 100644 --- a/doc/StringObj.3 +++ b/doc/StringObj.3 @@ -19,8 +19,10 @@ Tcl_Obj * Tcl_Obj * \fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR) .sp +void \fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR) .sp +void \fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR) .sp char * @@ -44,14 +46,19 @@ Tcl_Size Tcl_Obj * \fBTcl_GetRange\fR(\fIobjPtr, first, last\fR) .sp +void \fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR) .sp +void \fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR) .sp +void \fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR) .sp -\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fBNULL\fR) +void +\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *)NULL\fR) .sp +void \fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR) .sp Tcl_Obj * @@ -63,8 +70,10 @@ int Tcl_Obj * \fBTcl_ObjPrintf\fR(\fIformat, ...\fR) .sp +void \fBTcl_AppendPrintfToObj\fR(\fIobjPtr, format, ...\fR) .sp +void \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR) .sp int @@ -242,7 +251,7 @@ except that it can be passed more than one value to append and each value must be a null-terminated string (i.e. none of the values may contain internal null characters). Any number of \fIstring\fR arguments may be provided, but the last argument -must be a NULL pointer to indicate the end of the list. +must be (char *)NULL to indicate the end of the list. .PP \fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR except that it imposes a limit on how many bytes are appended. diff --git a/doc/Thread.3 b/doc/Thread.3 index cb63570..2e5cd0a 100644 --- a/doc/Thread.3 +++ b/doc/Thread.3 @@ -76,10 +76,7 @@ waited upon into it. .SH INTRODUCTION Beginning with the 8.1 release, the Tcl core is thread safe, which allows you to incorporate Tcl into multithreaded applications without -customizing the Tcl core. Starting with the 8.6 release, Tcl -multithreading support is on by default. To disable Tcl multithreading -support, you must include the \fB\-\|\-disable-threads\fR option to -\fBconfigure\fR when you configure and compile your Tcl core. +customizing the Tcl core. .PP An important constraint of the Tcl threads implementation is that \fIonly the thread that created a Tcl interpreter can use that @@ -1,6 +1,5 @@ '\" '\" Copyright (c) 2005-2006 Donal K. Fellows -'\" Copyright (c) 2021 Nathan Coulter '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -9,68 +8,85 @@ .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -chan \- Reads, writes and manipulates channels. +chan \- Read, write and manipulate channels .SH SYNOPSIS -\fBchan \fIoperation\fR ?\fIarg arg ...\fR? +\fBchan \fIoption\fR ?\fIarg arg ...\fR? .BE .SH DESCRIPTION .PP -\fBchan\fR provides several operations for reading from, writing to, and -otherwise manipulating channels, e.g. those created by \fBopen\fR and -\fBsocket\fR, or the default channels \fBstdin\fR, \fBstdout\fR or \fBstderr\fR -which correspond respectively to the standard input, output, and error streams -of the process. Any unique abbreviation for \fIoperation\fR is acceptable. -Available operations are: +This command provides several operations for reading from, writing to +and otherwise manipulating open channels (such as have been created +with the \fBopen\fR and \fBsocket\fR commands, or the default named +channels \fBstdin\fR, \fBstdout\fR or \fBstderr\fR which correspond to +the process's standard input, output and error streams respectively). +\fIOption\fR indicates what to do with the channel; any unique +abbreviation for \fIoption\fR is acceptable. Valid options are: .\" METHOD: blocked .TP -\fBchan blocked \fIchannelName\fR +\fBchan blocked \fIchannelId\fR . -Returns 1 when the channel is in non-blocking mode and the last input operation -on the channel failed because it would have otherwise caused the process to -block, and 0 otherwise. Each Tcl channel is in blocking mode unless configured -otherwise. +This tests whether the last input operation on the channel called +\fIchannelId\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 \fIchannelName\fR ?\fIdirection\fR? +\fBchan close \fIchannelId\fR ?\fIdirection\fR? . -Closes and destroys the named channel deleting any existing event handlers -established for the channel. The command returns the empty string. If -\fIdirection\fR is given, it is \fBread\fR, or \fBwrite\fR, or any unique -abbreviation of those words, and only that side of the channel is closed. I.e. a -read-write channel may become read-only or write-only. Closing a read-only -channel for reading, or closing a write-only channel for writing is the same as -simply closing the channel. It is an error to close a read-only channel for -writing or to close a write-only channel for reading. +Close and destroy the channel called \fIchannelId\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 +half-closed, so that it can go from being read-write to write-only or +read-only respectively. If a read-only channel is closed for reading, it is +the same as if the channel is fully closed, and respectively similar for +write-only channels. Without the \fIdirection\fR argument, the channel is +closed for both reading and writing (but only if those directions are +currently open). It is an error to close a read-only channel for writing, or a +write-only channel for reading. .RS .PP -When a channel is closed for writing, any buffered output on the channel is -flushed. When a channel is closed for reading, any buffered input is discarded. -When a channel is destroyed the underlying resource is closed and the channel -is thereafter unavailable. -.PP -\fBchan close\fR fully flushes any output before closing the write side of a -channel unless it is non-blocking mode, where it returns immediately and the -channel is flushed in the background before finally being closed. -.PP -\fBchan close\fR may return an error if an error occurs while flushing -output. If a process in a command pipeline created by \fBopen\fR returns an -error (either by returning a non-zero exit code or writing to its standard -error file descriptor), \fBchan close\fR generates an error in the same -manner as \fBexec\fR. -.PP -Closing one side of a socket or command pipeline may lead to the shutdown() or -close() of the underlying system resource, leading to a reaction from whatever -is on the other side of the pipeline or socket. -.PP -If the channel for a command pipeline is in blocking mode, \fBchan close\fR -waits for the connected processes to complete. -.PP -\fBchan close\fR only affects the current interpreter. If the channel is open -in any other interpreter, its state is unchanged there. See \fBinterp\fR for a -description of channel sharing. -.PP -When the last interpreter sharing a channel is destroyed, the channel is -switched to blocking mode and fully flushed and then closed. +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 +unavailable for future use (both only if the channel is being completely +closed). +.PP +If the channel is blocking and the channel is ceasing to be writable, the +command does not return until all output is flushed. If the channel is +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 +\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 +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 +described above occur. With half-closing, the half-close of the channel only +applies to the current interpreter's view of the channel until all channels +have closed it in that direction (or completely). +See the \fBinterp\fR command for a description of channel sharing. +.PP +Channels are automatically fully closed when an interpreter is destroyed and +when the process exits. Channels are switched to blocking mode, to +ensure that all output is correctly flushed before the process exits. +.PP +The command returns an empty string, and may generate an error if +an error occurs while flushing output. If a command in a command +pipeline created with \fBopen\fR returns an error, \fBchan close\fR +generates an error (similar to the \fBexec\fR command.) +.PP +Note that half-closes of sockets and command pipelines can have important side +effects because they result in a shutdown() or close() of the underlying +system resource, which can change how other processes or systems respond to +the Tcl program. .PP Channels are automatically closed when an interpreter is destroyed and when the process exits. @@ -85,81 +101,105 @@ restores the previous behavior. .RE .\" METHOD: configure .TP -\fBchan configure \fIchannelName\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... +\fBchan configure \fIchannelId\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... . -Configures or retrieves the configuration of the channel \fIchannelName\fR. +Query or set the configuration options of the channel named +\fIchannelId\fR. .RS .PP -If no \fIoptionName\fR or \fIvalue\fR arguments are given, -\fBchan configure\fR returns a dictionary of option names and -values for the channel. If \fIoptionName\fR is supplied without a \fIvalue\fR, -\fBchan configure\fR returns the current value of the named option. If one or -more pairs of \fIoptionName\fR and \fIvalue\fR are supplied, -\fBchan configure\fR sets each of the named options to the corresponding -\fIvalue\fR and returns the empty string. -.PP -The options described below are supported for all channels. Each type of -channel may provide additional options. Those options are described in the -relevant documentation. For example, additional options are documented for -\fBsocket\fR, and also for serial devices at \fBopen\fR. +If no \fIoptionName\fR or \fIvalue\fR arguments are supplied, the +command returns a list containing alternating option names and values +for the channel. If \fIoptionName\fR is supplied but no \fIvalue\fR +then the command returns the current value of the given option. If +one or more pairs of \fIoptionName\fR and \fIvalue\fR are supplied, +the command sets each of the named options to the corresponding +\fIvalue\fR; in this case the return value is an empty string. +.PP +The options described below are supported for all channels. In +addition, each channel type may add options that only it supports. See +the manual entry for the command that creates each type of channel +for the options supported by that specific type of channel. For +example, see the manual entry for the \fBsocket\fR command for additional +options for sockets, and the \fBopen\fR command for additional options for +serial devices. +.RE .\" OPTION: -blocking .TP \fB\-blocking\fI boolean\fR . -If \fB\-blocking\fR is set to \fBtrue\fR (default), reading the channel -or writing to it may cause the process to block indefinitely. Otherwise, -operations such as \fBchan gets\fR, \fBchan read\fR, \fBchan puts\fR, \fBchan -flush\fR, and \fBchan close\fR take care not to block. Non-blocking mode in -general requires that the event loop is entered, e.g. by calling -\fBTcl_DoOneEvent\fR or \fBvwait\fR or by using Tk, to give Tcl a chance to -process events on the channel. +The \fB\-blocking\fR option determines whether I/O operations on the +channel can cause the process to block indefinitely. The value of the +option must be a proper boolean value. Channels are normally in +blocking mode; if a channel is placed into non-blocking mode it will +affect the operation of the \fBchan gets\fR, \fBchan read\fR, \fBchan +puts\fR, \fBchan flush\fR, and \fBchan close\fR commands; see the +documentation for those commands for details. For non-blocking mode to +work correctly, the application must be using the Tcl event loop +(e.g. by calling \fBTcl_DoOneEvent\fR or invoking the \fBvwait\fR +command). .\" OPTION: -buffering .TP \fB\-buffering\fI newValue\fR . -If \fInewValue\fR is \fBfull\fR, which is the default, output is buffered -until the internal buffer is full or until \fBchan flush\fR is called. If -\fInewValue\fR is \fBline\fR, output is flushed each time a end-of-line -character is written. If \fInewValue\fR is \fBnone\fR, output is flushed after -every output operation. For \fBstdin\fR, \fBstdout\fR, and channels that -connect to terminal-like devices, the default value is \fBline\fR. For -\fBstderr\fR the default value is \fBnone\fR. +If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output +until its internal buffer is full or until the \fBchan flush\fR +command is invoked. If \fInewValue\fR is \fBline\fR, then the I/O +system will automatically flush output for the channel whenever a +newline character is output. If \fInewValue\fR is \fBnone\fR, the I/O +system will flush automatically after every output operation. The +default is for \fB\-buffering\fR to be set to \fBfull\fR except for +channels that connect to terminal-like devices; for these channels the +initial setting is \fBline\fR. Additionally, \fBstdin\fR and +\fBstdout\fR are initially set to \fBline\fR, and \fBstderr\fR is set +to \fBnone\fR. .\" OPTION: -buffersize .TP \fB\-buffersize\fI newSize\fR . -\fInewSize\fR, an integer no greater than one million, is the size in bytes of -any input or output buffers subsequently allocated for this channel. +\fInewSize\fR must be an integer; its value is used to set the size +of buffers, in bytes, subsequently allocated for this channel to store +input or output. \fInewSize\fR must be a number of no more than one +million, allowing buffers of up to one million bytes in size. .\" OPTION: -encoding .TP \fB\-encoding\fR \fIname\fR . -Sets the encoding of the channel to \fIname\fR which should be one of the names -returned by \fBencoding names\fR, or -.QW \fBbinary\fR -\&. Input is converted from the encoding into Unicode, and output is converted -from Unicode to the encoding. +This option is used to specify the encoding of the channel as one of +the named encodings returned by \fBencoding names\fR or the special +value \fBbinary\fR, so that the data can be converted to and from +Unicode for use in Tcl. For instance, in order for Tcl to read +characters from a Japanese file in \fBshiftjis\fR and properly process +and display the contents, the encoding would be set to \fBshiftjis\fR. +Thereafter, when reading from the channel, the bytes in the Japanese +file would be converted to Unicode as they are read. Writing is also +supported \- as Tcl strings are written to the channel they will +automatically be converted to the specified encoding on output. .RS .PP -\fBbinary\fR is an alias for \fBiso8859-1\fR. This alone is not sufficient for -working with binary data. Use \fB\-translation binary\fR instead. -.PP -The encoding of a new channel is the value of \fBencoding system\fR, -which returns the platform- and locale-dependent system encoding used to -interface with the operating system, +If a file contains pure binary data (for instance, a JPEG image), the +encoding for the channel should be configured to be \fBbinary\fR. Tcl +will then assign no interpretation to the data in the file and simply +read or write raw bytes. The Tcl \fBbinary\fR command can be used to +manipulate this byte-oriented data. It is usually better to set the +\fB\-translation\fR option to \fBbinary\fR when you want to transfer +binary data, as this turns off the other automatic interpretations of +the bytes in the stream as well. +.PP +The default encoding for newly opened channels is the same platform- +and locale-dependent system encoding used for interfacing with the +operating system, as returned by \fBencoding system\fR. .RE .\" OPTION: -eofchar .TP \fB\-eofchar\fI char\fR . -\fIchar\fR signals the end of the data when it is encountered in the input. -If \fIchar\fR is the empty string, there is no special character that marks -the end of the data. -.RS -.PP -The default value is the empty string. The acceptable range is \ex01 - -\ex7F. A value outside this range results in an error. -.RE +This option supports DOS file systems that use Control-z (\ex1A) as an +end of file marker. If \fIchar\fR is not an empty string, then this +character signals end-of-file when it is encountered during input. +Otherwise (the default) there is no special end of file character marker. +The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7f; +attempting to set \fB\-eofchar\fR to a value outside of this range will +generate an error. .VS "TCL8.7 TIP656" .\" OPTION: -profile .TP @@ -177,32 +217,41 @@ profiles. .TP \fB\-translation\fR \fB{\fIinTranslation outTranslation\fB}\fR . -In Tcl a single line feed (\en) represents the end of a line. However, -at the destination the end of a line may be represented differently on -different platforms, or even for different devices on the same platform. For -example, under UNIX line feed is used in files and a -carriage-return-linefeed sequence is normally used in network connections. -Therefore, on input, e.g. with \fBchan gets\fR and \fBchan read\fR, each -external end-of-line character is translated into a line feed. On -output, e.g. with \fBchan puts\fR, each line feed is translated to the external -end-of-line character. The default translation, \fBauto\fR, handles all the -common cases, and \fB\-translation\fR provides explicit control over the -end-of-line character. +In Tcl scripts the end of a line is always represented using a single +newline character (\en). However, in actual files and devices the end +of a line may be represented differently on different platforms, or +even for different devices on the same platform. For example, under +UNIX newlines are used in files, whereas carriage-return-linefeed +sequences are normally used in network connections. On input (i.e., +with \fBchan gets\fR and \fBchan read\fR) the Tcl I/O system +automatically translates the external end-of-line representation into +newline characters. Upon output (i.e., with \fBchan puts\fR), the I/O +system translates newlines to the external end-of-line representation. +The default translation mode, \fBauto\fR, handles all the common cases +automatically, but the \fB\-translation\fR option provides explicit +control over the end of line translations. .RS .PP -Returns the input translation for a read-only channel, the output translation -for a write-only channel, and both the input translation and the output -translation for a read-write channel. When two translations are given, they -are the input and output translation, respectively. When only one translation -is given for a read-write channel, it is the translation for both input and -output. The following values are currently supported: +The value associated with \fB\-translation\fR is a single item for +read-only and write-only channels. The value is a two-element list for +read-write channels; the read translation mode is the first element of +the list, and the write translation mode is the second element. As a +convenience, when setting the translation mode for a read-write channel +you can specify a single value that will apply to both reading and +writing. When querying the translation mode of a read-write channel, a +two-element list will always be returned. The following values are +currently supported: .IP \fBauto\fR -The default. For input each occurrence of a line feed (\fBlf\fR), carriage -return (\fBcr\fR), or carriage return followed by a line feed (\fBcrlf\fR) is -translated into a line feed. For output, each line feed is translated into a -platform-specific representation: For all Unix variants it is \fBlf\fR, and -for all Windows variants it is \fBcrlf\fR, except that for sockets on all -platforms it is \fBcrlf\fR for both input and output. +As the input translation mode, \fBauto\fR treats any of newline +(\fBlf\fR), carriage return (\fBcr\fR), or carriage return followed by +a newline (\fBcrlf\fR) as the end of line representation. The end of +line representation can even change from line-to-line, and all cases +are translated to a newline. As the output translation mode, +\fBauto\fR chooses a platform specific representation; for sockets on +all platforms Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses +\fBlf\fR, and for the various flavors of Windows it chooses +\fBcrlf\fR. The default setting for \fB\-translation\fR is \fBauto\fR +for both input and output. .IP \fBbinary\fR Like \fBlf\fR, no end-of-line translation is performed, but in addition, sets \fB\-eofchar\fR to the empty string to disable it, and sets \fB\-encoding\fR @@ -215,21 +264,24 @@ in the data remains in the range of 0 to 255 so that there is no distinction between binary data and text. For example, A JPEG image can be read from a such a channel, manipulated, and then written back to such a channel. .IP \fBcr\fR -The end of a line is represented in the external data by a single carriage -return character. For input, each carriage return is translated to a line -feed, and for output each line feed character is translated to a carriage -return. +The end of a line in the underlying file or device is represented by a +single carriage return character. As the input translation mode, +\fBcr\fR mode converts carriage returns to newline characters. As the +output translation mode, \fBcr\fR mode translates newline characters +to carriage returns. .IP \fBcrlf\fR -The end of a line is represented in the external data by a carriage return -character followed by a line feed. For input, each carriage-return-linefeed -sequence is translated to a line feed. For output, each line feed is -translated to a carriage-return-linefeed sequence. This translation is -typically used for network connections, and also on Windows systems. +The end of a line in the underlying file or device is represented by a +carriage return character followed by a linefeed character. As the +input translation mode, \fBcrlf\fR mode converts +carriage-return-linefeed sequences to newline characters. As the +output translation mode, \fBcrlf\fR mode translates newline characters +to carriage-return-linefeed sequences. This mode is typically used on +Windows platforms and for network connections. .IP \fBlf\fR -The end of a line in the external data is represented by a line feed so no -translations occur during either input or output. This translation is -typically used on UNIX platforms, -.RE +The end of a line in the underlying file or device is represented by a +single newline (linefeed) character. In this mode no translations +occur during either input or output. This mode is typically used on +UNIX platforms. .RE .\" METHOD: copy .TP @@ -274,81 +326,108 @@ error. .TP \fBchan create \fImode cmdPrefix\fR . -Creates a new channel, called a \fBreflected\fR channel, with \fIcmdPrefix\fR -as its handler, and returns the name of the channel. \fBcmdPrefix\fR is the -first words of a command that provides the interface for a \fBrefchan\fR. +This subcommand creates a new script level channel using the command +prefix \fIcmdPrefix\fR as its handler. Any such channel is called a +\fBreflected\fR channel. The specified command prefix, \fBcmdPrefix\fR, +must be a non-empty list, and should provide the API described in the +\fBrefchan\fR manual page. The handle of the new channel is +returned as the result of the \fBchan create\fR command, and the +channel is open. Use either \fBclose\fR or \fBchan close\fR to remove +the channel. .RS .PP -\fBImode\fR is a list of one or more of the strings +The argument \fImode\fR specifies if the new channel is opened for +reading, writing, or both. It has to be a list containing any of the +strings .QW \fBread\fR or .QW \fBwrite\fR , -indicating whether the channel is a read channel, a write channel, or both. -It is an error if the handler does not support the chosen mode. -.PP -The handler is called as needed from the global namespace at the top level, and -command resolution happens there at the time of the call. If the handler is -renamed or deleted any subsequent attempt to call it is an error, which may -not be able to describe the failure. -.PP -The handler is always called in the interpreter and thread it was created in, -even if the channel was shared with or moved into a different interpreter in a -different thread. This is achieved through event dispatch, so if the event -loop is not entered, e.g. by calling \fBTcl_DoOneEvent\fR or \fBvwait\fR or -using Tk, the thread performing the channel operation \fIblocks -indefinitely\fR, resulting in deadlock. -.PP -One side of a channel may be in one thread while the other side is in a -different thread, providing a stream-oriented bridge between the threads. This -provides a method for regular stream communication between threads as an -alternative to sending commands. -.PP -When the interpreter the handler is in is deleted each channel associated with -the handler is deleted as well, regardless of which interpreter or thread it -is currently in or shared with. -.PP -\fBchan create\fR is \fBsafe\fR and is accessible to safe interpreters. The -handler is always called in the safe interpreter it was created in. +The list must have at least one +element, as a channel you can neither write to nor read from makes no +sense. The handler command for the new channel must support the chosen +mode, or an error is thrown. +.PP +The command prefix is executed in the global namespace, at the top of +call stack, following the appending of arguments as described in the +\fBrefchan\fR manual page. Command resolution happens at the +time of the call. Renaming the command, or destroying it means that +the next call of a handler method may fail, causing the channel +command invoking the handler to fail as well. Depending on the +subcommand being invoked, the error message may not be able to explain +the reason for that failure. +.PP +Every channel created with this subcommand knows which interpreter it +was created in, and only ever executes its handler command in that +interpreter, even if the channel was shared with and/or was moved into +a different interpreter. Each reflected channel also knows the thread +it was created in, and executes its handler command only in that +thread, even if the channel was moved into a different thread. To this +end all invocations of the handler are forwarded to the original +thread by posting special events to it. This means that the original +thread (i.e. the thread that executed the \fBchan create\fR command) +must have an active event loop, i.e. it must be able to process such +events. Otherwise the thread sending them will \fIblock +indefinitely\fR. Deadlock may occur. +.PP +Note that this permits the creation of a channel whose two endpoints +live in two different threads, providing a stream-oriented bridge +between these threads. In other words, we can provide a way for +regular stream communication between threads instead of having to send +commands. +.PP +When a thread or interpreter is deleted, all channels created with +this subcommand and using this thread/interpreter as their computing +base are deleted as well, in all interpreters they have been shared +with or moved into, and in whatever thread they have been transferred +to. While this pulls the rug out under the other thread(s) and/or +interpreter(s), this cannot be avoided. Trying to use such a channel +will cause the generation of a regular error about unknown channel +handles. +.PP +This subcommand is \fBsafe\fR and made accessible to safe +interpreters. While it arranges for the execution of arbitrary Tcl +code the system also makes sure that the code is always executed +within the safe interpreter. .RE .\" METHOD: eof .TP -\fBchan eof \fIchannelName\fR +\fBchan eof \fIchannelId\fR . -Returns 1 if the last read on the channel failed because the end of the data -was already reached, and 0 otherwise. +Test whether the last input operation on the channel called +\fIchannelId\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 \fIchannelName event\fR ?\fIscript\fR? +\fBchan event \fIchannelId event\fR ?\fIscript\fR? . -Arranges for the given script, called a \fBchannel event handler\fR, to be -called whenever the given event, one of -.QW \fBreadable\fR -or -.QW \fBwritable\fR -occurs on the given channel, replacing any script that was previously set. If -\fIscript\fR is the empty string the current handler is deleted. It is also -deleted when the channel is closed. If \fIscript\fR is omitted, either the -existing script or the empty string is returned. The event loop must be -entered, e.g. via \fBvwait\fR or \fBupdate\fR, or by using Tk, for handlers to -be evaluated. +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 +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 +channel is closed or the interpreter deleted). If \fIscript\fR is +omitted, the currently installed script is returned (or an empty +string if no such handler is installed). The callback is only +performed if the event loop is being serviced (e.g. via \fBvwait\fR or +\fBupdate\fR). .RS .PP -\fIscript\fR is evaluated at the global level in the interpreter it was -established in. Any resulting error is handled in the background, i.e. via -\fBinterp bgerror\fR. In order to prevent an endless loop due to a buggy -handler, the handler is deleted if \fIscript\fR returns an error so that it is -not evaluated again. -.PP -Without an event handler, \fBchan gets\fR or \fBchan read\fR on a channel in -blocking mode may block until data becomes available, during which the -thread is unable to perform other work or respond to events on other channels. -This could cause the application to appear to +A file event handler is a binding between a channel and a script, such +that the script is evaluated whenever the channel becomes readable or +writable. File event handlers are most commonly used to allow data to +be received from another process on an event-driven basis, so that the +receiver can continue to interact with the user or with other channels +while waiting for the data to arrive. If an application invokes +\fBchan gets\fR or \fBchan read\fR on a blocking channel when there is +no input data available, the process will block; until the input data +arrives, it will not be able to service other events, so it will +appear to the user to .QW "freeze up" \&. -Channel event handlers allow events on the channel to direct channel handling -so that the reader or writer can continue to perform other processing while -waiting for a channel to become available and then handle channel operations -when the channel is ready for the operation. +With \fBchan event\fR, the +process can tell when data is present and only invoke \fBchan gets\fR +or \fBchan read\fR when they will not block. .PP A channel is considered to be readable if there is unread data available on the underlying device. A channel is also considered to @@ -364,29 +443,47 @@ there is no special check for end of file, an infinite loop may occur where \fIscript\fR reads no data, returns, and is immediately invoked again. .PP -A channel is considered to be writable if at least one byte of data can be -written to the underlying file or device without blocking, or if an error -condition is present. Note that client sockets opened in asynchronous mode -become writable when they become connected or if the connection fails. -.PP -Event-driven channel handling works best for channels in non-blocking mode. A -channel in blocking mode blocks when \fBchan puts\fR writes more data than the -channel can accept at the moment, and when \fBchan gets\fR or \fBchan read\fR -requests more data than is currently available. When a channel blocks, the -thread can not do any other processing or service any other events. A channel -in non-blocking mode allows a thread to carry on with other work and get back -to the channel at the right time. +A channel is considered to be writable if at least one byte of data +can be written to the underlying file or device without blocking, or +if an error condition is present on the underlying file or device. +Note that client sockets opened in asynchronous mode become writable +when they become connected or if the connection fails. +.PP +Event-driven I/O works best for channels that have been placed into +non-blocking mode with the \fBchan configure\fR command. In blocking +mode, a \fBchan puts\fR command may block if you give it more data +than the underlying file or device can accept, and a \fBchan gets\fR +or \fBchan read\fR command will block if you attempt to read more data +than is ready; no events will be processed while the commands block. +In non-blocking mode \fBchan puts\fR, \fBchan read\fR, and \fBchan +gets\fR never block. +.PP +The script for a file event is executed at global level (outside the +context of any Tcl procedure) in the interpreter in which the \fBchan +event\fR command was invoked. If an error occurs while executing the +script then the command registered with \fBinterp bgerror\fR is used +to report the error. In addition, the file event handler is deleted +if it ever returns an error; this is done in order to prevent infinite +loops due to buggy handlers. .RE .\" METHOD: flush .TP -\fBchan flush \fIchannelName\fR +\fBchan flush \fIchannelId\fR . -For a channel in blocking mode, flushes all buffered output to the destination, -and then returns. For a channel in non-blocking mode, returns immediately -while all buffered output is flushed in the background as soon as possible. +Ensures that all pending output for the channel called \fIchannelId\fR +is written. +.RS +.PP +If the channel is in blocking mode the command does not return until +all the buffered output has been flushed to the channel. If the +channel is in non-blocking mode, the command may return before all +buffered output has been flushed; the remainder will be flushed in the +background as fast as the underlying file or device is able to absorb +it. +.RE .\" METHOD: gets .TP -\fBchan gets \fIchannelName\fR ?\fIvarName\fR? +\fBchan gets \fIchannelId\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 @@ -434,126 +531,142 @@ changing the encoding in use. See \fBENCODING ERROR EXAMPLES\fR later. .TP \fBchan names\fR ?\fIpattern\fR? . -Returns a list of all channel names, or if \fIpattern\fR is given, only those -names that match according to the rules of \fBstring match\fR. +Produces a list of all channel names. If \fIpattern\fR is specified, +only those channel names that match it (according to the rules of +\fBstring match\fR) will be returned. .\" METHOD: pending .TP -\fBchan pending \fImode channelName\fR +\fBchan pending \fImode channelId\fR . -Returns the number of bytes of input -when \fImode\fR is -.QW\fBinput\fR -, or output when \fImode\fR is -.QW\fBoutput\fR -, that are currently internally buffered for the channel. Useful in a readable -event callback to impose limits on input line length to avoid a potential -denial-of-service attack where an extremely long line exceeds the available -memory to buffer it. Returns -1 if the channel was not opened for the mode in -question. +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 +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). +Returns -1 if the channel was not opened for the mode in question. .\" METHOD: pipe .TP \fBchan pipe\fR . -Creates a pipe, i.e. a readable channel and a writable channel, and returns the -names of the readable channel and the writable channel. Data written to the -writable channel can be read from the readable channel. Because the pipe is a -real system-level pipe, it can be connected to other processes using -redirection. For example, to redirect \fBstderr\fR from a subprocess into one -channel, and \fBstdout\fR into another, \fBexec\fR with "2>@" and ">@", each -onto the writable side of a pipe, closing the writable side immediately -thereafter so that EOF is signaled on the read side once the subprocess has -closed its output, typically on exit. +Creates a standalone pipe whose read- and write-side channels are +returned as a 2-element list, the first element being the read side and +the second the write side. Can be useful e.g. to redirect +separately \fBstderr\fR and \fBstdout\fR from a subprocess. To do +this, spawn with "2>@" or +">@" redirection operators onto the write side of a pipe, and then +immediately close it in the parent. This is necessary to get an EOF on +the read side once the child has exited or otherwise closed its output. .RS .PP -Due to buffering, data written to one side of a pipe might not immediately -become available on the other side. Tcl's own buffers can be configured via -\fBchan configure -buffering\fR, but overall behaviour still depends on -operating system buffers outside of Tcl's control. Once the write side of the -channel is closed, any data remaining in the buffers is flushed through to the -read side. It may be useful to arrange for the connected process to flush at -some point after writing to the channel or to have it use some system-provided -mechanism to configure buffering. When two pipes are connected to the same -process, one to send data to the process, and one to read data from the -process, a deadlock may occur if the channels are in blocking mode: If -reading, the channel may block waiting for data that can never come because -buffers are only flushed on subsequent writes, and if writing, the channel may -block while waiting for the buffers to become free, which can never happen -because the reader can not read while the writer is blocking. To avoid this -issue, either put the channels into non-blocking mode and use event handlers, -or place the read channel and the write channel in separate interpreters in -separate threads. +Note that the pipe buffering semantics can vary at the operating system level +substantially; it is not safe to assume that a write performed on the output +side of the pipe will appear instantly to the input side. This is a +fundamental difference and Tcl cannot conceal it. The overall stream semantics +\fIare\fR compatible, so blocking reads and writes will not see most of the +differences, but the details of what exactly gets written when are not. This +is most likely to show up when using pipelines for testing; care should be +taken to ensure that deadlocks do not occur and that potential short reads are +allowed for. .RE .\" METHOD: pop .TP -\fBchan pop \fIchannelName\fR +\fBchan pop \fIchannelId\fR . -Removes the topmost transformation handler from the channel if there is one, -and closes the channel otherwise. The result is normally the empty string, but -may be an error in some situations, e.g. when closing the underlying resource -results in an error. +Removes the topmost transformation from the channel \fIchannelId\fR, if there +is any. If there are no transformations added to \fIchannelId\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 \fIchannelName eventSpec\fR +\fBchan postevent \fIchannelId eventSpec\fR . -For use by handlers established with \fBchan create\fR. Notifies Tcl that -that one or more event(s) listed in \fIeventSpec\fR, each of which is either -.QW\fBread\fR -or -.QW\fBwrite\fR. -, have occurred. +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 +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 +no events to post. .RS .PP -For use only by handlers for a channel created by \fBchan create\fR. It is an -error to post an event for any other channel. -.PP -Since only the handler for a reflected channel channel should post events it is -an error to post an event from any interpreter other than the interpreter that -created the channel. -.PP -It is an error to post an event that the channel has no interest in. See -\fBwatch\fR in the \fBrefchan\fR documentation for more information -.PP -\fBchan postevent\fR is available in safe interpreters, as any handler for a -reflected channel would have been created, and will be evaluated in that -interpreter as well. +Note that this subcommand can only be used with channel handles that +were created/opened by \fBchan create\fR. All other channels will +cause this subcommand to report an error. +.PP +As only the Tcl level of a channel, i.e. its command handler, should +post events to it we also restrict the usage of this command to the +interpreter that created the channel. In other words, posting events +to a reflected channel from an interpreter that does not contain it's +implementation is not allowed. Attempting to post an event from any +other interpreter will cause this subcommand to report an error. +.PP +Another restriction is that it is not possible to post events that the +I/O core has not registered an interest in. Trying to do so will cause +the method to throw an error. See the command handler method +\fBwatch\fR described in \fBrefchan\fR, the document specifying +the API of command handlers for reflected channels. +.PP +This command is \fBsafe\fR and made accessible to safe interpreters. +It can trigger the execution of \fBchan event\fR handlers, whether in the +current interpreter or in other interpreters or other threads, even +where the event is posted from a safe interpreter and listened for by +a trusted interpreter. \fBChan event\fR handlers are \fIalways\fR +executed in the interpreter that set them up. .RE .\" METHOD: push .TP -\fBchan push \fIchannelName cmdPrefix\fR +\fBchan push \fIchannelId cmdPrefix\fR . -Adds a new transformation handler on top of the channel and returns a handle -for the transformation. \fIcmdPrefix\fR is the first words of a command that -provides the interface documented for \fBtranschan\fR, and transforms data on -the channel, It is an error if handler does not support the mode(s) the channel -is in. +Adds a new transformation on top of the channel \fIchannelId\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. +The result of this subcommand is a handle to the transformation. Note that it +is important to make sure that the transformation is capable of supporting the +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? ?\fIchannelName\fR? \fIstring\fR +\fBchan puts\fR ?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR . -Writes \fIstring\fR and a line feed to the channel. If \fB\-nonewline\fR is -given, the trailing line feed is not written. The default channel is +Writes \fIstring\fR to the channel named \fIchannelId\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 +omitted, the string is written to the standard output channel, \fBstdout\fR. .RS .PP -Each line feed in the output is translated to the appropriate end of line -sequence as per the \fB\-translation\fR configuration setting of the channel. -.PP -Because Tcl internally buffers output, characters written to a channel may not -immediately be available at the destination. Tcl normally delays output until -the buffer is full or the channel is closed. \fBchan flush\fR forces output in -the direction of the destination. -.PP -When the output for a channel in blocking mode fills up, \fBchan puts\fR blocks -until space in the buffer is available again. On the other hand for a channel in -non-blocking mode, it returns immediately and the data is written in the -background as fast possible, constrained by the speed at which as the -destination accepts it. Output to a channel in non-blocking mode only works -properly when the application enters the event loop. When a channel is in -non-blocking mode, Tcl's internal buffers can hold an arbitrary amount of data, -possibly consuming a large amount of memory. To avoid wasting memory, channels -in non-blocking mode should normally be handled using \fBchan event\fR, where -the application only invokes \fBchan puts\fR after being notified through a file -event handler that the channel is ready for more output data. +Newline characters in the output are translated by \fBchan puts\fR to +platform-specific end-of-line sequences according to the currently +configured value of the \fB\-translation\fR option for the channel +(for example, on PCs newlines are normally replaced with +carriage-return-linefeed sequences; see \fBchan configure\fR above for +details). +.PP +Tcl buffers output internally, so characters written with \fBchan +puts\fR may not appear immediately on the output file or device; Tcl +will normally delay output until the buffer is full or the channel is +closed. You can force output to appear immediately with the \fBchan +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 +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 +underlying file or device can accept it. The application must use the +Tcl event loop for non-blocking output to work; otherwise Tcl never +finds out that the file or device is ready for more output data. It +is possible for an arbitrarily large amount of data to be buffered for +a channel in non-blocking mode, which could consume a large amount of +memory. To avoid wasting memory, non-blocking I/O should normally be +used in an event-driven fashion with the \fBchan event\fR command +(do not invoke \fBchan puts\fR unless you have recently been notified +via a file event that the channel is ready for more output data). .PP The command will raise an error exception with POSIX error code \fBEILSEQ\fR if the encoding profile \fBstrict\fR is in effect for the channel and the output @@ -562,34 +675,58 @@ may be partially written to the channel in this case. .RE .\" METHOD: read .TP -\fBchan read \fIchannelName\fR ?\fInumChars\fR? +\fBchan read \fIchannelId\fR ?\fInumChars\fR? .TP -\fBchan read \fR?\fB\-nonewline\fR? \fIchannelName\fR +\fBchan read \fR?\fB\-nonewline\fR? \fIchannelId\fR . -Reads and returns the next \fInumChars\fR characters from the channel. If -\fInumChars\fR is omitted, all available characters up to the end of the file -are read, or if the channel is in non-blocking mode, all currently-available -characters are read. If there is an error on the channel, reading ceases and -an error is returned. If \fInumChars\fR is not given, \fB\-nonewline\fR -may be given, causing any trailing line feed to be trimmed. +In the first form, the result will be the next \fInumChars\fR +characters read from the channel named \fIchannelId\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 +\fInumChars\fR has been omitted) the flag \fB\-nonewline\fR may be +given to indicate that any trailing newline in the string that has +been read should be trimmed. .RS .PP -If the channel is in non-blocking mode, fewer characters than requested may be -returned. If the channel is configured to use a multi-byte encoding, bytes -that do not form a complete character are retained in the buffers until enough -bytes to complete the character accumulate, or the end of the data is reached. -\fB\-nonewline\fR is ignored if characters are returned before reaching the end -of the file. +If \fIchannelId\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 +multi-byte encoding, then there may actually be some bytes remaining +in the internal buffers that do not form a complete character. These +bytes will not be returned until a complete character is available or +end-of-file is reached. The \fB\-nonewline\fR switch is ignored if +the command returns before reaching the end of the file. +.PP +\fBChan read\fR translates end-of-line sequences in the input into +newline characters according to the \fB\-translation\fR option for the +channel (see \fBchan configure\fR above for a discussion on the ways +in which \fBchan configure\fR will alter input). .PP -Each end-of-line sequence according to the value of \fB\-translation\fR is -translated into a line feed. +When reading from a serial port, most applications should configure +the serial port channel to be non-blocking, like this: .PP -When reading from a serial port, most applications should configure the serial -port channel to be in non-blocking mode, but not necessarily use an event -handler since most serial ports are comparatively slow. It is entirely -possible to get a \fBreadable\fR event for each individual character. In -blocking mode, \fBchan read\fR blocks forever when reading to the end of the -data if there is no \fBchan configure -eofchar\fR configured for the channel. +.CS +\fBchan configure \fIchannelId \fB\-blocking \fI0\fR. +.CE +.PP +Then \fBchan read\fR behaves much like described above. Note that +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 +. +In this form \fBchan read\fR blocks until \fInumChars\fR have been +received from the serial port. +.TP +\fBchan read \fIchannelId\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 +end-of-file character has been configured for the channel, then +\fBchan read\fR will block forever. .PP If the encoding profile \fBstrict\fR is in effect for the channel, the command will raise an exception with the POSIX error code \fBEILSEQ\fR if any encoding @@ -608,41 +745,56 @@ changing the encoding in use. See \fBENCODING ERROR EXAMPLES\fR later. .RE .\" METHOD: seek .TP -\fBchan seek \fIchannelName offset\fR ?\fIorigin\fR? +\fBchan seek \fIchannelId offset\fR ?\fIorigin\fR? . -Sets the current position for the data in the channel to integer \fIoffset\fR -bytes relative to \fIorigin\fR. A negative offset moves the current position -backwards from the origin. \fIorigin\fR is one of the -following: +Sets the current access position within the underlying data stream for +the channel named \fIchannelId\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 .IP \fBstart\fR -The origin is the start of the data. This is the default. +The new access position will be \fIoffset\fR bytes from the start +of the underlying file or device. .IP \fBcurrent\fR -The origin is the current position. +The new access position will be \fIoffset\fR bytes from the current +access position; a negative \fIoffset\fR moves the access position +backwards in the underlying file or device. .IP \fBend\fR -The origin is the end of the data. -.PP -\fBChan seek\fR flushes all buffered output even if the channel is in -non-blocking mode, discards any buffered and unread input, and returns the -empty string or an error if the channel does not support seeking. -.PP -\fIoffset\fR values are byte offsets, not character offsets. Unlike \fBchan -read\fR, both \fBchan seek\fR and \fBchan tell\fR operate in terms of bytes, -not characters, +The new access position will be \fIoffset\fR bytes from the end of the +file or device. A negative \fIoffset\fR places the access position +before the end of file, and a positive \fIoffset\fR places the access +position after the end of file. +.PP +The \fIorigin\fR argument defaults to \fBstart\fR. +.PP +\fBChan seek\fR flushes all buffered output for the channel before the +command returns, even if the channel is in non-blocking mode. It also +discards any buffered and unread input. This command returns an empty +string. An error occurs if this command is applied to channels whose +underlying file or device does not support seeking. +.PP +Note that \fIoffset\fR values are byte offsets, not character offsets. +Both \fBchan seek\fR and \fBchan tell\fR operate in terms of bytes, +not characters, unlike \fBchan read\fR. .RE .\" METHOD: tell .TP -\fBchan tell \fIchannelName\fR +\fBchan tell \fIchannelId\fR . -Returns the offset in bytes of the current position in the underlying data, or --1 if the channel does not support seeking. The value can be passed to \fBchan -seek\fR to set current position to that offset. +Returns a number giving the current access position within the +underlying data stream for the channel named \fIchannelId\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 \fIchannelName\fR ?\fIlength\fR? +\fBchan truncate \fIchannelId\fR ?\fIlength\fR? . -Flushes the channel and truncates the data in the channel to \fIlength\fR -bytes, or to the current position in bytes if \fIlength\fR is omitted. +Sets the byte length of the underlying data stream for the channel +named \fIchannelId\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. . .SH EXAMPLES .SS "SIMPLE CHANNEL OPERATION EXAMPLES" @@ -753,7 +905,7 @@ preventing servicing of other connections at the same time: .PP .CS # This is a very simple logger... -proc log message { +proc log {message} { \fBchan puts\fR stdout $message } @@ -876,7 +1028,7 @@ full line. .CS % set f [open test_A_195_B.txt r] file384b6a8 -% chan configure $f -encoding utf-8 -profile strict +% chan configure $f -encoding utf-8 % catch {chan gets $f} e d 1 % set d @@ -886,7 +1038,7 @@ file384b6a8 -errorinfo {...} -errorline 1 % chan tell $f 0 -% chan configure $f -encoding binary -profile strict +% chan configure $f -encoding binary % chan gets $f AÃB .CE @@ -900,7 +1052,7 @@ position 1. The data at the error position is thus recovered by the next .CS % set f [open test_A_195_B.txt r] file35a65a0 -% chan configure $f -encoding utf-8 -profile strict -blocking 1 +% chan configure $f -encoding utf-8 -blocking 1 % catch {chan read $f} e d 1 % set d @@ -910,7 +1062,7 @@ file35a65a0 -errorinfo {...} -errorline 1 % chan tell $f 1 -% chan configure $f -encoding binary -profile strict +% chan configure $f -encoding binary % chan read $f ÃB % chan close $f @@ -921,7 +1073,7 @@ Finally the same example, but this time with a non-blocking channel. .CS % set f [open test_A_195_B.txt r] file35a65a0 -% chan configure $f -encoding utf-8 -profile strict -blocking 0 +% chan configure $f -encoding utf-8 -blocking 0 % chan read $f A % chan tell $f diff --git a/doc/configurable.n b/doc/configurable.n index 7ab5b92..d2e6b18 100644 --- a/doc/configurable.n +++ b/doc/configurable.n @@ -1,5 +1,5 @@ '\" -'\" Copyright © 2019 Donal K. Fellows +'\" Copyright (c) 2019 Donal K. Fellows '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. diff --git a/doc/encoding.n b/doc/encoding.n index d556839..c28406f 100644 --- a/doc/encoding.n +++ b/doc/encoding.n @@ -1,6 +1,5 @@ '\" '\" Copyright (c) 1998 Scriptics Corporation. -'\" Copyright (c) 2023 Nathan Coulter '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. @@ -9,86 +8,84 @@ .so man.macros .BS .SH NAME -encoding \- Work with encodings +encoding \- Manipulate encodings .SH SYNOPSIS -\fBencoding \fIoperation\fR ?\fIarg arg ...\fR? +\fBencoding \fIoption\fR ?\fIarg arg ...\fR? .BE .SH INTRODUCTION .PP -In Tcl every string is composed of Unicode values. Text may be encoded into an -encoding such as cp1252, iso8859-1, Shift\-JIS, utf-8, utf-16, etc. Not every -Unicode value is encodable in every encoding, and some encodings can encode -values that are not available in Unicode. -.PP -Even though Unicode is for encoding the written texts of human languages, any -sequence of bytes can be encoded as the first 255 Unicode values. In particular, -iso8859-1 is an encoding (a superset of classic ASCII) for a subset of Unicode -in which each byte is a Unicode value of 255 -or less; any sequence of bytes can be considered to be a Unicode string -encoded in iso8859-1. To work with binary data in Tcl, decode it from -iso8859-1 when reading it in, and encode it into iso8859-1 when writing it out, -ensuring that each character in the string has a value of 255 or less. -Decoding such a string does nothing, and encoding encoding such a string also -does nothing. -.PP -For example, the following is true: -.CS - -set text {In Tcl binary data is treated as Unicode text and it just works.} -set encoded [\fBencoding convertto\fR iso8859-1 $text] -expr {$text eq $encoded}; #-> 1 -.CE -The following is also true: -.CS -set decoded [\fBencoding convertfrom\fR iso8859-1 $text] -expr {$text eq $decoded}; #-> 1 -.CE +Strings in Tcl are logically a sequence of Unicode characters. +These strings are represented in memory as a sequence of bytes that +may be in one of several encodings: modified UTF\-8 (which uses 1 to 4 +bytes per character), or a custom encoding start as 8 bit binary data. +.PP +Different operating system interfaces or applications may generate +strings in other encodings such as Shift\-JIS. The \fBencoding\fR +command helps to bridge the gap between Unicode and these other +formats. .SH DESCRIPTION .PP -Performs one of the following encoding \fIoperations\fR: +Performs one of several encoding related operations, depending on +\fIoption\fR. The legal \fIoption\fRs are: .\" METHOD: convertfrom .TP \fBencoding convertfrom\fR ?\fIencoding\fR? \fIdata\fR +.VS "TCL8.7 TIP607, TIP656" .TP -\fBencoding convertfrom\fR ?\fB\-profile \fIprofile\fR? ?\fB\-failindex var\fR? \fIencoding data\fR +\fBencoding convertfrom\fR ?\fB-profile \fIprofile\fR? ?\fB-failindex var\fR? \fIencoding data\fR +.VE "TCL8.7 TIP607, TIP656" . -Decodes \fIdata\fR encoded in \fIencoding\fR. If \fIencoding\fR is not -specified the current system encoding is used. +Converts \fIdata\fR, which should be in binary string encoded as per +\fIencoding\fR, to a Tcl string. If \fIencoding\fR is not specified, the current +system encoding is used. +.PP .VS "TCL8.7 TIP607, TIP656" -\fB\-profile\fR determines how invalid data for the encoding are handled. See -the \fBPROFILES\fR section below for details. Returns an error if decoding -fails. However, if \fB\-failindex\fR given, returns the result of the -conversion up to the point of termination, and stores in \fBvar\fR the index of -the character that could not be converted. If no errors are encountered the -entire result of the conversion is returned and the value \fB-1\fR is stored in -\fBvar\fR. +The \fB-profile\fR option determines the command behavior in the presence +of conversion errors. See the \fBPROFILES\fR section below for details. Any premature +termination of processing due to errors is reported through an exception if +the \fB-failindex\fR option is not specified. +.PP +If the \fB-failindex\fR is specified, instead of an exception being raised +on premature termination, the result of the conversion up to the point of the +error is returned as the result of the command. In addition, the index +of the source byte triggering the error is stored in \fBvar\fR. If no +errors are encountered, the entire result of the conversion is returned and +the value \fB-1\fR is stored in \fBvar\fR. .VE "TCL8.7 TIP607, TIP656" .\" METHOD: convertto .TP \fBencoding convertto\fR ?\fIencoding\fR? \fIdata\fR .TP -\fBencoding convertto\fR ?\fB\-profile \fIprofile\fR? ?\fB\-failindex var\fR? \fIencoding data\fR +\fBencoding convertto\fR ?\fB-profile \fIprofile\fR? ?\fB-failindex var\fR? \fIencoding data\fR . -Converts \fIstring\fR to \fIencoding\fR. If \fIencoding\fR is not given, the -current system encoding is used. +Convert \fIstring\fR to the specified \fIencoding\fR. The result is a Tcl binary +string that contains the sequence of bytes representing the converted string in +the specified encoding. If \fIencoding\fR is not specified, the current system +encoding is used. +.PP .VS "TCL8.7 TIP607, TIP656" -See \fBencoding convertfrom\fR for the meaning of \fB\-profile\fR and -\fB\-failindex\fR. +The \fB-profile\fR and \fB-failindex\fR options have the same effect as +described for the \fBencoding convertfrom\fR command. .VE "TCL8.7 TIP607, TIP656" .\" METHOD: dirs .TP \fBencoding dirs\fR ?\fIdirectoryList\fR? . -Sets the search path for \fB*.enc\fR encoding data files to the list of -directories given by \fIdirectoryList\fR. If \fIdirectoryList\fR is not given, -returns the current list of directories that make up the search path. It is -not an error for an item in \fIdirectoryList\fR to not refer to a readable, -searchable directory. +Tcl can load encoding data files from the file system that describe +additional encodings for it to work with. This command sets the search +path for \fB*.enc\fR encoding data files to the list of directories +\fIdirectoryList\fR. If \fIdirectoryList\fR is omitted then the +command returns the current list of directories that make up the +search path. It is an error for \fIdirectoryList\fR to not be a valid +list. If, when a search for an encoding data file is happening, an +element in \fIdirectoryList\fR does not refer to a readable, +searchable directory, that element is ignored. .\" METHOD: names .TP \fBencoding names\fR . -Returns a list of the names of available encodings. +Returns a list containing the names of all of the encodings that are +currently available. The encodings .QW utf-8 and @@ -98,66 +95,89 @@ are guaranteed to be present in the list. .TP \fBencoding profiles\fR .VS "TCL8.7 TIP656" -Returns a list of names of available encoding profiles. See \fBPROFILES\fR -below. +Returns a list of the names of encoding profiles. See \fBPROFILES\fR below. .VE "TCL8.7 TIP656" .\" METHOD: system .TP \fBencoding system\fR ?\fIencoding\fR? . -Sets the system encoding to \fIencoding\fR. If \fIencoding\fR is not given, -returns the current system encoding. The system encoding is used to pass -strings to system calls. +Set the system encoding to \fIencoding\fR. If \fIencoding\fR is +omitted then the command returns the current system encoding. The +system encoding is used whenever Tcl passes strings to system calls. .\" Do not put .VS on whole section as that messes up the bullet list alignment .SH PROFILES .PP .VS "TCL8.7 TIP656" -Each \fIprofile\fR is a distinct strategy for dealing with invalid data for an -encoding. -.PP -The following profiles are currently implemented. +Operations involving encoding transforms may encounter several types of +errors such as invalid sequences in the source data, characters that +cannot be encoded in the target encoding and so on. +A \fIprofile\fR prescribes the strategy for dealing with such errors +in one of two ways: .VE "TCL8.7 TIP656" -.TP -\fBstrict\fR +. +.IP \(bu .VS "TCL8.7 TIP656" -The default profile. The operation fails when invalid data for the encoding -are encountered. +Terminating further processing of the source data. The profile does not +determine how this premature termination is conveyed to the caller. By default, +this is signalled by raising an exception. If the \fB-failindex\fR option +is specified, errors are reported through that mechanism. .VE "TCL8.7 TIP656" -.TP -\fBtcl8\fR +.IP \(bu .VS "TCL8.7 TIP656" -Provides for behaviour identical to that of Tcl 8.6: When -decoding, for encodings \fBother than utf-8\fR, each invalid byte is interpreted -as the Unicode value given by that one byte. For example, the byte 0x80, which -is invalid in the ASCII encoding would be mapped to the Unicode value U+0080. -For \fButf-8\fR, each invalid byte that is a valid CP1252 character is -interpreted as the Unicode value for that character, while each byte that is -not is treated as the Unicode value given by that one byte. For example, byte -0x80 is defined by CP1252 and is therefore mapped to its Unicode equivalent -U+20AC while byte 0x81 which is not defined by CP1252 is mapped to U+0081. As -an additional special case, the sequence 0xC0 0x80 is mapped to U+0000. -.RS -.PP -When encoding, each character that cannot be represented in the encoding is -replaced by an encoding-dependent character, usually the question mark \fB?\fR. -.RE +Continue further processing of the source data using a fallback strategy such +as replacing or discarding the offending bytes in a profile-defined manner. .VE "TCL8.7 TIP656" +.PP +The following profiles are currently implemented with \fBstrict\fR being +the default if the \fB-profile\fR is not specified. +.VS "TCL8.7 TIP656" +.TP +\fBstrict\fR +. +The \fBstrict\fR profile always stops processing when an conversion error is +encountered. The error is signalled via an exception or the \fB-failindex\fR +option mechanism. The \fBstrict\fR profile implements a Unicode standard +conformant behavior. +.TP +\fBtcl8\fR +. +The \fBtcl8\fR profile always follows the first strategy above and corresponds +to the behavior of encoding transforms in Tcl 8.6. When converting from an +external encoding \fBother than utf-8\fR to Tcl strings with the \fBencoding +convertfrom\fR command, invalid bytes are mapped to their numerically equivalent +code points. For example, the byte 0x80 which is invalid in ASCII would be +mapped to code point U+0080. When converting from \fButf-8\fR, invalid bytes +that are defined in CP1252 are mapped to their Unicode equivalents while those +that are not fall back to the numerical equivalents. For example, byte 0x80 is +defined by CP1252 and is therefore mapped to its Unicode equivalent U+20AC while +byte 0x81 which is not defined by CP1252 is mapped to U+0081. As an additional +special case, the sequence 0xC0 0x80 is mapped to U+0000. + +When converting from Tcl strings to an external encoding format using +\fBencoding convertto\fR, characters that cannot be represented in the +target encoding are replaced by an encoding-dependent character, usually +the question mark \fB?\fR. .TP \fBreplace\fR -.VS "TCL8.7 TIP 656" -When decoding, invalid bytes are replaced by U+FFFD, the Unicode REPLACEMENT -CHARACTER. -.RS -.PP -When encoding, Unicode values that cannot be represented in the target encoding -are transformed to an encoding-specific fallback character, U+FFFD REPLACEMENT -CHARACTER for UTF targets, and generally `?` for other encodings. -.RE +. +Like the \fBtcl8\fR profile, the \fBreplace\fR profile always continues +processing on conversion errors but follows a Unicode standard conformant +method for substitution of invalid source data. + +When converting an encoded byte sequence to a Tcl string using +\fBencoding convertfrom\fR, invalid bytes +are replaced by the U+FFFD REPLACEMENT CHARACTER code point. + +When encoding a Tcl string with \fBencoding convertto\fR, +code points that cannot be represented in the +target encoding are transformed to an encoding-specific fallback character, +U+FFFD REPLACEMENT CHARACTER for UTF targets and generally `?` for other +encodings. .VE "TCL8.7 TIP656" .SH EXAMPLES .PP -These examples use the utility proc below that prints the Unicode value for -each character in a string. +These examples use the utility proc below that prints the Unicode code points +comprising a Tcl string. .PP .CS proc codepoints s {join [lmap c [split $s {}] { @@ -165,14 +185,14 @@ proc codepoints s {join [lmap c [split $s {}] { } .CE .PP -Example 1: Convert from euc-jp: +Example 1: convert a byte sequence in Japanese euc-jp encoding to a TCL string: .PP .CS -% codepoints [\fBencoding convertfrom\fR euc-jp \exA4\exCF] +% codepoints [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"] U+00306F .CE .PP -The result is the Unicode value +The result is the unicode codepoint .QW "\eu306F" , which is the Hiragana letter HA. .VS "TCL8.7 TIP607, TIP656" @@ -194,7 +214,7 @@ unexpected byte sequence starting at index 1: '\ex80' Example 3: Get partial data and the error location: .PP .CS -% codepoints [\fBencoding convertfrom\fR -failindex idx ascii AB\ex80] +% codepoints [\fBencoding convertfrom\fR -profile strict -failindex idx ascii AB\ex80] U+000041 U+000042 % set idx 2 @@ -207,7 +227,7 @@ Example 4: Encode a character that is not representable in ISO8859-1: A? % \fBencoding convertto\fR -profile strict iso8859-1 A\eu0141 unexpected character at index 1: 'U+000141' -% \fBencoding convertto\fR -failindex idx iso8859-1 A\eu0141 +% \fBencoding convertto\fR -profile strict -failindex idx iso8859-1 A\eu0141 A % set idx 1 @@ -333,14 +333,6 @@ See the \fBmathfunc\fR(n) documentation for the math functions that are available by default. .SS "TYPES, OVERFLOW, AND PRECISION" .PP -When needed to guarantee exact performance, internal computations involving -integers use the LibTomMath multiple precision integer library. In Tcl releases -prior to 8.5, integer calculations were performed using one of the C types -\fIlong int\fR or \fITcl_WideInt\fR, causing implicit range truncation -in those calculations where values overflowed the range of those types. -Any code that relied on these implicit truncations should instead call -\fBwide()\fR, which does truncate. -.PP Internal floating-point computations are performed using the \fIdouble\fR C type. When converting a string to floating-point value, exponent overflow is @@ -259,7 +259,7 @@ The default is \fButf-8\fR, as specified by RFC 2718. The value of the User-Agent header in the HTTP request. In an unsafe interpreter, the default value depends upon the operating system, and the version numbers of \fBhttp\fR and \fBTcl\fR, and is (for example) -.QW "\fBMozilla/5.0 (Windows; U; Windows NT 10.0) http/2.9.0 Tcl/8.6.9\fR" . +.QW "\fBMozilla/5.0 (Windows; U; Windows NT 10.0) http/2.10.0 Tcl/9.0.0\fR" . A safe interpreter cannot determine its operating system, and so the default in a safe interpreter is to use a Windows 10 value with the current version numbers of \fBhttp\fR and \fBTcl\fR. @@ -511,32 +511,32 @@ own value is also specified: .PP .CS safe::interpCreate foo -accessPath { - /usr/local/TclHome/lib/tcl8.6 - /usr/local/TclHome/lib/tcl8.6/http1.0 - /usr/local/TclHome/lib/tcl8.6/opt0.4 - /usr/local/TclHome/lib/tcl8.6/msgs - /usr/local/TclHome/lib/tcl8.6/encoding + /usr/local/TclHome/lib/tcl9.0 + /usr/local/TclHome/lib/tcl9.0/http1.0 + /usr/local/TclHome/lib/tcl9.0/opt0.4 + /usr/local/TclHome/lib/tcl9.0/msgs + /usr/local/TclHome/lib/tcl9.0/encoding /usr/local/TclHome/lib } # The child's ::auto_path must be given a suitable value: safe::interpConfigure foo -autoPath { - /usr/local/TclHome/lib/tcl8.6 + /usr/local/TclHome/lib/tcl9.0 /usr/local/TclHome/lib } # The two commands can be combined: safe::interpCreate foo -accessPath { - /usr/local/TclHome/lib/tcl8.6 - /usr/local/TclHome/lib/tcl8.6/http1.0 - /usr/local/TclHome/lib/tcl8.6/opt0.4 - /usr/local/TclHome/lib/tcl8.6/msgs - /usr/local/TclHome/lib/tcl8.6/encoding + /usr/local/TclHome/lib/tcl9.0 + /usr/local/TclHome/lib/tcl9.0/http1.0 + /usr/local/TclHome/lib/tcl9.0/opt0.4 + /usr/local/TclHome/lib/tcl9.0/msgs + /usr/local/TclHome/lib/tcl9.0/encoding /usr/local/TclHome/lib } -autoPath { - /usr/local/TclHome/lib/tcl8.6 + /usr/local/TclHome/lib/tcl9.0 /usr/local/TclHome/lib } .CE @@ -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 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 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: diff --git a/doc/socket.n b/doc/socket.n index 06d3b5b..623fac6 100644 --- a/doc/socket.n +++ b/doc/socket.n @@ -261,8 +261,6 @@ close $sockChan puts "The time on $server is $line1" puts "That is [lindex $line2 0]s since the server started" .CE -.SH "HISTORY" -Support for IPv6 was added in Tcl 8.6. .SH "SEE ALSO" chan(n), flush(n), open(n), read(n) .SH KEYWORDS diff --git a/doc/transchan.n b/doc/transchan.n index a511c75..abae7b9 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 \fIchannelName cmdPrefix\fR +\fBchan push \fIchannelId cmdPrefix\fR \fIcmdPrefix \fBclear \fIhandle\fR \fIcmdPrefix \fBdrain \fIhandle\fR |