Process Spawning Functions

---

This module is responsible for managing portable processes using Ecore. With this module you're able to spawn processes and you also can pause, quit your spawned processes. An interaction between your process and those spawned is possible using pipes or signals.

Example

• Ecore_exe

Functions
void	ecore_exe_run_priority_set (int pri)
int	ecore_exe_run_priority_get (void)
Ecore_Exe *	ecore_exe_run (const char *exe_cmd, const void *data)
Ecore_Exe *	ecore_exe_pipe_run (const char *exe_cmd, Ecore_Exe_Flags flags, const void *data)
void	ecore_exe_callback_pre_free_set (Ecore_Exe *exe, Ecore_Exe_Cb func)
Eina_Bool	ecore_exe_send (Ecore_Exe *exe, const void *data, int size)
void	ecore_exe_close_stdin (Ecore_Exe *exe)
void	ecore_exe_auto_limits_set (Ecore_Exe *exe, int start_bytes, int end_bytes, int start_lines, int end_lines)
Ecore_Exe_Event_Data *	ecore_exe_event_data_get (Ecore_Exe *exe, Ecore_Exe_Flags flags)
void	ecore_exe_event_data_free (Ecore_Exe_Event_Data *data)
void *	ecore_exe_free (Ecore_Exe *exe)
pid_t	ecore_exe_pid_get (const Ecore_Exe *exe)
void	ecore_exe_tag_set (Ecore_Exe *exe, const char *tag)
const char *	ecore_exe_tag_get (const Ecore_Exe *exe)
const char *	ecore_exe_cmd_get (const Ecore_Exe *exe)
void *	ecore_exe_data_get (const Ecore_Exe *exe)
void *	ecore_exe_data_set (Ecore_Exe *exe, void *data)
Ecore_Exe_Flags	ecore_exe_flags_get (const Ecore_Exe *exe)
void	ecore_exe_pause (Ecore_Exe *exe)
void	ecore_exe_continue (Ecore_Exe *exe)
void	ecore_exe_interrupt (Ecore_Exe *exe)
void	ecore_exe_quit (Ecore_Exe *exe)
void	ecore_exe_terminate (Ecore_Exe *exe)
void	ecore_exe_kill (Ecore_Exe *exe)
void	ecore_exe_signal (Ecore_Exe *exe, int num)
void	ecore_exe_hup (Ecore_Exe *exe)
Typedefs
typedef Eo	Ecore_Exe
typedef void(*	Ecore_Exe_Cb )(void *data, const Ecore_Exe *exe)
typedef struct _Ecore_Exe_Event_Add	Ecore_Exe_Event_Add
typedef struct _Ecore_Exe_Event_Del	Ecore_Exe_Event_Del
typedef struct _Ecore_Exe_Event_Data_Line	Ecore_Exe_Event_Data_Line
typedef struct _Ecore_Exe_Event_Data	Ecore_Exe_Event_Data
Defines
#define	ECORE_EXE_PRIORITY_INHERIT   9999

---

Define Documentation

#define ECORE_EXE_PRIORITY_INHERIT   9999

Inherit priority from parent process

---

Typedef Documentation

typedef Eo Ecore_Exe

A handle for spawned processes

Ecore_Exe_Cb Ecore_Exe_Cb

A callback to run with the associated Ecore_Exe, usually for cleanup purposes.

typedef struct _Ecore_Exe_Event_Add Ecore_Exe_Event_Add

Spawned Exe add event

typedef struct _Ecore_Exe_Event_Data Ecore_Exe_Event_Data

Data from a child process

typedef struct _Ecore_Exe_Event_Data_Line Ecore_Exe_Event_Data_Line

Lines from a child process

typedef struct _Ecore_Exe_Event_Del Ecore_Exe_Event_Del

Spawned Exe exit event

---

Enumeration Type Documentation

enum _Ecore_Exe_Flags

Flags for executing a child with its stdin and/or stdout piped back.

Enumerator:

ECORE_EXE_NONE	No exe flags at all
ECORE_EXE_PIPE_READ	Exe Pipe Read mask
ECORE_EXE_PIPE_WRITE	Exe Pipe Write mask
ECORE_EXE_PIPE_ERROR	Exe Pipe error mask
ECORE_EXE_PIPE_READ_LINE_BUFFERED	Reads are buffered until a newline and split 1 line per Ecore_Exe_Event_Data_Line
ECORE_EXE_PIPE_ERROR_LINE_BUFFERED	Errors are buffered until a newline and split 1 line per Ecore_Exe_Event_Data_Line
ECORE_EXE_PIPE_AUTO	stdout and stderr are buffered automatically
ECORE_EXE_RESPAWN	FIXME: Exe is restarted if it dies
ECORE_EXE_USE_SH	Use /bin/sh to run the command.
ECORE_EXE_NOT_LEADER	Do not use setsid() to have the executed process be its own session leader
ECORE_EXE_TERM_WITH_PARENT	Makes child receive SIGTERM when parent dies.

enum _Ecore_Exe_Win32_Priority

Defines the priority of the process.

Enumerator:

ECORE_EXE_WIN32_PRIORITY_IDLE	Idle priority, for monitoring the system
ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL	Below default priority
ECORE_EXE_WIN32_PRIORITY_NORMAL	Default priority
ECORE_EXE_WIN32_PRIORITY_ABOVE_NORMAL	Above default priority
ECORE_EXE_WIN32_PRIORITY_HIGH	High priority, use with care as other threads in the system will not get processor time
ECORE_EXE_WIN32_PRIORITY_REALTIME	Realtime priority, should be almost never used as it can interrupt system threads that manage mouse input, keyboard input, and background disk flushing

---

Function Documentation

void ecore_exe_auto_limits_set	(	Ecore_Exe *	exe,
		int	start_bytes,
		int	end_bytes,
		int	start_lines,
		int	end_lines
	)

Sets the auto pipe limits for the given process handle. On Windows this function does nothing.

Parameters:

exe	The given process handle.
start_bytes	Limit of bytes at start of output to buffer.
end_bytes	Limit of bytes at end of output to buffer.
start_lines	Limit of lines at start of output to buffer.
end_lines	Limit of lines at end of output to buffer.

Since :

3.0

void ecore_exe_callback_pre_free_set	(	Ecore_Exe *	exe,
		Ecore_Exe_Cb	func
	)

Defines a function to be called before really freeing the handle data.

This might be useful for language bindings such as Python and Perl that need to deallocate wrappers associated with this handle.

This handle should never be modified by this call. It should be considered informative only. All getters are valid when the given function is called back.

Parameters:

exe	The child process to attach the pre_free function.
func	The function to call before exe is freed.

Since :

3.0

void ecore_exe_close_stdin

(

Ecore_Exe *

exe

)

The stdin of the given child process will close when the write buffer is empty.

Parameters:

exe	The child process

Since :

3.0

const char* ecore_exe_cmd_get

(

const Ecore_Exe *

exe

)

Retrieves the command of the given spawned process.

Parameters:

exe	Handle to the given spawned process.

Returns:

The command on success, NULL otherwise. This string is the pointer to the internal value and must not be modified in any way.

Since :

3.0

void ecore_exe_continue

(

Ecore_Exe *

exe

)

Continues the given paused process by sending it a SIGCONT signal.

Parameters:

exe	Process handle to the given process.

Since :

3.0

void* ecore_exe_data_get

(

const Ecore_Exe *

exe

)

Retrieves the data attached to the given process handle.

Parameters:

exe	The given process handle.

Returns:

The data pointer attached to exe Given to ecore_exe_run() or ecore_exe_pipe_run()

Since :

3.0

void* ecore_exe_data_set	(	Ecore_Exe *	exe,
		void *	data
	)

