Merge trunk. Also update Tcl_ObjType.version to match TIP 644

11 files changed, 175 insertions, 85 deletions

diff --git a/doc/BoolObj.3 b/doc/BoolObj.3
index 47a2189..71580af 100644
--- a/doc/BoolObj.3
+++ b/doc/BoolObj.3
@@ -20,7 +20,7 @@ Tcl_Obj *
 \fBTcl_SetBooleanObj\fR(\fIobjPtr, intValue\fR)
 .sp
 int
-\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, intPtr\fR)
+\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR)
 .sp
 int
 \fBTcl_GetBoolFromObj\fR(\fIinterp, objPtr, flags. charPtr\fR)
@@ -35,7 +35,7 @@ retrieve a boolean value.
 If a boolean value cannot be retrieved,
 an error message is left in the interpreter's result value
 unless \fIinterp\fR is NULL.
-.AP int *intPtr out
+.AP "bool \&| int" *boolPtr out
 Points to place where \fBTcl_GetBooleanFromObj\fR
 stores the boolean value (0 or 1) obtained from \fIobjPtr\fR.
 .AP char *charPtr out
@@ -71,13 +71,13 @@ any former value stored in \fI*objPtr\fR.
 from the value stored in \fI*objPtr\fR.
 If \fIobjPtr\fR holds a string value recognized by \fBTcl_GetBoolean\fR,
 then the recognized boolean value is written at the address given
-by \fIintPtr\fR.
+by \fIboolPtr\fR.
 If \fIobjPtr\fR holds any value recognized as
 a number by Tcl, then if that value is zero a 0 is written at
-the address given by \fIintPtr\fR and if that
-value is non-zero a 1 is written at the address given by \fIintPtr\fR.
+the address given by \fIboolPtr\fR and if that
+value is non-zero a 1 is written at the address given by \fIboolPtr\fR.
 In all cases where a value is written at the address given
-by \fIintPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR.
+by \fIboolPtr\fR, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR.
 If the value of \fIobjPtr\fR does not meet any of the conditions
 above, then \fBTCL_ERROR\fR is returned and an error message is
 left in the interpreter's result unless \fIinterp\fR is NULL.
diff --git a/doc/CrtObjCmd.3 b/doc/CrtObjCmd.3
index 012c46c..ffd9e27 100644
--- a/doc/CrtObjCmd.3
+++ b/doc/CrtObjCmd.3
@@ -224,7 +224,7 @@ pointed to by \fIinfoPtr\fR and returns 1.
 A \fBTcl_CmdInfo\fR structure has the following fields:
 .PP
 .CS
