gi-gio-2.0.27: Gio bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gio.Objects.SubprocessLauncher

Contents

- Exported types
- Methods
  - Overloaded methods
  - getenv
  - new
  - setCwd
  - setEnviron
  - setFlags
  - setStderrFilePath
  - setStdinFilePath
  - setStdoutFilePath
  - setenv
  - spawnv
  - takeFd
  - takeStderrFd
  - takeStdinFd
  - takeStdoutFd
  - unsetenv
- Properties
  - flags

Description

This class contains a set of options for launching child processes, such as where its standard input and output will be directed, the argument list, the environment, and more.

While the `Subprocess` class has high level functions covering popular cases, use of this class allows access to more advanced options. It can also be used to launch multiple subprocesses with a similar configuration.

Since: 2.40

Synopsis

- newtype SubprocessLauncher = SubprocessLauncher (ManagedPtr SubprocessLauncher)
- class (GObject o, IsDescendantOf SubprocessLauncher o) => IsSubprocessLauncher o
- toSubprocessLauncher :: (MonadIO m, IsSubprocessLauncher o) => o -> m SubprocessLauncher
- subprocessLauncherGetenv :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> [Char] -> m [Char]
- subprocessLauncherNew :: (HasCallStack, MonadIO m) => [SubprocessFlags] -> m SubprocessLauncher
- subprocessLauncherSetCwd :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> [Char] -> m ()
- subprocessLauncherSetEnviron :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> [[Char]] -> m ()
- subprocessLauncherSetFlags :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> [SubprocessFlags] -> m ()
- subprocessLauncherSetStderrFilePath :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Maybe [Char] -> m ()
- subprocessLauncherSetStdinFilePath :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Text -> m ()
- subprocessLauncherSetStdoutFilePath :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Maybe [Char] -> m ()
- subprocessLauncherSetenv :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> [Char] -> [Char] -> Bool -> m ()
- subprocessLauncherSpawnv :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> [[Char]] -> m Subprocess
- subprocessLauncherTakeFd :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Int32 -> Int32 -> m ()
- subprocessLauncherTakeStderrFd :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Int32 -> m ()
- subprocessLauncherTakeStdinFd :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Int32 -> m ()
- subprocessLauncherTakeStdoutFd :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Int32 -> m ()
- subprocessLauncherUnsetenv :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> [Char] -> m ()
- constructSubprocessLauncherFlags :: (IsSubprocessLauncher o, MonadIO m) => [SubprocessFlags] -> m (GValueConstruct o)

# Exported types

newtype SubprocessLauncher Source #

Memory-managed wrapper type.

Constructors

SubprocessLauncher (ManagedPtr SubprocessLauncher) |

#### Instances

Instances details

Eq SubprocessLauncher Source # |
Instance details Defined in GI.Gio.Objects.SubprocessLauncher Methods (==) :: SubprocessLauncher -> SubprocessLauncher -> Bool # (/=) :: SubprocessLauncher -> SubprocessLauncher -> Bool #
GObject SubprocessLauncher Source # |
Instance details Defined in GI.Gio.Objects.SubprocessLauncher
TypedObject SubprocessLauncher Source # |
Instance details Defined in GI.Gio.Objects.SubprocessLauncher Methods glibType :: IO GType Source #
ManagedPtrNewtype SubprocessLauncher Source # |
Instance details Defined in GI.Gio.Objects.SubprocessLauncher Methods toManagedPtr :: SubprocessLauncher -> ManagedPtr SubprocessLauncher Source #
IsGValue SubprocessLauncher Source # | Convert `SubprocessLauncher` to and from `GValue` with `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Objects.SubprocessLauncher Methods toGValue :: SubprocessLauncher -> IO GValue Source # fromGValue :: GValue -> IO SubprocessLauncher Source #
HasParentTypes SubprocessLauncher Source # |
Instance details Defined in GI.Gio.Objects.SubprocessLauncher
type ParentTypes SubprocessLauncher Source # |
Instance details Defined in GI.Gio.Objects.SubprocessLauncher type ParentTypes SubprocessLauncher = '[Object]

class (GObject o, IsDescendantOf SubprocessLauncher o) => IsSubprocessLauncher o Source #

Type class for types which can be safely cast to `SubprocessLauncher`, for instance with `toSubprocessLauncher`.

