From 63f4be3aa2f1fe3a2f36da8509a5b02b8381870d Mon Sep 17 00:00:00 2001 From: dkf Date: Tue, 30 Mar 2021 09:03:19 +0000 Subject: Improve documentation for exec and open, especially in relation to binary pipelines --- doc/exec.n | 26 ++++++++++++++++++++++++++ doc/open.n | 39 ++++++++++++++++++++++++++++++++++++--- 2 files changed, 62 insertions(+), 3 deletions(-) diff --git a/doc/exec.n b/doc/exec.n index e40b596..89c6413 100644 --- a/doc/exec.n +++ b/doc/exec.n @@ -23,6 +23,10 @@ of one or more subprocesses to execute. The arguments take the form of a standard shell pipeline where each \fIarg\fR becomes one word of a command, and each distinct command becomes a subprocess. +The result of the command is the standard output of the final subprocess in +the pipeline, interpreted using the system \fBencoding\fR; to use any other +encoding (especially including binary data), the pipeline must be +\fBopen\fRed, configured and read explicitly. .PP If the initial arguments to \fBexec\fR start with \fB\-\fR then they are treated as command-line switches and are not part @@ -369,6 +373,7 @@ The \fBexec\fR command is fully functional and works as described. Here are some examples of the use of the \fBexec\fR command on Unix. .PP To execute a simple program and get its result: +.PP .CS \fBexec\fR uname -a .CE @@ -376,6 +381,7 @@ To execute a simple program and get its result: To execute a program that can return a non-zero result, you should wrap the call to \fBexec\fR in \fBcatch\fR and check the contents of the \fB\-errorcode\fR return option if you have an error: +.PP .CS set status 0 if {[catch {\fBexec\fR grep foo bar.txt} results options]} { @@ -391,10 +397,13 @@ if {[catch {\fBexec\fR grep foo bar.txt} results options]} { When translating a command from a Unix shell invocation, care should be taken over the fact that single quote characters have no special significance to Tcl. Thus: +.PP .CS awk '{sum += $1} END {print sum}' numbers.list .CE +.PP would be translated into something like: +.PP .CS \fBexec\fR awk {{sum += $1} END {print sum}} numbers.list .CE @@ -403,6 +412,7 @@ If you are converting invocations involving shell globbing, you should remember that Tcl does not handle globbing or expand things into multiple arguments by default. Instead you should write things like this: +.PP .CS \fBexec\fR ls -l {*}[glob *.tcl] .CE @@ -411,26 +421,41 @@ Here are some examples of the use of the \fBexec\fR command on Windows. .PP To start an instance of \fInotepad\fR editing a file without waiting for the user to finish editing the file: +.PP .CS \fBexec\fR notepad myfile.txt & .CE .PP To print a text file using \fInotepad\fR: +.PP .CS \fBexec\fR notepad /p myfile.txt .CE .PP +To print a text file in a directory other than the current one using +\fInotepad\fR, you need to use \fBfile nativename\fR to convert the name into +a form that will be understood by the other program: +.PP +.CS +\fBexec\fR notepad /p [file nativename some/dir/myfile.txt] +.CE +.PP If a program calls other programs, such as is common with compilers, then you may need to resort to batch files to hide the console windows that sometimes pop up: +.PP .CS \fBexec\fR cmp.bat somefile.c -o somefile .CE +.PP With the file \fIcmp.bat\fR looking something like: +.PP .CS @gcc %* .CE +.PP or like another variant using single parameters: +.PP .CS @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9 .CE @@ -448,6 +473,7 @@ applies especially when you want to run commands like \fIdir\fR from a Tcl script (if you just want to list filenames, use the \fBglob\fR command.) To do that, use this: +.PP .CS \fBexec\fR {*}[auto_execok dir] *.tcl .CE diff --git a/doc/open.n b/doc/open.n index a9da946..844433e 100644 --- a/doc/open.n +++ b/doc/open.n @@ -68,7 +68,7 @@ reading or writing of binary data. .VE 8.5 .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 @@ -351,7 +351,13 @@ pipe is closed. These problems only occur because both Tcl and the child 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. +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 @@ -376,8 +382,23 @@ input, but is redirected from a file, then the above problem does not occur. See the \fBPORTABILITY ISSUES\fR section of the \fBexec\fR command for additional information not specific to command pipelines about executing applications on the various platforms -.SH "EXAMPLE" +.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 .CS set fl [\fBopen\fR "| ls this_file_does_not_exist"] set data [read $fl] @@ -385,6 +406,18 @@ if {[catch {close $fl} err]} { puts "ls command failed: $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 .SH "SEE ALSO" file(n), close(n), filename(n), fconfigure(n), gets(n), read(n), puts(n), exec(n), pid(n), fopen(3) -- cgit v0.12