Haskell › Haskell - Libraries

documentation patch for process

Classic

List

Threaded

4 messages Options

Evan Laforge

documentation patch for process

I recently burned some time because I didn't realize that
System.Process.createProcess doesn't report when the binary isn't
found. I guess I was used to that behaviour from python's subprocess
module, which goes to some effort to report the error from the
fork()ed child when exec() fails. After a failed solution, I did some
poking around in the source to see exactly what haskell's process
does.

In the interests of saving someone else that time, I submit a patch to
process to add some documentation. I'm not sure how to do a 'darcs
send' with git, but here's the patch:

% git log | head
commit 5a46937961b3400fa58ccffc785d0de8c1c01d94
Author: Evan Laforge <[hidden email]>
Date: Wed Feb 8 13:25:16 2012 -0800

More detailed haddock for createProcess: document what happens if
the binary is not found

commit c8b30a6f1d493ab724f2da05dbc49496b119a051
Author: Simon Marlow <[hidden email]>
Date: Mon Jan 16 16:25:34 2012 +0000

% git diff HEAD\^
diff --git a/System/Process.hs b/System/Process.hs
index f3a8f9b..a372228 100644
--- a/System/Process.hs
+++ b/System/Process.hs
@@ -234,9 +234,18 @@ To create a pipe from which to read the output of @ls@:
To also set the directory in which to run @ls@:

> (_, Just hout, _, _) <-
-> createProcess (proc "ls" []){ cwd = Just "\home\bob",
+> createProcess (proc "ls" []){ cwd = Just "/home/bob",
> std_out = CreatePipe }

+Note that this does /not/ throw an error if the binary is not found,
+or not executable. Instead, the process will fail with the exit code 127.
+But you can't rely on it failing quickly, because it may e.g. hang up
+searching the PATH on a slow NFS mount. Since there's no way to tell when
+the exec() has succeeded, the only way to reliably know if the createProcess
+failed is to 'waitForProcess'.
+
+If the CreateProcess record's 'cwd' directory doesn't exist, the exit code
+will be 126.
-}
createProcess
:: CreateProcess
diff --git a/System/Process/Internals.hs b/System/Process/Internals.hs
index 11de1f4..2a6c047 100644
--- a/System/Process/Internals.hs
+++ b/System/Process/Internals.hs
@@ -199,7 +199,8 @@ data CmdSpec
= ShellCommand String
-- ^ a command line to execute using the shell
| RawCommand FilePath [String]
- -- ^ the filename of an executable with a list of arguments
+ -- ^ The filename of an executable with a list of arguments.
+ -- The PATH is searched for the executable.

data StdStream
= Inherit -- ^ Inherit Handle from parent

_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries

Evan Laforge

Re: documentation patch for process

Any interest in applying this? I don't think I have permissions.

Or should I get permissions somehow?

On Wed, Feb 8, 2012 at 1:25 PM, Evan Laforge <[hidden email]> wrote:

> I recently burned some time because I didn't realize that
> System.Process.createProcess doesn't report when the binary isn't
> found. I guess I was used to that behaviour from python's subprocess
> module, which goes to some effort to report the error from the
> fork()ed child when exec() fails. After a failed solution, I did some
> poking around in the source to see exactly what haskell's process
> does.
>
> In the interests of saving someone else that time, I submit a patch to
> process to add some documentation. I'm not sure how to do a 'darcs
> send' with git, but here's the patch:
>
> % git log | head
> commit 5a46937961b3400fa58ccffc785d0de8c1c01d94
> Author: Evan Laforge <[hidden email]>
> Date: Wed Feb 8 13:25:16 2012 -0800
>
> More detailed haddock for createProcess: document what happens if
> the binary is not found
>
> commit c8b30a6f1d493ab724f2da05dbc49496b119a051
> Author: Simon Marlow <[hidden email]>
> Date: Mon Jan 16 16:25:34 2012 +0000
>
> % git diff HEAD\^
> diff --git a/System/Process.hs b/System/Process.hs
> index f3a8f9b..a372228 100644
> --- a/System/Process.hs
> +++ b/System/Process.hs
> @@ -234,9 +234,18 @@ To create a pipe from which to read the output of @ls@:
> To also set the directory in which to run @ls@:
>
> > (_, Just hout, _, _) <-
> -> createProcess (proc "ls" []){ cwd = Just "\home\bob",
> +> createProcess (proc "ls" []){ cwd = Just "/home/bob",
> > std_out = CreatePipe }
>
> +Note that this does /not/ throw an error if the binary is not found,
> +or not executable. Instead, the process will fail with the exit code 127.
> +But you can't rely on it failing quickly, because it may e.g. hang up
> +searching the PATH on a slow NFS mount. Since there's no way to tell when
> +the exec() has succeeded, the only way to reliably know if the createProcess
> +failed is to 'waitForProcess'.
> +
> +If the CreateProcess record's 'cwd' directory doesn't exist, the exit code
> +will be 126.
> -}
> createProcess
> :: CreateProcess
> diff --git a/System/Process/Internals.hs b/System/Process/Internals.hs
> index 11de1f4..2a6c047 100644
> --- a/System/Process/Internals.hs
> +++ b/System/Process/Internals.hs
> @@ -199,7 +199,8 @@ data CmdSpec
> = ShellCommand String
> -- ^ a command line to execute using the shell
> | RawCommand FilePath [String]
> - -- ^ the filename of an executable with a list of arguments
> + -- ^ The filename of an executable with a list of arguments.
> + -- The PATH is searched for the executable.
>
> data StdStream
> = Inherit -- ^ Inherit Handle from parent

_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries

Evan Laforge

Re: documentation patch for process

On Wed, Feb 22, 2012 at 5:52 PM, Evan Laforge <[hidden email]> wrote:
> Any interest in applying this? I don't think I have permissions.
>
> Or should I get permissions somehow?

I guess I'll give up on this eventually if there's no interest. But
it would still be nice to have more documentation.

Going once... going twice...

_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries

Simon Marlow-7

Re: documentation patch for process

In reply to this post by Evan Laforge

My apologies, I missed this:

On 08/02/2012 21:25, Evan Laforge wrote:

> % git diff HEAD\^
> diff --git a/System/Process.hs b/System/Process.hs
> index f3a8f9b..a372228 100644
> --- a/System/Process.hs
> +++ b/System/Process.hs
> @@ -234,9 +234,18 @@ To create a pipe from which to read the output of @ls@:
> To also set the directory in which to run @ls@:
>
> > (_, Just hout, _, _)<-
> -> createProcess (proc "ls" []){ cwd = Just "\home\bob",
> +> createProcess (proc "ls" []){ cwd = Just "/home/bob",
> > std_out = CreatePipe }
>
> +Note that this does /not/ throw an error if the binary is not found,
> +or not executable. Instead, the process will fail with the exit code 127.
> +But you can't rely on it failing quickly, because it may e.g. hang up
> +searching the PATH on a slow NFS mount. Since there's no way to tell when
> +the exec() has succeeded, the only way to reliably know if the createProcess
> +failed is to 'waitForProcess'.
> +
> +If the CreateProcess record's 'cwd' directory doesn't exist, the exit code
> +will be 126.
> -}

This isn't true on Windows, so at least the comment should be qualified
to that effect.

> createProcess
> :: CreateProcess
> diff --git a/System/Process/Internals.hs b/System/Process/Internals.hs
> index 11de1f4..2a6c047 100644
> --- a/System/Process/Internals.hs
> +++ b/System/Process/Internals.hs
> @@ -199,7 +199,8 @@ data CmdSpec
> = ShellCommand String
> -- ^ a command line to execute using the shell
> | RawCommand FilePath [String]
> - -- ^ the filename of an executable with a list of arguments
> + -- ^ The filename of an executable with a list of arguments.
> + -- The PATH is searched for the executable.

Again, I think Windows has a rather more complex method for finding
binaries, and in all cases it makes a difference whether the FilePath is
absolute or not. I forget the precise details.

The best way forward with this is to fix up the patch and submit it as a
GHC ticket.

Cheers,
Simon

_______________________________________________
Libraries mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/libraries