#### Instances

Instances details

(GObject o, IsDescendantOf SubprocessLauncher o) => IsSubprocessLauncher o Source # |
Instance details Defined in GI.Gio.Objects.SubprocessLauncher

toSubprocessLauncher :: (MonadIO m, IsSubprocessLauncher o) => o -> m SubprocessLauncher Source #

Cast to `SubprocessLauncher`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

## Overloaded methods

## getenv

subprocessLauncherGetenv Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> [Char] | `variable`: the environment variable to get
-> m [Char] | Returns: the value of the environment variable, `Nothing` if unset

Returns the value of the environment variable `variable` in the environment of processes launched from this launcher.

On UNIX, the returned string can be an arbitrary byte string. On Windows, it will be UTF-8.

Since: 2.40

## new

subprocessLauncherNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> [SubprocessFlags] | `flags`: `SubprocessFlags`
-> m SubprocessLauncher |

Creates a new `SubprocessLauncher`.

The launcher is created with the default options. A copy of the environment of the calling process is made at the time of this call and will be used as the environment that the process is launched in.

Since: 2.40

## setCwd

subprocessLauncherSetCwd Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> [Char] | `cwd`: the cwd for launched processes
-> m () |

Sets the current working directory that processes will be launched with.

By default processes are launched with the current working directory of the launching process at the time of launch.

Since: 2.40

## setEnviron

subprocessLauncherSetEnviron Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> [[Char]] | `env`: the replacement environment
-> m () |

Replace the entire environment of processes launched from this launcher with the given 'environ' variable.

Typically you will build this variable by using `listenv` to copy the process 'environ' and using the functions `environSetenv`, `environUnsetenv`, etc.

As an alternative, you can use `subprocessLauncherSetenv`, `subprocessLauncherUnsetenv`, etc.

Pass an empty array to set an empty environment. Pass `Nothing` to inherit the parent process’ environment. As of GLib 2.54, the parent process’ environment will be copied when `subprocessLauncherSetEnviron` is called. Previously, it was copied when the subprocess was executed. This means the copied environment may now be modified (using `subprocessLauncherSetenv`, etc.) before launching the subprocess.

On UNIX, all strings in this array can be arbitrary byte strings. On Windows, they should be in UTF-8.

Since: 2.40

## setFlags

subprocessLauncherSetFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> [SubprocessFlags] | `flags`: `SubprocessFlags`
-> m () |

Sets the flags on the launcher.

The default flags are `SubprocessFlagsNone`.

You may not set flags that specify conflicting options for how to handle a particular stdio stream (eg: specifying both `SubprocessFlagsStdinPipe` and `SubprocessFlagsStdinInherit`).

You may also not set a flag that conflicts with a previous call to a function like `subprocessLauncherSetStdinFilePath` or `subprocessLauncherTakeStdoutFd`.

Since: 2.40

## setStderrFilePath

subprocessLauncherSetStderrFilePath Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> Maybe [Char] | `path`: a filename or `Nothing`
-> m () |

Sets the file path to use as the stderr for spawned processes.

If `path` is `Nothing` then any previously given path is unset.

The file will be created or truncated when the process is spawned, as would be the case if using '2>' at the shell.

If you want to send both stdout and stderr to the same file then use `SubprocessFlagsStderrMerge`.

You may not set a stderr file path if a stderr fd is already set or if the launcher flags contain any flags directing stderr elsewhere.

This feature is only available on UNIX.

Since: 2.40

## setStdinFilePath

subprocessLauncherSetStdinFilePath Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> Text |
-> m () |

Sets the file path to use as the stdin for spawned processes.

If `path` is `Nothing` then any previously given path is unset.

The file must exist or spawning the process will fail.

You may not set a stdin file path if a stdin fd is already set or if the launcher flags contain any flags directing stdin elsewhere.

This feature is only available on UNIX.

Since: 2.40

## setStdoutFilePath

subprocessLauncherSetStdoutFilePath Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> Maybe [Char] | `path`: a filename or `Nothing`
-> m () |

Sets the file path to use as the stdout for spawned processes.

If `path` is `Nothing` then any previously given path is unset.

The file will be created or truncated when the process is spawned, as would be the case if using '>' at the shell.

You may not set a stdout file path if a stdout fd is already set or if the launcher flags contain any flags directing stdout elsewhere.