Sets the data attached to the given process handle.

Parameters:

exe	The given process handle.
data	The pointer to attach.

Returns:

The data pointer previously attached to exe with ecore_exe_run(), ecore_exe_pipe_run(), or ecore_exe_data_set()

Since (EFL) :

1.1

Since :

3.0

void ecore_exe_event_data_free

(

Ecore_Exe_Event_Data *

data

)

Frees the given event data.

Parameters:

data	The given event data.

Since :

3.0

Ecore_Exe_Event_Data* ecore_exe_event_data_get	(	Ecore_Exe *	exe,
		Ecore_Exe_Flags	flags
	)

Gets the auto pipe data for the given process handle

Parameters:

exe	The given process handle.
flags	Is this a ECORE_EXE_PIPE_READ or ECORE_EXE_PIPE_ERROR?

Returns:

The event data.

Since :

3.0

Ecore_Exe_Flags ecore_exe_flags_get

(

const Ecore_Exe *

exe

)

Retrieves the flags attached to the given process handle.

Parameters:

exe	The given process handle.

Returns:

The flags attached to exe.

Since :

3.0

void* ecore_exe_free

(

Ecore_Exe *

exe

)

Frees the given process handle.

Note that the process that the handle represents is unaffected by this function.

Parameters:

exe	The given process handle.

Returns:

The data attached to the handle when ecore_exe_run was called.

Since :

3.0

Examples:

ecore_exe_example.c.

void ecore_exe_hup

(

Ecore_Exe *

exe

)

Sends a SIGHUP signal to the given spawned process.

Parameters:

exe	Process handle to the given process.

Since :

3.0

void ecore_exe_interrupt

(

Ecore_Exe *

exe

)

Sends the given spawned process a interrupt (SIGINT) signal.

Parameters:

exe	Process handle to the given process.

Since :

3.0

void ecore_exe_kill

(

Ecore_Exe *

exe

)

Kills the given spawned process by sending it a SIGKILL signal.

Parameters:

exe	Process handle to the given process.

Since :

3.0

void ecore_exe_pause

(

Ecore_Exe *

exe

)

Pauses the given process by sending it a SIGSTOP signal.

Parameters:

exe	Process handle to the given process.

Since :

3.0

pid_t ecore_exe_pid_get

(

const Ecore_Exe *

exe

)

Retrieves the process ID of the given spawned process.

Parameters:

exe	Handle to the given spawned process.

Returns:

The process ID on success, -1 otherwise.

Since :

3.0

Examples:

ecore_exe_example.c.

Ecore_Exe* ecore_exe_pipe_run	(	const char *	exe_cmd,
		Ecore_Exe_Flags	flags,
		const void *	data
	)

Spawns a child process with its stdin/out available for communication.

This function forks and runs the given command using /bin/sh.

Note that the process handle is only valid until a child process terminated event is received. After all handlers for the child process terminated event have been called, the handle will be freed by Ecore.

This function does the same thing as ecore_exe_run(), but also makes the standard in and/or out as well as stderr from the child process available for reading or writing. To write use ecore_exe_send(). To read listen to ECORE_EXE_EVENT_DATA or ECORE_EXE_EVENT_ERROR events (set up handlers). Ecore may buffer read and error data until a newline character if asked for with the flags. All data will be included in the events (newlines will be replaced with NULLS if line buffered). ECORE_EXE_EVENT_DATA events will only happen if the process is run with ECORE_EXE_PIPE_READ enabled in the flags. The same with the error version. Writing will only be allowed with ECORE_EXE_PIPE_WRITE enabled in the flags.

Parameters:

exe_cmd	The command to run with /bin/sh.
flags	The flag parameters for how to deal with inter-process I/O
data	Data to attach to the returned process handle.

Returns:

A process handle to the spawned process.

Since :

3.0

Examples:

ecore_exe_example.c.

void ecore_exe_quit

(

Ecore_Exe *

exe

)

Sends the given spawned process a quit (SIGQUIT) signal.

Parameters:

exe	Process handle to the given process.

Since :

3.0

Ecore_Exe* ecore_exe_run	(	const char *	exe_cmd,
		const void *	data
	)

Spawns a child process.

This is now just a thin wrapper around ecore_exe_pipe_run()

Parameters:

exe_cmd	The command to run with /bin/sh.
data	Data to attach to the returned process handle.

Returns:

A process handle to the spawned process.

Note:

When you use this function you will have no permissions to write or read on the pipe that connects you with the spwaned process. If you need to do that use ecore_exe_pipe_run() with the appropriated flags.

Since :

3.0

int ecore_exe_run_priority_get

(

void

)

Gets the priority at which to launch processes.

This gets the priority of launched processes. See ecore_exe_run_priority_set() for details. This just returns the value set by this call.

Returns:

The value set by ecore_exe_run_priority_set()

Since :

3.0

void ecore_exe_run_priority_set

(

int

pri

)

Sets the priority at which to launch processes.

This sets the priority of processes run by ecore_exe_run() and ecore_exe_pipe_run().

• On Windows, the child process is created by default with the ECORE_EXE_WIN32_PRIORITY_NORMAL priority, unless the calling process is in ECORE_EXE_WIN32_PRIORITY_IDLE or ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL priority. In that case, the child process inherits this priority.
• On other platforms, if set to ECORE_EXE_PRIORITY_INHERIT child processes inherits the priority of their parent. This is the default.

Parameters:

pri	Value an Ecore_Exe_Win32_Priority value on Windows, -20 to 19 or ECORE_EXE_PRIORITY_INHERIT on other OS.

Since :

3.0

Eina_Bool ecore_exe_send	(	Ecore_Exe *	exe,
		const void *	data,
		int	size
	)

Sends data to the given child process which it receives on stdin.

This function writes to a child processes standard in, with unlimited buffering. This call will never block. It may fail if the system runs out of memory.

Parameters:

exe	The child process to send to
data	The data to send
size	The size of the data to send, in bytes

Returns:

EINA_TRUE if successful, EINA_FALSE on failure.

Since :

3.0

Examples:

ecore_exe_example.c.

void ecore_exe_signal	(	Ecore_Exe *	exe,
		int	num
	)

Sends a SIGUSR signal to the given spawned process.

Parameters:

exe	Process handle to the given process.
num	The number user signal to send. Must be either 1 or 2, or the signal will be ignored.

Since :

3.0

const char* ecore_exe_tag_get

(

const Ecore_Exe *

exe

)

Retrieves the tag attached to the given process handle. There is no need to free it as it just returns the internal pointer value. This value is only valid as long as the exe is valid or until the tag is set to something else on this exe.

Parameters:

exe	The given process handle.

Returns:

The string attached to exe. It is a handle to existing internal string and should not be modified, use ecore_exe_tag_set() to change it. It might be NULL.

Since :

3.0

void ecore_exe_tag_set	(	Ecore_Exe *	exe,
		const char *	tag
	)

Sets the string tag for the given process handle.

Parameters:

exe	The given process handle.
tag	The string tag to set on the process handle.

Since :

3.0

void ecore_exe_terminate

(

Ecore_Exe *

exe

)

Sends the given spawned process a terminate (SIGTERM) signal.

Parameters:

exe	Process handle to the given process.

Since :

3.0

---

Variable Documentation

int ECORE_EXE_EVENT_ADD

A child process has been added

int ECORE_EXE_EVENT_DATA

Data from a child process.

Examples:

ecore_exe_example.c.

int ECORE_EXE_EVENT_DEL

A child process has been deleted (it exited, naming consistent with the rest of ecore).

int ECORE_EXE_EVENT_ERROR

Errors from a child process.