From af022e5b7e8476e27d435552fd730b8b4a1bc324 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Fri, 6 Sep 2013 14:29:01 -0600
Subject: [PATCH] subprocess docs: add notes about exec failure and full-pipe
 deadlock

Closes PR 14003 and 13914
---
 .../scribblings/reference/subprocess.scrbl    | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/reference/subprocess.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/reference/subprocess.scrbl
index bdce247f02..93a8e3906c 100644
--- a/pkgs/racket-pkgs/racket-doc/scribblings/reference/subprocess.scrbl
+++ b/pkgs/racket-pkgs/racket-doc/scribblings/reference/subprocess.scrbl
@@ -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,}