System.Posix.Process

POSIX process support. See also the System.Cmd and System.Process modules in the process package.

Processes

Forking and executing

forkProcess :: IO () -> IO ProcessID

forkProcess corresponds to the POSIX fork system call. The IO action passed as an argument is executed in the child process; no other threads will be copied to the child process. On success, forkProcess returns the child's ProcessID to the parent process; in case of an error, an exception is thrown.

The exception masking state of the executed action is inherited (c.f. forkIO), see also forkProcessWithUnmask (since: 2.7.0.0).

forkProcess comes with a giant warning: since any other running threads are not copied into the child process, it's easy to go wrong: e.g. by accessing some shared resource that was held by another thread in the parent.

GHC note: forkProcess is not currently very well supported when using multiple capabilities (+RTS -N), although it is supported with -threaded as long as only one capability is being used.

forkProcessWithUnmask :: ((forall a. IO a -> IO a) -> IO ()) -> IO ProcessID

Variant of forkProcess in the style of forkIOWithUnmask.

Since: 2.7.0.0

executeFile

Arguments

:: FilePath

Command

-> Bool

Search PATH?

-> [String]

Arguments

-> Maybe [(String, String)]

Environment

-> IO a

executeFile cmd args env calls one of the execv* family, depending on whether or not the current PATH is to be searched for the command, and whether or not an environment is provided to supersede the process's current environment. The basename (leading directory names suppressed) of the command is passed to execv* as arg[0]; the argument list passed to executeFile therefore begins with arg[1].

Exiting

exitImmediately :: ExitCode -> IO a

exitImmediately status calls _exit to terminate the process with the indicated exit status. The operation never returns. Since it does not use the Haskell exception system and it cannot be caught.

Note: Prior to unix-2.8.0.0 the type-signature of exitImmediately was ExitCode -> IO ().

Since: 2.8.0.0

Process environment

getProcessID :: IO ProcessID

getProcessID calls getpid to obtain the ProcessID for the current process.

getParentProcessID :: IO ProcessID

getParentProcessID calls getppid to obtain the ProcessID for the parent of the current process.

Process groups

getProcessGroupID :: IO ProcessGroupID

getProcessGroupID calls getpgrp to obtain the ProcessGroupID for the current process.

getProcessGroupIDOf :: ProcessID -> IO ProcessGroupID

getProcessGroupIDOf pid calls getpgid to obtain the ProcessGroupID for process pid.

createProcessGroupFor :: ProcessID -> IO ProcessGroupID

createProcessGroupFor pid calls setpgid to make process pid a new process group leader.

joinProcessGroup :: ProcessGroupID -> IO ()

joinProcessGroup pgid calls setpgid to set the ProcessGroupID of the current process to pgid.

setProcessGroupIDOf :: ProcessID -> ProcessGroupID -> IO ()

setProcessGroupIDOf pid pgid calls setpgid to set the ProcessGroupIDOf for process pid to pgid.

Sessions

createSession :: IO ProcessGroupID

createSession calls setsid to create a new session with the current process as session leader.

Process times

data ProcessTimes

Constructors

ProcessTimes

Fields

• elapsedTime :: ClockTick
• userTime :: ClockTick
• systemTime :: ClockTick
• childUserTime :: ClockTick
• childSystemTime :: ClockTick

getProcessTimes :: IO ProcessTimes

getProcessTimes calls times to obtain time-accounting information for the current process and its children.

Scheduling priority

nice :: Int -> IO ()

getProcessPriority :: ProcessID -> IO Int

getProcessGroupPriority :: ProcessGroupID -> IO Int

getUserPriority :: UserID -> IO Int

setProcessPriority :: ProcessID -> Int -> IO ()

setProcessGroupPriority :: ProcessGroupID -> Int -> IO ()

setUserPriority :: UserID -> Int -> IO ()

Process status

data ProcessStatus

The exit status of a process

Constructors

Exited ExitCode

the process exited by calling exit() or returning from main

Terminated Signal Bool

the process was terminated by a signal, the Bool is True if a core dump was produced

Since: 2.7.0.0

Stopped Signal

the process was stopped by a signal

Instances

Show ProcessStatus

Defined in System.Posix.Process.Internals

Methods

showsPrec :: Int -> ProcessStatus -> ShowS

show :: ProcessStatus -> String

showList :: [ProcessStatus] -> ShowS

Eq ProcessStatus

Defined in System.Posix.Process.Internals

Methods

(==) :: ProcessStatus -> ProcessStatus -> Bool

(/=) :: ProcessStatus -> ProcessStatus -> Bool

Ord ProcessStatus

Defined in System.Posix.Process.Internals

Methods

compare :: ProcessStatus -> ProcessStatus -> Ordering

(<) :: ProcessStatus -> ProcessStatus -> Bool

(<=) :: ProcessStatus -> ProcessStatus -> Bool

(>) :: ProcessStatus -> ProcessStatus -> Bool

(>=) :: ProcessStatus -> ProcessStatus -> Bool

max :: ProcessStatus -> ProcessStatus -> ProcessStatus

min :: ProcessStatus -> ProcessStatus -> ProcessStatus

getProcessStatus :: Bool -> Bool -> ProcessID -> IO (Maybe ProcessStatus)

getProcessStatus blk stopped pid calls waitpid, returning Just tc, the ProcessStatus for process pid if it is available, Nothing otherwise. If blk is False, then WNOHANG is set in the options for waitpid, otherwise not. If stopped is True, then WUNTRACED is set in the options for waitpid, otherwise not.

getAnyProcessStatus :: Bool -> Bool -> IO (Maybe (ProcessID, ProcessStatus))

getAnyProcessStatus blk stopped calls waitpid, returning Just (pid, tc), the ProcessID and ProcessStatus for any child process if a child process has exited, or Nothing if there are child processes but none have exited. If there are no child processes, then getAnyProcessStatus raises an isDoesNotExistError exception.

If blk is False, then WNOHANG is set in the options for waitpid, otherwise not. If stopped is True, then WUNTRACED is set in the options for waitpid, otherwise not.

getGroupProcessStatus :: Bool -> Bool -> ProcessGroupID -> IO (Maybe (ProcessID, ProcessStatus))

getGroupProcessStatus blk stopped pgid calls waitpid, returning Just (pid, tc), the ProcessID and ProcessStatus for any process in group pgid if one is available, or Nothing if there are child processes but none have exited. If there are no child processes, then getGroupProcessStatus raises an isDoesNotExistError exception.

If blk is False, then WNOHANG is set in the options for waitpid, otherwise not. If stopped is True, then WUNTRACED is set in the options for waitpid, otherwise not.

Deprecated

createProcessGroup :: ProcessID -> IO ProcessGroupID

Deprecated: This function is scheduled to be replaced by something different in the future, we therefore recommend that you do not use this version and use createProcessGroupFor instead.

createProcessGroup pid calls setpgid to make process pid a new process group leader. This function is currently deprecated, and might be changed to making the current process a new process group leader in future versions.

setProcessGroupID :: ProcessID -> ProcessGroupID -> IO ()

Deprecated: This function is scheduled to be replaced by something different in the future, we therefore recommend that you do not use this version and use setProcessGroupIDOf instead.

setProcessGroupID pid pgid calls setpgid to set the ProcessGroupID for process pid to pgid. This function is currently deprecated, and might be changed to setting the ProcessGroupID for the current process in future versions.