Module dglib.Spawn

Class Spawn

Implemented interfaces:

Spawn

Flags passed to gSpawnSync(), gSpawnAsync() and gSpawnAsyncWithPipes().

br> GSPAWNLEAVEDESCRIPTORSOPEN the parent's open file descriptors will be inherited by the child; otherwise all descriptors except stdin/stdout/stderr will be closed before calling exec() in the child.
GSPAWNDONOTREAPCHILD the child will not be automatically reaped; you must call waitpid() or handle SIGCHLD yourself, or the child will become a zombie.
GSPAWNSEARCHPATH argv[0] need not be an absolute path, it will be looked for in the user's PATH.
GSPAWNSTDOUTTODEVNULL the child's standad output will be discarded, instead of going to the same location as the parent's standard output.
GSPAWNSTDERRTODEVNULL the child's standard error will be discarded.
GSPAWNCHILDINHERITSSTDIN the child will inherit the parent's standard input (by default, the child's standard input is attached to /dev/null).
GSPAWNFILEANDARGVZERO the first element of argv is the file to execute, while the remaining elements are the actual argument vector to pass to the file. Normally gSpawnAsyncWithPipes() uses argv[0] as the file to execute, and passes all of argv to the child. Specifies the type of the setup function passed to gSpawnAsync(), gSpawnSync() and gSpawnAsyncWithPipes(). It is called in the child after GLib has performed all the setup it plans to perform but before calling exec(). Obviously, actions taken in this function will only affect the child, not the parent.

Parameters:

userData - user data to pass to the function. Executes a child program asynchronously (your program will not block waiting for the child to exit). The child program is specified by the only argument that must be provided, argv. argv should be a NULL-terminated array of strings, to be passed as the argument vector for the child. The first string in argv is of course the name of the program to execute. By default, the name of the program must be a full path; the PATH shell variable will only be searched if you pass the GSPAWNSEARCHPATH flag.
On Windows, the low-level child process creation API (CreateProcess())doesn't use argument vectors, but a command line. The C runtime library's spawn*() family of functions (which gSpawnAsyncWithPipes() eventually calls) paste the argument vector elements into a command line, and the C runtime startup code does a corresponding recostruction of an argument vector from the command line, to be passed to main(). Complications arise when you have argument vector elements that contain spaces of double quotes. The spawn*() functions don't do any quoting or escaping, but on the other hand the startup code does do unquoting and unescaping in order to enable receiving arguments with embedded spaces or double quotes. To work around this asymmetry, gSpawnAsyncWithPipes() will do quoting and escaping on argument vector elements that need it before calling the C runtime spawn() function.
envp is a NULL-terminated array of strings, where each string has the form KEY=VALUE. This will become the child's environment. If envp is NULL, the child inherits its parent's environment.
flags should be the bitwise OR of any flags you want to affect the function's behavior. On Unix, the GSPAWNDONOTREAPCHILD means that the child will not be automatically reaped; you must call waitpid() or handle SIGCHLD yourself, or the child will become a zombie. On Windows, the flag means that a handle to the child will be returned childPid. You must call CloseHandle() on it eventually (or exit the process), or the child processs will continue to take up some table space even after its death. Quite similar to zombies on Unix, actually.
GSPAWNLEAVEDESCRIPTORSOPEN means that the parent's open file descriptors will be inherited by the child; otherwise all descriptors except stdin/stdout/stderr will be closed before calling exec() in the child. GSPAWNSEARCHPATH means that argv[0] need not be an absolute path, it will be looked for in the user's PATH. GSPAWNSTDOUTTODEVNULL means that the child's standard output will be discarded, instead of going to the same location as the parent's standard output. If you use this flag, standardOutput must be NULL. GSPAWNSTDERRTODEVNULL means that the child's standard error will be discarded, instead of going to the same location as the parent's standard error. If you use this flag, standardError must be NULL. GSPAWNCHILDINHERITSSTDIN means that the child will inherit the parent's standard input (by default, the child's standard input is attached to /dev/null). If you use this flag, standardInput must be NULL. GSPAWNFILEANDARGVZERO means that the first element of argv is the file to execute, while the remaining elements are the actual argument vector to pass to the file. Normally gSpawnAsyncWithPipes() uses argv[0] as the file to execute, and passes all of argv to the child.
childSetup and userData are a function and user data. On POSIX platforms, the function is called in the child after GLib has performed all the setup it plans to perform (including creating pipes, closing file descriptors, etc.) but before calling exec(). That is, childSetup is called just before calling exec() in the child. Obviously actions taken in this function will only affect the child, not the parent. On Windows, there is no separate fork() and exec() functionality. Child processes are created and run right away with one API call, CreateProcess(). childSetup is called in the parent process just before creating the child process. You should carefully consider what you do in childSetup if you intend your software to be portable to Windows.
If non-NULL, childPid will on Unix be filled with the child's process ID. You can use the process ID to send signals to the child, or to waitpid() if you specified the GSPAWNDONOTREAPCHILD flag. On Windows, childPid will be filled with a handle to the child process only if you specified the GSPAWNDONOTREAPCHILD flag. You can then access the child process using the Win32 API, for example wait for its termination with the WaitFor*() functions, or examine its exit code with GetExitCodeProcess(). You should close the handle with CloseHandle() when you no longer need it.
If non-NULL, the standardInput, standardOutput, standardError locations will be filled with file descriptors for writing to the child's standard input or reading from its standard output or standard error. The caller of gSpawnAsyncWithPipes() must close these file descriptors when they are no longer in use. If these parameters are NULL, the corresponding pipe won't be created.
If standardInput is NULL, the child's standard input is attached to /dev/null unless GSPAWNCHILDINHERITSSTDIN is set.
If standardError is NULL, the child's standard error goes to the same location as the parent's standard error unless GSPAWNSTDERRTODEVNULL is set.
If standardOutput is NULL, the child's standard output goes to the same location as the parent's standard output unless GSPAWNSTDOUTTODEVNULL is set.
error can be NULL to ignore errors, or non-NULL to report errors. If an error is set, the function returns FALSE. Errors are reported even if they occur in the child (for example if the executable in argv[0] is not found). Typically the message field of returned errors should be displayed to users. Possible errors are those from the GSPAWNERROR domain.
If an error occurs, childPid, standardInput, standardOutput, and standardError will not be filled with valid values.
If childPid is not NULL and an error does not occur then the returned pid must be closed using gSpawnClosePid().

workingDirectory - child's current working directory, or NULL to inherit parent's

argv - child's argument vector

envp - child's environment, or NULL to inherit parent's

flags - flags from GSpawnFlags

childSetup - function to run in the child just before exec()

userData - user data for childSetup

childPid - return location for child process ID, or NULL

standardInput - return location for file descriptor to write to child's stdin, or NULL

standardOutput - return location for file descriptor to read child's stdout, or NULL

standardError - return location for file descriptor to read child's stderr, or NULL

error - return location for error

Returns:

TRUE on success, FALSE if an error was set

See gSpawnAsyncWithPipes() for a full description; this function simply calls the gSpawnAsyncWithPipes() without any pipes.

Parameters:

workingDirectory - child's current working directory, or NULL to inherit parent's

argv - child's argument vector

envp - child's environment, or NULL to inherit parent's

flags - flags from GSpawnFlags

childSetup - function to run in the child just before exec()

userData - user data for childSetup

childPid - return location for child process ID, or NULL

error - return location for error

Returns:

TRUE on success, FALSE if error is set

Executes a child synchronously (waits for the child to exit before returning).

All output from the child is stored in standardOutput and standardError, if those parameters are non-NULL. If exitStatus is non-NULL, the exit status of the child is stored there as it would be returned by waitpid(); standard UNIX macros such as WIFEXITED() and WEXITSTATUS() must be used to evaluate the exit status. If an error occurs, no data is returned in standardOutput, standardError, or exitStatus.
This function calls gSpawnAsyncWithPipes() internally; see that function for full details on the other parameters.

Parameters:

workingDirectory - child's current working directory, or NULL to inherit parent's

argv - child's argument vector

envp - child's environment, or NULL to inherit parent's

flags - flags from GSpawnFlags

childSetup - function to run in the child just before exec()

userData - user data for childSetup

standardOutput - return location for child output

standardError - return location for child error messages

exitStatus - child exit status, as returned by waitpid()

error - return location for error

Returns:

TRUE on success, FALSE if an error was set.

A simple version of gSpawnAsync() that parses a command line with gShellParseArgv() and passes it to gSpawnAsync().

Runs a command line in the background. Unlike gSpawnAsync(), the GSPAWNSEARCHPATH flag is enabled, other flags are not. Note that GSPAWNSEARCHPATH can have security implications, so consider using gSpawnAsync() directly if appropriate. Possible errors are those from gShellParseArgv() and gSpawnAsync().
The same concerns on Windows apply as for gSpawnCommandLineSync().

Parameters:

commandLine - a command line

error - return location for errors

Returns:

TRUE on success, FALSE if error is set.

A simple version of gSpawnSync() with little-used parameters removed, taking a command line instead of an argument vector.

See gSpawnSync() for full details. commandLine will be parsed by gShellParseArgv(). Unlike gSpawnSync(), the GSPAWNSEARCHPATH flag is enabled. Note that GSPAWNSEARCHPATH can have security implications, so consider using gSpawnSync() directly if appropriate. Possible errors are those from gSpawnSync() and those from gShellParseArgv().
On Windows, please note the implications of gShellParseArgv() parsing commandLine. Space is a separator, and backslashes are special. Thus you cannot simply pass a commandLine containing canonical Windows paths, like "c:\\program files\\app\\app.exe", as the backslashes will be eaten, and the space will act as a separator. You need to enclose such paths with single quotes, like "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".

Parameters:

commandLine - a command line

standardOutput - return location for child output

standardError - return location for child errors

exitStatus - return location for child exit status

error - return location for errors

Returns:

TRUE on success, FALSE if an error was set

On some platforms, notably WIN32, the GPid type represents a resource which must be closed to prevent resource leaking.

gSpawnClosePid() is provided for this purpose. It should be used on all platforms, even though it doesn't do anything under UNIX.

Parameters:

pid - The process identifier to close