Copyright | Will Thompson, Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
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.
- newtype SubprocessLauncher = SubprocessLauncher (ManagedPtr SubprocessLauncher)
- class GObject o => IsSubprocessLauncher o
- toSubprocessLauncher :: IsSubprocessLauncher o => o -> IO SubprocessLauncher
- noSubprocessLauncher :: Maybe SubprocessLauncher
- data SubprocessLauncherGetenvMethodInfo
- subprocessLauncherGetenv :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Text -> m Text
- subprocessLauncherNew :: (HasCallStack, MonadIO m) => [SubprocessFlags] -> m SubprocessLauncher
- data SubprocessLauncherSetChildSetupMethodInfo
- subprocessLauncherSetChildSetup :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> SpawnChildSetupFunc -> m ()
- data SubprocessLauncherSetCwdMethodInfo
- subprocessLauncherSetCwd :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> [Char] -> m ()
- data SubprocessLauncherSetEnvironMethodInfo
- subprocessLauncherSetEnviron :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> [Text] -> m ()
- data SubprocessLauncherSetFlagsMethodInfo
- subprocessLauncherSetFlags :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> [SubprocessFlags] -> m ()
- data SubprocessLauncherSetStderrFilePathMethodInfo
- subprocessLauncherSetStderrFilePath :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Maybe [Char] -> m ()
- data SubprocessLauncherSetStdinFilePathMethodInfo
- subprocessLauncherSetStdinFilePath :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Text -> m ()
- data SubprocessLauncherSetStdoutFilePathMethodInfo
- subprocessLauncherSetStdoutFilePath :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Maybe [Char] -> m ()
- data SubprocessLauncherSetenvMethodInfo
- subprocessLauncherSetenv :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Text -> Text -> Bool -> m ()
- data SubprocessLauncherSpawnvMethodInfo
- subprocessLauncherSpawnv :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> [Text] -> m Subprocess
- data SubprocessLauncherTakeFdMethodInfo
- subprocessLauncherTakeFd :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Int32 -> Int32 -> m ()
- data SubprocessLauncherTakeStderrFdMethodInfo
- subprocessLauncherTakeStderrFd :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Int32 -> m ()
- data SubprocessLauncherTakeStdinFdMethodInfo
- subprocessLauncherTakeStdinFd :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Int32 -> m ()
- data SubprocessLauncherTakeStdoutFdMethodInfo
- subprocessLauncherTakeStdoutFd :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Int32 -> m ()
- data SubprocessLauncherUnsetenvMethodInfo
- subprocessLauncherUnsetenv :: (HasCallStack, MonadIO m, IsSubprocessLauncher a) => a -> Text -> m ()
- data SubprocessLauncherFlagsPropertyInfo
- constructSubprocessLauncherFlags :: IsSubprocessLauncher o => [SubprocessFlags] -> IO (GValueConstruct o)
- subprocessLauncherFlags :: AttrLabelProxy "flags"
Exported types
newtype SubprocessLauncher Source #
GObject SubprocessLauncher Source # | |
IsObject SubprocessLauncher Source # | |
IsSubprocessLauncher SubprocessLauncher Source # | |
((~) * info (ResolveSubprocessLauncherMethod t SubprocessLauncher), MethodInfo * info SubprocessLauncher p) => IsLabel t (SubprocessLauncher -> p) Source # | |
((~) * info (ResolveSubprocessLauncherMethod t SubprocessLauncher), MethodInfo * info SubprocessLauncher p) => IsLabelProxy t (SubprocessLauncher -> p) Source # | |
HasAttributeList * SubprocessLauncher Source # | |
type AttributeList SubprocessLauncher Source # | |
type SignalList SubprocessLauncher Source # | |
class GObject o => IsSubprocessLauncher o Source #
toSubprocessLauncher :: IsSubprocessLauncher o => o -> IO SubprocessLauncher Source #
Methods
getenv
data SubprocessLauncherGetenvMethodInfo Source #
((~) * signature (Text -> m Text), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherGetenvMethodInfo a signature Source # | |
subprocessLauncherGetenv Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> Text |
|
-> m Text | Returns: the value of the environment variable, |
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 #
:: (HasCallStack, MonadIO m) | |
=> [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
setChildSetup
data SubprocessLauncherSetChildSetupMethodInfo Source #
((~) * signature (SpawnChildSetupFunc -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherSetChildSetupMethodInfo a signature Source # | |
subprocessLauncherSetChildSetup Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> SpawnChildSetupFunc |
|
-> m () |
Sets up a child setup function.
The child setup function will be called after fork()
but before
exec()
on the child's side.
destroyNotify
will not be automatically called on the child's side
of the fork()
. It will only be called when the last reference on the
SubprocessLauncher
is dropped or when a new child setup function is
given.
Nothing
can be given as childSetup
to disable the functionality.
Child setup functions are only available on UNIX.
Since: 2.40
setCwd
data SubprocessLauncherSetCwdMethodInfo Source #
((~) * signature ([Char] -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherSetCwdMethodInfo a signature Source # | |
subprocessLauncherSetCwd Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> [Char] |
|
-> 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
data SubprocessLauncherSetEnvironMethodInfo Source #
((~) * signature ([Text] -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherSetEnvironMethodInfo a signature Source # | |
subprocessLauncherSetEnviron Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> [Text] |
|
-> 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.
On UNIX, all strings in this array can be arbitrary byte strings. On Windows, they should be in UTF-8.
Since: 2.40
setFlags
data SubprocessLauncherSetFlagsMethodInfo Source #
((~) * signature ([SubprocessFlags] -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherSetFlagsMethodInfo a signature Source # | |
subprocessLauncherSetFlags Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> [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
data SubprocessLauncherSetStderrFilePathMethodInfo Source #
((~) * signature (Maybe [Char] -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherSetStderrFilePathMethodInfo a signature Source # | |
subprocessLauncherSetStderrFilePath Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> Maybe [Char] |
|
-> 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
data SubprocessLauncherSetStdinFilePathMethodInfo Source #
((~) * signature (Text -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherSetStdinFilePathMethodInfo a signature Source # | |
subprocessLauncherSetStdinFilePath Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> 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
data SubprocessLauncherSetStdoutFilePathMethodInfo Source #
((~) * signature (Maybe [Char] -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherSetStdoutFilePathMethodInfo a signature Source # | |
subprocessLauncherSetStdoutFilePath Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> Maybe [Char] |
|
-> 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
data SubprocessLauncherSetenvMethodInfo Source #
((~) * signature (Text -> Text -> Bool -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherSetenvMethodInfo a signature Source # | |
subprocessLauncherSetenv Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> Text |
|
-> Text |
|
-> Bool |
|
-> 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
data SubprocessLauncherSpawnvMethodInfo Source #
((~) * signature ([Text] -> m Subprocess), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherSpawnvMethodInfo a signature Source # | |
subprocessLauncherSpawnv Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> [Text] |
|
-> m Subprocess | Returns: A new |
Creates a Subprocess
given a provided array of arguments.
Since: 2.40
takeFd
data SubprocessLauncherTakeFdMethodInfo Source #
((~) * signature (Int32 -> Int32 -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherTakeFdMethodInfo a signature Source # | |
subprocessLauncherTakeFd Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> Int32 |
|
-> Int32 |
|
-> 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
data SubprocessLauncherTakeStderrFdMethodInfo Source #
((~) * signature (Int32 -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherTakeStderrFdMethodInfo a signature Source # | |
subprocessLauncherTakeStderrFd Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> Int32 |
|
-> 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
data SubprocessLauncherTakeStdinFdMethodInfo Source #
((~) * signature (Int32 -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherTakeStdinFdMethodInfo a signature Source # | |
subprocessLauncherTakeStdinFd Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> Int32 |
|
-> 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
data SubprocessLauncherTakeStdoutFdMethodInfo Source #
((~) * signature (Int32 -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherTakeStdoutFdMethodInfo a signature Source # | |
subprocessLauncherTakeStdoutFd Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> Int32 |
|
-> 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
data SubprocessLauncherUnsetenvMethodInfo Source #
((~) * signature (Text -> m ()), MonadIO m, IsSubprocessLauncher a) => MethodInfo * SubprocessLauncherUnsetenvMethodInfo a signature Source # | |
subprocessLauncherUnsetenv Source #
:: (HasCallStack, MonadIO m, IsSubprocessLauncher a) | |
=> a |
|
-> Text |
|
-> 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
data SubprocessLauncherFlagsPropertyInfo Source #
constructSubprocessLauncherFlags :: IsSubprocessLauncher o => [SubprocessFlags] -> IO (GValueConstruct o) Source #
subprocessLauncherFlags :: AttrLabelProxy "flags" Source #