suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

subprocess docs: add notes about exec failure and full-pipe deadlock

Browse Source 
Closes PR 14003 and 13914
This commit is contained in:
Matthew Flatt 2013-09-06 14:29:01 -06:00
parent 97193c7620
commit af022e5b7e
1 changed files with 22 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
pkgs/racket-pkgs/racket-doc/scribblings/reference/subprocess.scrbl
View File

@ -29,6 +29,13 @@ environment variables @racket[current-environment-variables]. See also
@racket[system] and @racket[process] from
@racketmodname[racket/system].
@margin-note{On Unix and Mac OS X, subprocess creation is separate
from starting the program indicated by @racket[command]. In
particular, if @racket[command] refers to a non-existent or
non-executable file, an error will be reported (via standard error and
a non-0 exit code) in the subprocess, not in the creating
process.}
The @racket[command] argument is a path to a program executable, and
the @racket[arg]s are command-line arguments for the program. See
@racket[find-executable-path] for locating an executable based on
@ -84,6 +91,15 @@ The @racket[subprocess] procedure returns four values:
explicitly closed, usually with @racket[close-input-port] or
@racket[close-output-port].
@margin-note{A @tech{file-stream port} for communicating with a
subprocess is normally a pipe with a limited capacity. Beware of
creating deadlock by serializing a write to a subprocess followed by a
read, while the subprocess does the same, so that both processes end
up blocking on a write because the other end must first read to make
room in the pipe. Beware also of waiting for a subprocess to finish
without reading its output, because the subprocess may be blocked attempting
to write output into a full pipe.}
The returned ports are @tech{file-stream ports} (see
@secref["file-ports"]), and they are placed into the management of
the current custodian (see @secref["custodians"]). The
@ -334,6 +350,9 @@ subprocess has ended). The @racket[command] argument is a string or
byte string containing no nul characters. If the command succeeds, the
return value is @racket[#t], @racket[#f] otherwise.
@margin-note{See also @racket[subprocess] for notes about error
handling and the limited buffer capacity of subprocess pipes.}
If @racket[set-pwd?] is true, then the @envvar{PWD} environment
variable is set to the value of @racket[(current-directory)] when
starting the shell process.
@ -408,6 +427,9 @@ Executes a shell command asynchronously (using @exec{sh} on Unix
and Mac OS X, @exec{cmd} on Windows). The result is a list of five
values:
@margin-note{See also @racket[subprocess] for notes about error
handling and the limited buffer capacity of subprocess pipes.}
@itemize[
@item{an input port piped from the subprocess's standard output,}