System.Posix.Process.ByteString

unix-2.7.2.0: POSIX functionality

Copyright | (c) The University of Glasgow 2002
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | provisional
Portability | non-portable (requires POSIX)
Safe Haskell | Safe
Language | Haskell2010

System.Posix.Process.ByteString

Contents

- Processes
  - Forking and executing
  - Exiting
  - Process environment
  - Process groups
  - Sessions
  - Process times
  - Scheduling priority
  - Process status
  - Deprecated

Description

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

Synopsis

- forkProcess :: IO () -> IO ProcessID
- forkProcessWithUnmask :: ((forall a. IO a -> IO a) -> IO ()) -> IO ProcessID
- executeFile :: RawFilePath -> Bool -> [ByteString] -> Maybe [(ByteString, ByteString)] -> IO a
- exitImmediately :: ExitCode -> IO ()
- getProcessID :: IO ProcessID
- getParentProcessID :: IO ProcessID
- getProcessGroupID :: IO ProcessGroupID
- getProcessGroupIDOf :: ProcessID -> IO ProcessGroupID
- createProcessGroupFor :: ProcessID -> IO ProcessGroupID
- joinProcessGroup :: ProcessGroupID -> IO ()
- setProcessGroupIDOf :: ProcessID -> ProcessGroupID -> IO ()
- createSession :: IO ProcessGroupID
- data ProcessTimes = ProcessTimes {
  - elapsedTime :: ClockTick
  - userTime :: ClockTick
  - systemTime :: ClockTick
  - childUserTime :: ClockTick
  - childSystemTime :: ClockTick
  }
- getProcessTimes :: IO ProcessTimes
- 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 ()
- data ProcessStatus
  - = Exited ExitCode
  - | Terminated Signal Bool
  - | Stopped Signal
- getProcessStatus :: Bool -> Bool -> ProcessID -> IO (Maybe ProcessStatus)
- getAnyProcessStatus :: Bool -> Bool -> IO (Maybe (ProcessID, ProcessStatus))
- getGroupProcessStatus :: Bool -> Bool -> ProcessGroupID -> IO (Maybe (ProcessID, ProcessStatus))
- createProcessGroup :: ProcessID -> IO ProcessGroupID
- setProcessGroupID :: ProcessID -> ProcessGroupID -> IO ()

# Processes

## Forking and executing

forkProcess :: IO () -> IO ProcessID Source

`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.

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

Variant of `forkProcess` in the style of `forkIOWithUnmask`.

Since: 2.7.0.0

executeFile Source

Arguments

:: RawFilePath | Command
-> Bool | Search PATH?
-> [ByteString] | Arguments
-> Maybe [(ByteString, ByteString)] | 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 () Source

``exitImmediately` status` calls `_exit` to terminate the process with the indicated exit `status`. The operation never returns.

## Process environment

getProcessID :: IO ProcessID Source

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

getParentProcessID :: IO ProcessID Source

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

## Process groups

getProcessGroupID :: IO ProcessGroupID Source

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

getProcessGroupIDOf :: ProcessID -> IO ProcessGroupID Source

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

createProcessGroupFor :: ProcessID -> IO ProcessGroupID Source

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

joinProcessGroup :: ProcessGroupID -> IO () Source

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

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

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

## Sessions

createSession :: IO ProcessGroupID Source

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

## Process times

data ProcessTimes Source

Constructors

ProcessTimes |
Fields elapsedTime :: ClockTick userTime :: ClockTick systemTime :: ClockTick childUserTime :: ClockTick childSystemTime :: ClockTick

getProcessTimes :: IO ProcessTimes Source

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

## Scheduling priority

nice :: Int -> IO () Source

getProcessPriority :: ProcessID -> IO Int Source

getProcessGroupPriority :: ProcessGroupID -> IO Int Source

getUserPriority :: UserID -> IO Int Source

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

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

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

## Process status

data ProcessStatus Source

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

Eq ProcessStatus |
Methods (==) :: ProcessStatus -> ProcessStatus -> Bool (/=) :: ProcessStatus -> ProcessStatus -> Bool
Ord ProcessStatus |
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
Show ProcessStatus |
Methods showsPrec :: Int -> ProcessStatus -> ShowS Source show :: ProcessStatus -> String Source showList :: [ProcessStatus] -> ShowS Source

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

``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)) Source

``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)) Source

``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 Source

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 () Source

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.