Improve documentation for exec and open, especially in relation to binary pipelines

1 files changed, 32 insertions, 1 deletions

diff --git a/doc/open.n b/doc/open.n
index b0d9781..c7c8cf6 100644
--- a/doc/open.n
+++ b/doc/open.n
@@ -72,7 +72,7 @@ indicate that the opened channel should be configured as if with the
 reading or writing of binary data.
 .PP
 In the second form, \fIaccess\fR consists of a list of any of the
-following flags, all of which have the standard POSIX meanings.
+following flags, most of which have the standard POSIX meanings.
 One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR.
 .TP 15
 \fBRDONLY\fR
@@ -453,6 +453,12 @@ application are competing for the console at the same time.  If the command
 pipeline is started from a script, so that Tcl is not accessing the console,
 or if the command pipeline does not use standard input or output, but is
 redirected from or to a file, then the above problems do not occur.
+.PP
+Files opened in the
+.QW \fBa\fR
+mode or with the \fBAPPEND\fR flag set are implemented by seeking immediately
+before each write, which is not an atomic operation and does not carry the
+guarantee of strict appending that is present on POSIX platforms.
 .RE
 .TP
 \fBUnix\fR\0\0\0\0\0\0\0
@@ -527,6 +533,19 @@ Note that the equivalent options exist on Unix, but are on the serial channel
 type.
 .VE "8.7, TIP 160"
 .SH "EXAMPLES"
+Open a file for writing, forcing it to be created and raising an error if it
+already exists.
+.PP
+.CS
+set myNewFile [\fBopen\fR filename.txt {WRONLY CREAT EXCL}]
+.CE
+.PP
+Open a file for writing as a log file.
+.PP
+.CS
+set myLogFile [\fBopen\fR filename.log "a"]
+fconfigure $myLogFile -buffering line
+.CE
 .PP
 Open a command pipeline and catch any errors:
 .PP
@@ -538,6 +557,18 @@ if {[catch {close $fl} err]} {
 }
 .CE
 .PP
+Open a command pipeline and read binary data from it. Note the unusual form
+with
+.QW |[list
+that handles non-trivial edge cases with arguments that potentially have
+spaces in.
+.PP
+.CS
+set fl [\fBopen\fR |[list create_image_data $input] "rb"]
+set binData [read $fl]
+close $fl
+.CE
+.PP
 .VS "8.7, TIP 160"
 Read a password securely from the user (assuming that the script is being run
 interactively):