This feature is only available on UNIX.

Since: 2.40

## setenv

subprocessLauncherSetenv Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> [Char] | `variable`: the environment variable to set, must not contain '='
-> [Char] | `value`: the new value for the variable
-> Bool | `overwrite`: whether to change the variable if it already exists
-> m () |

Sets the environment variable `variable` in the environment of processes launched from this launcher.

On UNIX, both the variable's name and value can be arbitrary byte strings, except that the variable's name cannot contain '='. On Windows, they should be in UTF-8.

Since: 2.40

## spawnv

subprocessLauncherSpawnv Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> [[Char]] | `argv`: Command line arguments
-> m Subprocess | Returns: A new `Subprocess`, or `Nothing` on error (and `error` will be set) (Can throw `GError`)

Creates a `Subprocess` given a provided array of arguments.

Since: 2.40

## takeFd

subprocessLauncherTakeFd Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> Int32 | `sourceFd`: File descriptor in parent process
-> Int32 | `targetFd`: Target descriptor for child process
-> m () |

Transfer an arbitrary file descriptor from parent process to the child. This function takes "ownership" of the fd; it will be closed in the parent when `self` is freed.

By default, all file descriptors from the parent will be closed. This function allows you to create (for example) a custom `pipe()` or `socketpair()` before launching the process, and choose the target descriptor in the child.

An example use case is GNUPG, which has a command line argument --passphrase-fd providing a file descriptor number where it expects the passphrase to be written.

## takeStderrFd

subprocessLauncherTakeStderrFd Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> Int32 | `fd`: a file descriptor, or -1
-> m () |

Sets the file descriptor to use as the stderr for spawned processes.

If `fd` is -1 then any previously given fd is unset.

Note that the default behaviour is to pass stderr through to the stderr of the parent process.

The passed `fd` belongs to the `SubprocessLauncher`. It will be automatically closed when the launcher is finalized. The file descriptor will also be closed on the child side when executing the spawned process.

You may not set a stderr fd if a stderr file path is already set or if the launcher flags contain any flags directing stderr elsewhere.

This feature is only available on UNIX.

Since: 2.40

## takeStdinFd

subprocessLauncherTakeStdinFd Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> Int32 | `fd`: a file descriptor, or -1
-> m () |

Sets the file descriptor to use as the stdin for spawned processes.

If `fd` is -1 then any previously given fd is unset.

Note that if your intention is to have the stdin of the calling process inherited by the child then `SubprocessFlagsStdinInherit` is a better way to go about doing that.

The passed `fd` is noted but will not be touched in the current process. It is therefore necessary that it be kept open by the caller until the subprocess is spawned. The file descriptor will also not be explicitly closed on the child side, so it must be marked O_CLOEXEC if that's what you want.

You may not set a stdin fd if a stdin file path is already set or if the launcher flags contain any flags directing stdin elsewhere.

This feature is only available on UNIX.

Since: 2.40

## takeStdoutFd

subprocessLauncherTakeStdoutFd Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> Int32 | `fd`: a file descriptor, or -1
-> m () |

Sets the file descriptor to use as the stdout for spawned processes.

If `fd` is -1 then any previously given fd is unset.

Note that the default behaviour is to pass stdout through to the stdout of the parent process.

The passed `fd` is noted but will not be touched in the current process. It is therefore necessary that it be kept open by the caller until the subprocess is spawned. The file descriptor will also not be explicitly closed on the child side, so it must be marked O_CLOEXEC if that's what you want.

You may not set a stdout fd if a stdout file path is already set or if the launcher flags contain any flags directing stdout elsewhere.

This feature is only available on UNIX.

Since: 2.40

## unsetenv

subprocessLauncherUnsetenv Source #

Arguments

:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) |
=> a | `self`: a `SubprocessLauncher`
-> [Char] | `variable`: the environment variable to unset, must not contain '='
-> m () |

Removes the environment variable `variable` from the environment of processes launched from this launcher.

On UNIX, the variable's name can be an arbitrary byte string not containing '='. On Windows, it should be in UTF-8.

Since: 2.40

# Properties

## flags

No description available in the introspection data.

constructSubprocessLauncherFlags :: (IsSubprocessLauncher o, MonadIO m) => [SubprocessFlags] -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`flags`” property. This is rarely needed directly, but it is used by `new`.