Xfce Foundation Classes

SpawnAsync executes a child program asynchronously (that is, 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 vector of std::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 G::SPAWN_SEARCH_PATH flag. The first constructor takes an argv as a parameter and one or more optional spawn flags. The second constructor creates the argv argument for you from the passed in command line.

SpawnFlagsField should be the bitwise OR of any flags you want to affect the child's behavior. On Unix, the G::SPAWN_DO_NOT_REAP_CHILD 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 child_pid. 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.

G::SPAWN_LEAVE_DESCRIPTORS_OPEN 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. G::SPAWN_SEARCH_PATH means that argv[0] need not be an absolute path, it will be looked for in the user's PATH. G::SPAWN_STDOUT_TO_DEV_NULL 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, set_standard_output() is ignored. G::SPAWN_STDERR_TO_DEV_NULL 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, set_standard_error() will be ignored. G::SPAWN_CHILD_INHERITS_STDIN 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, set_standard_input() will be ignored. G::SPAWN_FILE_AND_ARGV_ZERO 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 SpawnAsync uses argv[0] as the file to execute, and passes all of argv to the child.

ChildSetupSlot is a user-defined method. On POSIX platforms, the method 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, the ChildSetupSlot is called just before calling exec() in the child. Obviously actions taken in this method 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(). The ChildSetupSlot is called in the parent process just before creating the child process. You should carefully consider what you do in the ChildSetupSlot method if you intend your software to be portable to Windows.

The process_id() method returns the child's process ID. You can use the process ID to send signals to the child, or to waitpid() if you specified the G::SPAWN_DO_NOT_REAP_CHILD flag. On Windows, child_pid will be filled with a handle to the child process only if you specified the G::SPAWN_DO_NOT_REAP_CHILD 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.

A G::Error should be passed to execute() to report errors but can be null to ignore them. If the G::Error is set, execute() 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 G_SPAWN_ERROR domain. If an error occurs the standard_input, standard_output, and standard_error file descriptors will not be filled with valid values, and process_id() will return zero.

    G::Error error;
    SpawnAsync child(command_line, &error);
    if (error.get())
    {
        // handle error
    }
    else
    {
        if (!child.execute(&error))
        {
                // handle error
        }
    }

Constructor & Destructor Documentation

Xfc::G::SpawnAsync::SpawnAsync	(	const std::vector< std::string > &	argv,
		SpawnFlagsField	flags = `0`
	)

Constructs an asynchronous spawn object with the specified arguments argv and spawn flags.

Parameters:

	argv	A reference to a vector of std::string that holds the child's argument strings.
	flags	One or more bitflags from the G::SpawnFlags enumeration.

The first string in argv (argv[0]) 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 G::SPAWN_SEARCH_PATH flag.

Xfc::G::SpawnAsync::SpawnAsync	(	const std::string &	command_line,
		G::Error *	error
	)

Constructs an asynchronous spawn object with the specified arguments in the command_line string.

Parameters:

	command_line	The command line string.
	error	The return location for a G::Error.

This constructor parses command line with g_shell_parse_argv() and passes it to GLib. If an error occurs it is set by the parsing function, and can be any of those from the G_SHELL_ERROR domain. Runs a command_line in the background. Unlike then other constructor, the G::SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note that G::SPAWN_SEARCH_PATH can have security implications, so consider using the other constructor if appropriate.

Member Function Documentation

GPid Xfc::G::SpawnAsync::child_pid

(

)

const

Returns the child process ID or zero if an error occurs.

Returns:: The child process ID.

bool Xfc::G::SpawnAsync::execute	(	const ChildSetupSlot &	slot,
		int *	std_input,
		int *	std_output,
		int *	std_error,
		G::Error *	error = `0`
	)

Executes a child program asynchronously (that is, your program will not block waiting for the child to exit).

Parameters:

	slot	A sigc::slot to call in the child just before exec().
	std_input	The return location for the file descriptor to write to child's stdin.
	std_output	The return location for the file descriptor to read child's stdout.
	std_error	The return location for the file descriptor to read child's stderr.
	error	The return location for a G::Error, or null to ignore errors.

Returns:: true if successful, false if error is set.

The file descriptors std_input, std_output, and std_error are used for writing to the child's standard input or reading from its standard output or standard error, and must be closed by calling close() when no longer required.

If std_input is null the child's standard input is attached to /dev/null unless G::SPAWN_CHILD_INHERITS_STDIN is set. If std_error is null the child's standard error goes to the same location as the parent's standard error unless G::SPAWN_STDERR_TO_DEV_NULL is set. If std_output is not called the child's standard output goes to the same location as the parent's standard output unless G::SPAWN_STDOUT_TO_DEV_NULL is set.

bool Xfc::G::SpawnAsync::execute	(	const ChildSetupSlot &	slot,
		G::Error *	error = `0`
	)

Executes a child program asynchronously (that is, your program will not block waiting for the child to exit).

Parameters:

	slot	A sigc::slot to call in the child just before exec().
	error	The return location for a G::Error, or null to ignore errors.

Returns:: true if successful, false if error is set.

bool Xfc::G::SpawnAsync::execute ( G::Error * error = 0 )

Executes a child program asynchronously (that is, your program will not block waiting for the child to exit).

Parameters:

error

The return location for a G::Error, or null to ignore errors.

Returns:: true if successful, false if error is set.

Xfc::G::SpawnAsync Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation