merge core-8-6-branch

7 files changed, 74 insertions, 28 deletions

diff --git a/doc/SetResult.3 b/doc/SetResult.3
index dc8f487..e5b81d7 100644
--- a/doc/SetResult.3
+++ b/doc/SetResult.3
@@ -164,7 +164,7 @@ The source interpreter will have its result reset by this operation.
 .SH "DEPRECATED INTERFACES"
 .SS "OLD STRING PROCEDURES"
 .PP
-Use of the following procedures (is deprecated
+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
diff --git a/doc/chan.n b/doc/chan.n
index 7ea0d19..81aa9f4 100644
--- a/doc/chan.n
+++ b/doc/chan.n
@@ -287,12 +287,14 @@ slow destinations like network sockets.
 .RS
 .PP
 The \fBchan copy\fR command transfers data from \fIinputChan\fR until
-end of file or \fIsize\fR bytes have been transferred. If no
-\fB\-size\fR argument is given, then the copy goes until end of file.
-All the data read from \fIinputChan\fR is copied to \fIoutputChan\fR.
-Without the \fB\-command\fR option, \fBchan copy\fR blocks until the
-copy is complete and returns the number of bytes written to
-\fIoutputChan\fR.
+end of file or \fIsize\fR bytes or characters have been transferred;
+\fIsize\fR is in bytes if the two channels are using the same encoding,
+and is in characters otherwise.  If no \fB\-size\fR argument is given,
+then the copy goes until end of file. All the data read from
+\fIinputChan\fR is copied to \fIoutputChan\fR.  Without the
+\fB\-command\fR option, \fBchan copy\fR blocks until the copy is
+complete and returns the number of bytes or characters (using the same
+rules as for the \fB\-size\fR option) written to \fIoutputChan\fR.
 .PP
 The \fB\-command\fR argument makes \fBchan copy\fR work in the
 background.  In this case it returns immediately and the
@@ -547,6 +549,18 @@ 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
+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
 .VE 8.6
 .TP
 \fBchan pop \fIchannelId\fR
diff --git a/doc/exec.n b/doc/exec.n
index 9d58d90..70ace32 100644
--- a/doc/exec.n
+++ b/doc/exec.n
@@ -271,8 +271,9 @@ limitation as \fBexec\fR wants to communicate over pipes.  The Expect
 extension addresses this issue when communicating with a TUI application.
 .PP
 When attempting to execute an application, \fBexec\fR first searches for
-the name as it was specified.  Then, in order, \fB.com\fR, \fB.exe\fR, and
-\fB.bat\fR are appended to the end of the specified name and it searches
+the name as it was specified.  Then, in order,
+\fB.com\fR, \fB.exe\fR, \fB.bat\fR and \fB.cmd\fR
+are appended to the end of the specified name and it searches
 for the longer name.  If a directory name was not specified as part of the
 application name, the following directories are automatically searched in
 order when attempting to locate the application:
diff --git a/doc/fcopy.n b/doc/fcopy.n
index e5dd1d6..d39c803 100644
--- a/doc/fcopy.n
+++ b/doc/fcopy.n
@@ -25,12 +25,15 @@ network sockets.
 .PP
 The \fBfcopy\fR
 command transfers data from \fIinchan\fR until end of file
-or \fIsize\fR bytes have been
-transferred. If no \fB\-size\fR argument is given,
+or \fIsize\fR bytes or characters have been
+transferred; \fIsize\fR is in bytes if the two channels are using the
+same encoding, and is in characters otherwise.
+If no \fB\-size\fR argument is given,
 then the copy goes until end of file.
 All the data read from \fIinchan\fR is copied to \fIoutchan\fR.
 Without the \fB\-command\fR option, \fBfcopy\fR blocks until the copy is complete
-and returns the number of bytes written to \fIoutchan\fR.
+and returns the number of bytes or characters (using the same rules as
+for the \fB\-size\fR option) written to \fIoutchan\fR.
 .PP
 The \fB\-command\fR argument makes \fBfcopy\fR work in the background.
 In this case it returns immediately and the \fIcallback\fR is invoked
@@ -174,3 +177,6 @@ vwait done
 eof(n), fblocked(n), fconfigure(n), file(n)
 .SH KEYWORDS
 blocking, channel, end of line, end of file, nonblocking, read, translation
+'\" Local Variables:
+'\" mode: nroff
+'\" End:
diff --git a/doc/file.n b/doc/file.n
index 8e765da..2f8b70c 100644
--- a/doc/file.n
+++ b/doc/file.n
@@ -162,7 +162,9 @@ returns \fB/home\fR (or something similar).
 \fBfile executable \fIname\fR
 .
 Returns \fB1\fR if file \fIname\fR is executable by the current user,
-\fB0\fR otherwise.
+\fB0\fR otherwise. On Windows, which does not have an executable attribute,
+the command treats all directories and any files with extensions
+\fBexe\fR, \fBcom\fR, \fBcmd\fR or \fBbat\fR as executable.
 .TP
 \fBfile exists \fIname\fR
 .
@@ -482,10 +484,9 @@ not the effective ones.
 .TP
 \fBWindows\fR\0\0\0\0
 .
-The \fBfile owned\fR subcommand currently always reports that the current user
-is the owner of the file, without regard for what the operating system
-believes to be true, making an ownership test useless. This issue (#3613671)
-may be fixed in a future release of Tcl.
+The \fBfile owned\fR subcommand uses the user identifier (SID) of
+the process token, not the thread token which may be impersonating
+some other user.
 .SH EXAMPLES
 .PP
 This procedure shows how to search for C files in a given directory
diff --git a/doc/proc.n b/doc/proc.n
index 129f4df..fdccaca 100644
--- a/doc/proc.n
+++ b/doc/proc.n
@@ -34,8 +34,9 @@ one or two fields.  If there is only a single field in the specifier
 then it is the name of the argument; if there are two fields, then
 the first is the argument name and the second is its default value.
 Arguments with default values that are followed by non-defaulted
-arguments become required arguments.  In 8.6 this will be considered an
-error.
+arguments become required arguments; enough actual arguments must be
+supplied to allow all arguments up to and including the last required
+formal argument.
 .PP
 When \fIname\fR is invoked a local variable
 will be created for each of the formal arguments to the procedure; its
@@ -48,11 +49,14 @@ actual arguments for all the
 formal arguments that do not have defaults, and there must not be any extra
 actual arguments.
 Arguments with default values that are followed by non-defaulted
-arguments become required arguments (in 8.6 it will be considered an
-error).
+arguments become de-facto required arguments, though this may change
+in a future version of Tcl; portable code should ensure that all
+optional arguments come after all required arguments.
+.PP
 There is one special case to permit procedures with
 variable numbers of arguments.  If the last formal argument has the name
-\fBargs\fR, then a call to the procedure may contain more actual arguments
+.QW \fBargs\fR ,
+then a call to the procedure may contain more actual arguments
 than the procedure has formal arguments.  In this case, all of the actual arguments
 starting at the one that would be assigned to \fBargs\fR are combined into
 a list (as if the \fBlist\fR command had been used); this combined value
@@ -80,6 +84,20 @@ If an error occurs while executing the procedure
 body, then the procedure-as-a-whole will return that same error.
 .SH EXAMPLES
 .PP
+This is a procedure that takes two arguments and prints both their sum
+and their product. It also returns the string
+.QW OK
+to the caller as an explicit result.
+.PP
+.CS
+\fBproc\fR printSumProduct {x y} {
+    set sum [expr {$x + $y}]
+    set prod [expr {$x * $y}]
+    puts "sum is $sum, product is $prod"
+    return "OK"
+}
+.CE
+.PP
 This is a procedure that accepts arbitrarily many arguments and prints
 them out, one by one.
 .PP
diff --git a/doc/zlib.n b/doc/zlib.n
index 9f3078d..fd29e0d 100644
--- a/doc/zlib.n
+++ b/doc/zlib.n
@@ -174,7 +174,11 @@ to the \fBzlib push\fR command:
 .VS "TIP 400"
 Sets the compression dictionary to use when working with compressing or
 decompressing the data to be \fIbinData\fR. Not valid for transformations that
-work with gzip-format data.
+work with gzip-format data.  The dictionary should consist of strings (byte
+sequences) that are likely to be encountered later in the data to be compressed,
+with the most commonly used strings preferably put towards the end of the
+dictionary. Tcl provides no mechanism for choosing a good such dictionary for
+a particular data sequence.
 .VE
 .TP
 \fB\-header\fI dictionary\fR
@@ -207,11 +211,13 @@ compression algorithm depends on what format is being produced or consumed.
 .TP
 \fB\-dictionary\fI binData\fR
 .VS "TIP 400"
-This read-write options gets or sets the compression dictionary to use when
-working with compressing or decompressing the data to be \fIbinData\fR. It is
-not valid for transformations that work with gzip-format data, and should not
-normally be set on compressing transformations other than at the point where
-the transformation is stacked.
+This read-write options gets or sets the initial compression dictionary to use
+when working with compressing or decompressing the data to be \fIbinData\fR.
+It is not valid for transformations that work with gzip-format data, and should
+not normally be set on compressing transformations other than at the point where
+the transformation is stacked. Note that this cannot be used to get the
+current active compression dictionary mid-stream, as that information is not
+exposed by the underlying library.
 .VE
 .TP
 \fB\-flush\fI type\fR