Repository : ssh://darcs.haskell.org//srv/darcs/packages/process On branch : master
http://hackage.haskell.org/trac/ghc/changeset/270e43a2138898967da904e3d61a6e2589cb7b1a >--------------------------------------------------------------- commit 270e43a2138898967da904e3d61a6e2589cb7b1a Author: Simon Marlow <[email protected]> Date: Mon Jun 4 10:41:18 2012 +0100 Document the precise semantics of executable searching (see #6094) I had to do some research to figure out what we were actually doing here, and it appears we're using the platform semantics (ie. execvp() on Unix and CreateProcess() on Windows), so I've documented that. >--------------------------------------------------------------- System/Process.hs | 25 +++++++++++++++++++++---- System/Process/Internals.hs | 4 +++- 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/System/Process.hs b/System/Process.hs index 51fba92..5a4a2b6 100644 --- a/System/Process.hs +++ b/System/Process.hs @@ -141,7 +141,7 @@ runCommand string = do 'runProcess'. -} runProcess - :: FilePath -- ^ Filename of the executable + :: FilePath -- ^ Filename of the executable (see 'proc' for details) -> [String] -- ^ Arguments to pass to the executable -> Maybe FilePath -- ^ Optional path to the working directory -> Maybe [(String,String)] -- ^ Optional environment (otherwise inherit) @@ -178,6 +178,23 @@ runProcess cmd args mb_cwd mb_env mb_stdin mb_stdout mb_stderr = do -- | Construct a 'CreateProcess' record for passing to 'createProcess', -- representing a raw command with arguments. +-- +-- The @FilePath@ names the executable, and is interpreted according +-- to the platform's standard policy for searching for +-- executables. Specifically: +-- +-- * on Unix systems the @execvp@ semantics is used, where if the +-- filename does not contain a slash (@/@) then the @PATH@ +-- environment variable is searched for the executable. +-- +-- * on Windows systems the Win32 @CreateProcess@ semantics is used. +-- Briefly: if the filename does not contain a path, then the +-- directory containing the parent executable is searched, followed +-- by the current directory, then some some standard locations, and +-- finally the current @PATH@. An @.exe@ extension is added if the +-- filename does not already have an extension. For full details +-- see the documentation for the Windows @SearchPath@ API. + proc :: FilePath -> [String] -> CreateProcess proc cmd args = CreateProcess { cmdspec = RawCommand cmd args, cwd = Nothing, @@ -285,7 +302,7 @@ runInteractiveCommand string = in text mode then use 'hSetBinaryMode'. -} runInteractiveProcess - :: FilePath -- ^ Filename of the executable + :: FilePath -- ^ Filename of the executable (see 'proc' for details) -> [String] -- ^ Arguments to pass to the executable -> Maybe FilePath -- ^ Optional path to the working directory -> Maybe [(String,String)] -- ^ Optional environment (otherwise inherit) @@ -373,7 +390,7 @@ waitForProcess ph = do -- * A string to pass on the standard input to the program. -- readProcess - :: FilePath -- ^ command to run + :: FilePath -- ^ Filename of the executable (see 'proc' for details) -> [String] -- ^ any arguments -> String -- ^ standard input -> IO String -- ^ stdout @@ -427,7 +444,7 @@ quite easy: follow the link to the source code to see how -} readProcessWithExitCode - :: FilePath -- ^ command to run + :: FilePath -- ^ Filename of the executable (see 'proc' for details) -> [String] -- ^ any arguments -> String -- ^ standard input -> IO (ExitCode,String,String) -- ^ exitcode, stdout, stderr diff --git a/System/Process/Internals.hs b/System/Process/Internals.hs index 11de1f4..a73c6fc 100644 --- a/System/Process/Internals.hs +++ b/System/Process/Internals.hs @@ -199,7 +199,9 @@ 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. + -- see 'System.Process.proc' for the precise interpretation of + -- the @FilePath@ field. data StdStream = Inherit -- ^ Inherit Handle from parent _______________________________________________ Cvs-libraries mailing list [email protected] http://www.haskell.org/mailman/listinfo/cvs-libraries
