Expose createProcess_ and document UseHandle behavior #2

System/Process.hs

@@ -41,6 +41,7 @@
 module System.Process (
     -- * Running sub-processes
     createProcess,
+    createProcess_,
     shell, proc,
     CreateProcess(..),
     CmdSpec(..),
@@ -179,6 +180,12 @@ To also set the directory in which to run @ls@:
 >       createProcess (proc "ls" []){ cwd = Just "\home\bob",
 >                                     std_out = CreatePipe }
 
+Note that @Handle@s provided for @std_in@, @std_out@, or @std_err@ via the
+@UseHandle@ constructor will be closed by calling this function. This is not
+always the desired behavior. In cases where you would like to leave the
+@Handle@ open after spawning the child process, please use 'createProcess_'
+instead.
+
 -}
 createProcess
   :: CreateProcess

System/Process/Internals.hs

@@ -222,6 +222,17 @@ data StdStream
                              -- and newline translation mode (just
                              -- like @Handle@s created by @openFile@).
 
+-- | This function is almost identical to @createProcess@. The only differences
+-- are:
+--
+-- * @Handle@s provided via @UseHandle@ are not closed automatically.
+--
+-- * This function takes an extra @String@ argument to be used in creating
+--   error messages.
+--
+-- This function has been available from the @System.Process.Internals@ module
+-- for some time, and is part of the @System.Process@ module since version
+-- 1.2.1.0.
 createProcess_
   :: String                     -- ^ function name (for error messages)
   -> CreateProcess

changelog.md

@@ -11,6 +11,9 @@
   * With GHC 7.10, `System.Cmd` and `System.Process` are now `Safe`
     (when compiled with older GHC versions they are just `Trustworthy`)
 
+  * Expose `createProcess_` function, and document behavior of `UseHandle` for
+    `createProcess`. See [issue #2](https://github.com/haskell/process/issues/2).
+
 ## 1.2.0.0  *Dec 2013*
 
   * Update to Cabal 1.10 format