-typedef struct Tcl_CmdInfo {
+typedef struct {
     int \fIisNativeObjectProc\fR;
     Tcl_ObjCmdProc *\fIobjProc\fR;
     void *\fIobjClientData\fR;
diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3
index 6833fc5..e4d1a43 100644
--- a/doc/CrtTrace.3
+++ b/doc/CrtTrace.3
@@ -29,7 +29,7 @@ Tcl_Trace
 .AS Tcl_CmdObjTraceDeleteProc *deleteProc
 .AP Tcl_Interp *interp in
 Interpreter containing command to be traced or untraced.
-.AP int level in
+.AP size_t level in
 Only commands at or below this nesting level will be traced unless
 0 is specified.  1 means
 top-level commands only, 2 means top-level commands or those that are
@@ -81,6 +81,20 @@ typedef int \fBTcl_CmdObjTraceProc\fR(
         \fBTcl_Obj\fR *const \fIobjv\fR[]);
 .CE
 .PP
+\fIobjProc2\fR should have arguments and result that match the type,
+\fBTcl_CmdObjTraceProc2\fR:
+.PP
+.CS
+typedef int \fBTcl_CmdObjTraceProc2\fR(
+        \fBvoid *\fR \fIclientData\fR,
+        \fBTcl_Interp\fR* \fIinterp\fR,
+        size_t \fIlevel\fR,
+        const char *\fIcommand\fR,
+        \fBTcl_Command\fR \fIcommandToken\fR,
+        size_t \fIobjc\fR,
+        \fBTcl_Obj\fR *const \fIobjv\fR[]);
+.CE
+.PP
 The \fIclientData\fR and \fIinterp\fR parameters are copies of the
 corresponding arguments given to \fBTcl_CreateTrace\fR.
 \fIclientData\fR typically points to an application-specific data
diff --git a/doc/Encoding.3 b/doc/Encoding.3
index f37452d..974e70e 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -46,6 +46,9 @@ const char *
 \fBTcl_GetEncodingName\fR(\fIencoding\fR)
 .sp
 int
+\fBTcl_GetEncodingNulLength\fR(\fIencoding\fR)
+.sp
+int
 \fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR)
 .sp
 const char *
@@ -270,6 +273,9 @@ was used to create the encoding.  The string returned by
 \fBTcl_GetEncodingName\fR is only guaranteed to persist until the
 \fIencoding\fR is deleted.  The caller must not modify this string.
 .PP
+\fBTcl_GetEncodingNulLength\fR returns the length of the terminating
+nul byte sequence for strings in the specified encoding.
+.PP
 \fBTcl_SetSystemEncoding\fR sets the default encoding that should be used
 whenever the user passes a NULL value for the \fIencoding\fR argument to
 any of the other encoding functions.  If \fIname\fR is NULL, the system
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 239ff0f..469af22 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -850,7 +850,7 @@ The \fBTcl_Filesystem\fR structure contains the following fields:
 .CS
 typedef struct Tcl_Filesystem {
     const char *\fItypeName\fR;
-    int \fIstructureLength\fR;
+    size_t \fIstructureLength\fR;
     Tcl_FSVersion \fIversion\fR;
     Tcl_FSPathInFilesystemProc *\fIpathInFilesystemProc\fR;
     Tcl_FSDupInternalRepProc *\fIdupInternalRepProc\fR;
diff --git a/doc/OpenTcp.3 b/doc/OpenTcp.3
index fbaa04f..5a0f559 100644
--- a/doc/OpenTcp.3
+++ b/doc/OpenTcp.3
@@ -24,7 +24,7 @@ Tcl_Channel
 \fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR)
 .sp
 Tcl_Channel
-\fBTcl_OpenTcpServerEx\fR(\fIinterp, service, myaddr, flags, proc, clientData\fR)
+\fBTcl_OpenTcpServerEx\fR(\fIinterp, service, myaddr, flags, backlog, proc, clientData\fR)
 .sp
 .SH ARGUMENTS
 .AS Tcl_TcpAcceptProc clientData
@@ -47,6 +47,8 @@ for the local end of the connection.  If NULL, a default interface is
 chosen.
 .AP int async in
 If nonzero, the client socket is connected asynchronously to the server.
+.AP int backlog in
+Length of OS listen backlog queue. Use -1 for default value.
 .AP "unsigned int" flags in
 ORed combination of \fBTCL_TCPSERVER\fR flags that specify additional
 informations about the socket being created.
diff --git a/doc/chan.n b/doc/chan.n
index 9589f98..584f0c5 100644
--- a/doc/chan.n
+++ b/doc/chan.n
@@ -143,19 +143,12 @@ interface with the operating system,
 .RE
 .TP
 \fB\-eofchar\fR \fIchar\fR
-.TP
-\fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR
 .
 \fIchar\fR signals the end of the data when it is encountered in the input.
-For output, the character is added when the channel is closed.  If \fIchar\fR
-is the empty string, there is no special character that marks the end of the
-data.  For read-write channels, one end-of-file character for input and another
-for output may be given.  When only one end-of-file character is given it is
-applied to both input and output.  For a read-write channel two values are
-returned even if they are are identical.
+If \fIchar\fR is the empty string, there is no special character that marks
+the end of the data.
 
-The default value is the empty string, except that under Windows the default
-value for reading is Control-z (\ex1A).  The acceptable range is \ex01 -
+The default value is the empty string.  The acceptable range is \ex01 -
 \ex7f.  A value outside this range results in an error.
 .TP
 \fB\-translation\fR \fItranslation\fR
diff --git a/doc/encoding.n b/doc/encoding.n
index c1dbf27..4e18798 100644
--- a/doc/encoding.n
+++ b/doc/encoding.n
@@ -28,30 +28,37 @@ formats.
 Performs one of several encoding related operations, depending on
 \fIoption\fR.  The legal \fIoption\fRs are:
 .TP
-\fBencoding convertfrom\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR?
-?\fIencoding\fR? \fIdata\fR
+\fBencoding convertfrom\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR? ?\fB-strict\fR? ?\fIencoding\fR? \fIdata\fR
 .
 Convert \fIdata\fR to a Unicode string from the specified \fIencoding\fR.  The
 characters in \fIdata\fR are 8 bit binary data.  The resulting
 sequence of bytes is a string created by applying the given \fIencoding\fR
 to the data. If \fIencoding\fR is not specified, the current
 system encoding is used.
-.
-The call fails on convertion errors, like an incomplete utf-8 sequence.
-The option \fB-failindex\fR is followed by a variable name. The variable
-is set to \fI-1\fR if no conversion error occured. It is set to the
-first error location in \fIdata\fR in case of a conversion error. All data
-until this error location is transformed and retured. This option may not
-be used together with \fB-nocomplain\fR.
-.
-The call does not fail on conversion errors, if the option
-\fB-nocomplain\fR is given. In this case, any error locations are replaced
-by \fB?\fR. Incomplete sequences are written verbatim to the output string.
-The purpose of this switch is to gain compatibility to prior versions of TCL.
-It is not recommended for any other usage.
+.VS "TCL8.7 TIP346, TIP607, TIP601"
+.PP
+.RS
+If the option \fB-nocomplain\fR is given, the command does not fail on
+encoding errors.  Instead, any not convertable bytes (like incomplete UTF-8
+ sequences, see example below) are put as byte values into the output stream.
+If the option \fB-nocomplain\fR is not given, the command will fail with an
+appropriate error message.
+.PP
+If the option \fB-failindex\fR with a variable name is given, the error reporting
+is changed in the following manner:
+in case of a conversion error, the position of the input byte causing the error
+is returned in the given variable.  The return value of the command are the
+converted characters until the first error position. No error condition is raised.
+In case of no error, the value \fI-1\fR is written to the variable.  This option
+may not be used together with \fB-nocomplain\fR.
+.PP
+The \fB-strict\fR option followes more strict rules in conversion.  Currently, only
+the sequence \fB\\xC0\\x80\fR in \fButf-8\fR encoding is disallowed.  Additional rules
+may follow.
+.VE "TCL8.7 TIP346, TIP607, TIP601"
+.RE
 .TP
-\fBencoding convertto\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR?
-?\fIencoding\fR? \fIstring\fR
+\fBencoding convertto\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR? ?\fB-strict\fR? ?\fIencoding\fR? \fIstring\fR
 .
 Convert \fIstring\fR from Unicode to the specified \fIencoding\fR.
 The result is a sequence of bytes that represents the converted
@@ -59,21 +66,28 @@ string.  Each byte is stored in the lower 8-bits of a Unicode
 character (indeed, the resulting string is a binary string as far as
 Tcl is concerned, at least initially).  If \fIencoding\fR is not
 specified, the current system encoding is used.
-.
-The call fails on convertion errors, like a Unicode character not representable
-in the given \fIencoding\fR.
-.
-The option \fB-failindex\fR is followed by a variable name. The variable
-is set to \fI-1\fR if no conversion error occured. It is set to the
-first error location in \fIdata\fR in case of a conversion error. All data
-until this error location is transformed and retured. This option may not
-be used together with \fB-nocomplain\fR.
-.
-The call does not fail on conversion errors, if the option
-\fB-nocomplain\fR is given. In this case, any error locations are replaced
-by \fB?\fR. Incomplete sequences are written verbatim to the output string.
-The purpose of this switch is to gain compatibility to prior versions of TCL.
-It is not recommended for any other usage.
+.VS "TCL8.7 TIP346, TIP607, TIP601"
+.PP
+.RS
+If the option \fB-nocomplain\fR is given, the command does not fail on
+encoding errors.  Instead, the replacement character \fB?\fR is output
+for any not representable character (like the dot \fB\\U2022\fR
+in \fBiso-8859-1\fR encoding, see example below).
+If the option \fB-nocomplain\fR is not given, the command will fail with an
+appropriate error message.
+.PP
+If the option \fB-failindex\fR with a variable name is given, the error reporting
+is changed in the following manner:
+in case of a conversion error, the position of the input character causing the error
+is returned in the given variable.  The return value of the command are the
+converted bytes until the first error position. No error condition is raised.
+In case of no error, the value \fI-1\fR is written to the variable.  This option
+may not be used together with \fB-nocomplain\fR.
+.PP
+The \fB-strict\fR option followes more strict rules in conversion.  Currently, it has
+no effect but may be used in future to add additional encoding checks.
+.VE "TCL8.7 TIP346, TIP607, TIP601"
+.RE
 .TP
 \fBencoding dirs\fR ?\fIdirectoryList\fR?
 .
@@ -104,7 +118,7 @@ omitted then the command returns the current system encoding.  The
 system encoding is used whenever Tcl passes strings to system calls.
 .SH EXAMPLE
 .PP
-The following example converts a byte sequence in Japanese euc-jp encoding to a TCL string:
+Example 1: convert a byte sequence in Japanese euc-jp encoding to a TCL string:
 .PP
 .CS
 set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"]
@@ -113,8 +127,9 @@ set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"]
 The result is the unicode codepoint:
 .QW "\eu306F" ,
 which is the Hiragana letter HA.
+.VS "TCL8.7 TIP346, TIP607, TIP601"
 .PP
-The following example detects the error location in an incomplete UTF-8 sequence:
+Example 2: detect the error location in an incomplete UTF-8 sequence:
 .PP
 .CS
 % set s [\fBencoding convertfrom\fR -failindex i utf-8 "A\exC3"]
@@ -123,7 +138,14 @@ A
 1
 .CE
 .PP
-The following example detects the error location while transforming to ISO8859-1
+Example 3: return the incomplete UTF-8 sequence by raw bytes:
+.PP
+.CS
+% set s [\fBencoding convertfrom\fR -nocomplain utf-8 "A\exC3"]
+.CE
+The result is "A" followed by the byte \exC3.
+.PP
+Example 4: detect the error location while transforming to ISO8859-1
 (ISO-Latin 1):
 .PP
 .CS
@@ -133,8 +155,16 @@ A
 1
 .CE
 .PP
+Example 5: replace a not representable character by the replacement character:
+.PP
+.CS
+% set s [\fBencoding convertto\fR -nocomplain utf-8 "A\eu0141"]
+A?
+.CE
+.VE "TCL8.7 TIP346, TIP607, TIP601"
+.PP
 .SH "SEE ALSO"
-Tcl_GetEncoding(3)
+Tcl_GetEncoding(3), fconfigure(n)
 .SH KEYWORDS
 encoding, unicode
 .\" Local Variables:
diff --git a/doc/fconfigure.n b/doc/fconfigure.n
index 2926777..912702f 100644
--- a/doc/fconfigure.n
+++ b/doc/fconfigure.n
@@ -102,26 +102,43 @@ system, as returned by \fBencoding system\fR.
 .RE
 .TP
 \fB\-eofchar\fR \fIchar\fR
-.TP
-\fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR
 .
 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.  For
-output, the end-of-file character is output when the channel is closed.
+character signals end-of-file when it is encountered during input.
 If \fIchar\fR is the empty string, then there is no special end of file
-character marker.  For read-write channels, a two-element list specifies
-the end of file marker for input and output, respectively.  As a
-convenience, when setting the end-of-file character for a read-write
-channel you can specify a single value that will apply to both reading
-and writing.  When querying the end-of-file character of a read-write
-channel, a two-element list will always be returned.  The default value
-for \fB\-eofchar\fR is the empty string in all cases except for files
-under Windows.  In that case the \fB\-eofchar\fR is Control-z (\ex1A) for
-reading and the empty string for writing.
+character marker.  The default value for \fB\-eofchar\fR is the empty
+string.
 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 "TCL9.0 TIP633"
+.TP
+\fB\-nocomplainencoding\fR \fIbool\fR
+.
+Reporting mode of encoding errors.
+If set to a \fItrue\fR value, encoding errors are resolved by a replacement
+character (output) or verbatim bytes (input). No error is thrown.
+If set to a \fIfalse\fR value, errors are thrown in case of encoding errors.
+.RS
+.PP
+The default value is \fIfalse\fR starting from TCL 9.0 and \fItrue\fR on TCL 8.7.
+This option was introduced with TCL 8.7 and has the fix value \fItrue\fR.
+.PP
+See the \fI\-nocomplain\fR option of the \fBencoding\fR command for more information.
+.RE
+.VE "TCL9.0 TIP633"
+.VS "TCL8.7 TIP346"
+.TP
+\fB\-strictencoding\fR \fIbool\fR
+.
+Activate additional stricter encoding application rules.
+Default value is \fIfalse\fR.
+.RS
+.PP
+See the \fI\-strict\fR option of the \fBencoding\fR command for more information.
+.VE "TCL8.7 TIP346"
+.RE
 .TP
 \fB\-translation\fR \fImode\fR
 .TP
@@ -278,10 +295,10 @@ set data [read $f $numDataBytes]
 close $f
 .CE
 .SH "SEE ALSO"
-close(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n),
+close(n), encoding(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n),
 Tcl_StandardChannels(3)
 .SH KEYWORDS
-blocking, buffering, carriage return, end of line, flushing, linemode,
+blocking, buffering, carriage return, end of line, encoding, flushing, linemode,
 newline, nonblocking, platform, translation, encoding, filter, byte array,
 binary
 '\" Local Variables:
diff --git a/doc/http.n b/doc/http.n
index 59f15b6..ff2307e 100644
--- a/doc/http.n
+++ b/doc/http.n
@@ -172,14 +172,15 @@ fresh socket, overriding the \fB\-keepalive\fR option of
 command \fBhttp::geturl\fR.  See the \fBPERSISTENT SOCKETS\fR section for
 details. The default is 0.
 .TP
-\fB\-proxyhost\fR \fIhostname\fR
-.
-The name of the proxy host, if any.  If this value is the
-empty string, the URL host is contacted directly.
-.TP
-\fB\-proxyport\fR \fInumber\fR
+\fB\-proxyauth\fR \fIstring\fR
 .
-The proxy port number.
+If non-empty, the string is supplied to the proxy server as the value of the
+request header Proxy-Authorization.  This option can be used for HTTP Basic
+Authentication.  If the proxy server requires authentication by another
+technique, e.g. Digest Authentication, the \fB\-proxyauth\fR option is not
+useful.  In that case the caller must expect a 407 response from the proxy,
+compute the authentication value to be supplied, and use the \fB\-headers\fR
+option to supply it as the value of the Proxy-Authorization header.
 .TP
 \fB\-proxyfilter\fR \fIcommand\fR
 .
@@ -188,18 +189,46 @@ The command is a callback that is made during
 to determine if a proxy is required for a given host.  One argument, a
 host name, is added to \fIcommand\fR when it is invoked.  If a proxy
 is required, the callback should return a two-element list containing
-the proxy server and proxy port.  Otherwise the filter should return
-an empty list.  The default filter returns the values of the
-\fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
-non-empty.
+the proxy server and proxy port.  Otherwise the filter command should return
+an empty list.
 .RS
 .PP
+The default value of \fB\-proxyfilter\fR is \fBhttp::ProxyRequired\fR, and
+this command returns the values of the \fB\-proxyhost\fR and
+\fB\-proxyport\fR settings if they are non-empty.  The options
+\fB\-proxyhost\fR, \fB\-proxyport\fR, and \fB\-proxynot\fR are used only
+by \fBhttp::ProxyRequired\fR, and nowhere else in \fB::http::geturl\fR.
+A user-supplied \fB\-proxyfilter\fR command may use these options, or
+alternatively it may obtain values from elsewhere in the calling script.
+In the latter case, any values provided for \fB\-proxyhost\fR,
+\fB\-proxyport\fR, and \fB\-proxynot\fR are unused.
+.PP
 The \fB::http::geturl\fR command runs the \fB\-proxyfilter\fR callback inside
 a \fBcatch\fR command.  Therefore an error in the callback command does
 not call the \fBbgerror\fR handler.  See the \fBERRORS\fR section for
 details.
 .RE
 .TP
+\fB\-proxyhost\fR \fIhostname\fR
+.
+The host name or IP address of the proxy server, if any.  If this value is
+the empty string, the URL host is contacted directly.  See
+\fB\-proxyfilter\fR for how the value is used.
+.TP
+\fB\-proxynot\fR \fIlist\fR
+.
+A Tcl list of domain names and IP addresses that should be accessed directly,
+not through the proxy server.  The target hostname is compared with each list
+element using a case-insensitive \fBstring match\fR.  It is often convenient
+to use the wildcard "*" at the start of a domain name (e.g. *.example.com) or
+at the end of an IP address (e.g. 192.168.0.*).  See \fB\-proxyfilter\fR for
+how the value is used.
+.TP
+\fB\-proxyport\fR \fInumber\fR
+.
+The port number of the proxy server.  See \fB\-proxyfilter\fR for how the
+value is used.
+.TP
 \fB\-repost\fR \fIboolean\fR
 .
 Specifies what to do if a POST request over a persistent connection fails
diff --git a/doc/safe.n b/doc/safe.n
index 6dd4033..6e0d948 100644
--- a/doc/safe.n
+++ b/doc/safe.n
@@ -468,7 +468,7 @@ Examples of use with "Sync Mode" off: any of these commands will set the
  safe::interpConfigure foo -accessPath {}
 .CE
 .RE
-.TP
+.PP
 Example of use with "Sync Mode" off: when initializing a safe interpreter
 with a non-empty access path, the ::auto_path will be set to {} unless its
 own value is also specified:
@@ -506,7 +506,7 @@ own value is also specified:
  }
 .CE
 .RE
-.TP
+.PP
 Example of use with "Sync Mode" off: the command
 \fBsafe::interpAddToAccessPath\fR does not change the safe interpreter's
 ::auto_path, and so any necessary change must be made by the script:
@@ -520,7 +520,6 @@ Example of use with "Sync Mode" off: the command
  safe::interpConfigure foo -autoPath $childAutoPath
 .CE
 .RE
-.TP
 .SH "SEE ALSO"
 interp(n), library(n), load(n), package(n), pkg_mkIndex(n), source(n),
 tm(n), unknown(n)