[commit: packages/process] master, wip/issue15: Expose createProcess_ and document UseHandle behavior #2 (8d9cde7)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/process

On branches: master,wip/issue15
Link       : http://ghc.haskell.org/trac/ghc/changeset/8d9cde7744a239689baa6717482fc7208d1f7d6e/process

>---------------------------------------------------------------

commit 8d9cde7744a239689baa6717482fc7208d1f7d6e
Author: Michael Snoyman <michael at snoyman.com>
Date:   Wed Nov 26 10:37:37 2014 +0200

    Expose createProcess_ and document UseHandle behavior #2


>---------------------------------------------------------------

8d9cde7744a239689baa6717482fc7208d1f7d6e
 System/Process.hs           |  7 +++++++
 System/Process/Internals.hs | 11 +++++++++++
 changelog.md                |  3 +++
 3 files changed, 21 insertions(+)

diff --git a/System/Process.hs b/System/Process.hs
index bff7f5d..a5f92ff 100644
--- a/System/Process.hs
+++ b/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 at s provided for @std_in@, @std_out@, or @std_err@ via the
+ at 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
+ at Handle@ open after spawning the child process, please use 'createProcess_'
+instead.
+
 -}
 createProcess
   :: CreateProcess
diff --git a/System/Process/Internals.hs b/System/Process/Internals.hs
index 3de8944..b3fd8bd 100644
--- a/System/Process/Internals.hs
+++ b/System/Process/Internals.hs
@@ -222,6 +222,17 @@ data StdStream
                              -- and newline translation mode (just
                              -- like @Handle at s created by @openFile@).
 
+-- | This function is almost identical to @createProcess at . The only differences
+-- are:
+--
+-- * @Handle at 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
diff --git a/changelog.md b/changelog.md
index 896d581..8a1d630 100644
--- a/changelog.md
+++ b/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