This module is responsible for managing portable processes using Ecore. More...

Data Structures

struct  _Ecore_Exe_Event_Add
 Process add event. More...
 
struct  _Ecore_Exe_Event_Del
 Process exit event. More...
 
struct  _Ecore_Exe_Event_Data_Line
 < Lines from a child process More...
 
struct  _Ecore_Exe_Event_Data
 Data from a child process event. More...
 

Macros

#define ECORE_EXE_PRIORITY_INHERIT   9999
 Inherit priority from parent process.
 

Typedefs

typedef enum _Ecore_Exe_Flags Ecore_Exe_Flags
 
typedef enum _Ecore_Exe_Win32_Priority Ecore_Exe_Win32_Priority
 
typedef struct _Ecore_Exe Ecore_Exe
 A handle for spawned processes.
 
typedef void(* Ecore_Exe_Cb) (void *data, const Ecore_Exe *exe)
 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_Del Ecore_Exe_Event_Del
 Spawned Exe exit event.
 
typedef struct _Ecore_Exe_Event_Data_Line Ecore_Exe_Event_Data_Line
 Lines from a child process.
 
typedef struct _Ecore_Exe_Event_Data Ecore_Exe_Event_Data
 Data from a child process.
 

Enumerations

enum  _Ecore_Exe_Flags {
  ECORE_EXE_NONE = 0,
  ECORE_EXE_PIPE_READ = 1,
  ECORE_EXE_PIPE_WRITE = 2,
  ECORE_EXE_PIPE_ERROR = 4,
  ECORE_EXE_PIPE_READ_LINE_BUFFERED = 8,
  ECORE_EXE_PIPE_ERROR_LINE_BUFFERED = 16,
  ECORE_EXE_PIPE_AUTO = 32,
  ECORE_EXE_RESPAWN = 64,
  ECORE_EXE_USE_SH = 128,
  ECORE_EXE_NOT_LEADER = 256,
  ECORE_EXE_TERM_WITH_PARENT = 512
}
 Flags for executing a child with its stdin and/or stdout piped back. More...
 
enum  _Ecore_Exe_Win32_Priority {
  ECORE_EXE_WIN32_PRIORITY_IDLE,
  ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL,
  ECORE_EXE_WIN32_PRIORITY_NORMAL,
  ECORE_EXE_WIN32_PRIORITY_ABOVE_NORMAL,
  ECORE_EXE_WIN32_PRIORITY_HIGH,
  ECORE_EXE_WIN32_PRIORITY_REALTIME
}
 Defines the priority of the proccess. More...
 

Functions

void ecore_exe_run_priority_set (int pri)
 Sets the priority at which to launch processes. More...
 
int ecore_exe_run_priority_get (void)
 Gets the priority at which to launch processes. More...
 
Ecore_Exeecore_exe_run (const char *exe_cmd, const void *data)
 Spawns a child process. More...
 
Ecore_Exeecore_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. More...
 
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. More...
 
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. More...
 
void ecore_exe_close_stdin (Ecore_Exe *exe)
 The stdin of the given child process will close when the write buffer is empty. More...
 
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. More...
 
Ecore_Exe_Event_Dataecore_exe_event_data_get (Ecore_Exe *exe, Ecore_Exe_Flags flags)
 Gets the auto pipe data for the given process handle. More...
 
void ecore_exe_event_data_free (Ecore_Exe_Event_Data *e)
 Frees the given event data. More...
 
void * ecore_exe_free (Ecore_Exe *exe)
 Frees the given process handle. More...
 
pid_t ecore_exe_pid_get (const Ecore_Exe *exe)
 Retrieves the process ID of the given spawned process. More...
 
void ecore_exe_tag_set (Ecore_Exe *exe, const char *tag)
 Sets the string tag for the given process handle. More...
 
const char * ecore_exe_tag_get (const Ecore_Exe *exe)
 Retrieves the tag attached to the given process handle. More...
 
const char * ecore_exe_cmd_get (const Ecore_Exe *exe)
 Retrieves the command of the given spawned process. More...
 
void * ecore_exe_data_get (const Ecore_Exe *exe)
 Retrieves the data attached to the given process handle. More...
 
void * ecore_exe_data_set (Ecore_Exe *exe, void *data)
 Sets the data attached to the given process handle. More...
 
Ecore_Exe_Flags ecore_exe_flags_get (const Ecore_Exe *exe)
 Retrieves the flags attached to the given process handle. More...
 
void ecore_exe_pause (Ecore_Exe *exe)
 Pauses the given process by sending it a SIGSTOP signal. More...
 
void ecore_exe_continue (Ecore_Exe *exe)
 Continues the given paused process by sending it a SIGCONT signal. More...
 
void ecore_exe_interrupt (Ecore_Exe *exe)
 Sends the given spawned process a interrupt (SIGINT) signal. More...
 
void ecore_exe_quit (Ecore_Exe *exe)
 Sends the given spawned process a quit (SIGQUIT) signal. More...
 
void ecore_exe_terminate (Ecore_Exe *exe)
 Sends the given spawned process a terminate (SIGTERM) signal. More...
 
void ecore_exe_kill (Ecore_Exe *exe)
 Kills the given spawned process by sending it a SIGKILL signal. More...
 
void ecore_exe_signal (Ecore_Exe *exe, int num)
 Sends a SIGUSR signal to the given spawned process. More...
 
void ecore_exe_hup (Ecore_Exe *exe)
 Sends a SIGHUP signal to the given spawned process. More...
 

Variables

int ECORE_EXE_EVENT_ADD
 A child process has been added.
 
int ECORE_EXE_EVENT_DEL
 A child process has been deleted (it exited, naming consistent with the rest of ecore). More...
 
int ECORE_EXE_EVENT_DATA
 Data from a child process. More...
 
int ECORE_EXE_EVENT_ERROR
 Errors from a child process. More...
 
static int run_pri = ECORE_EXE_PRIORITY_INHERIT
 

Detailed Description

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

Enumeration Type Documentation

§ _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.

§ _Ecore_Exe_Win32_Priority

Defines the priority of the proccess.

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

§ ecore_exe_run_priority_set()

EAPI 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().

Parameters
privalue a Ecore_Exe_Win32_Priority value on Windows, -20 to 19 or ECORE_EXE_PRIORITY_INHERIT on other OS.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_run_priority_get()

EAPI int ecore_exe_run_priority_get ( void  )

Gets the priority at which to launch processes.

This gets ths 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()

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

§ ecore_exe_run()

EAPI 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()

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.
Parameters
exe_cmdThe command to run with /bin/sh.
dataData to attach to the returned process handle.
Returns
A process handle to the spawned process.

References EAPI, ecore_exe_pipe_run(), and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

§ ecore_exe_pipe_run()

EAPI 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_cmdThe command to run with /bin/sh.
flagsThe flag parameters for how to deal with inter-process I/O
dataData to attach to the returned process handle.
Returns
A process handle to the spawned process.
Examples:
ecore_exe_example.c.

References ECORE_EXE_PIPE_AUTO, ECORE_EXE_PIPE_ERROR, ECORE_EXE_PIPE_READ, ECORE_EXE_PIPE_WRITE, EINA_MAIN_LOOP_CHECK_RETURN_VAL, and pipe.

Referenced by ecore_exe_run().

§ ecore_exe_callback_pre_free_set()

EAPI 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
exeThe child process to attach the pre_free function.
funcThe function to call before exe is freed.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_send()

EAPI 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
exeThe child process to send to
dataThe data to send
sizeThe size of the data to send, in bytes
Returns
EINA_TRUE if successful, EINA_FALSE on failure.
Examples:
ecore_exe_example.c.

References EINA_FALSE, and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

§ ecore_exe_close_stdin()

EAPI void ecore_exe_close_stdin ( Ecore_Exe exe)

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

Parameters
exeThe child process

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_auto_limits_set()

EAPI 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
exeThe given process handle.
start_byteslimit of bytes at start of output to buffer.
end_byteslimit of bytes at end of output to buffer.
start_lineslimit of lines at start of output to buffer.
end_lineslimit of lines at end of output to buffer.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_event_data_get()

EAPI 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
exeThe given process handle.
flagsIs this a ECORE_EXE_PIPE_READ or ECORE_EXE_PIPE_ERROR?
Returns
The event data.

References _Ecore_Exe_Event_Data::data, EAPI, ECORE_EXE_PIPE_ERROR, ECORE_EXE_PIPE_ERROR_LINE_BUFFERED, ECORE_EXE_PIPE_READ, ECORE_EXE_PIPE_READ_LINE_BUFFERED, EINA_MAIN_LOOP_CHECK_RETURN_VAL, _Ecore_Exe_Event_Data::exe, _Ecore_Exe_Event_Data_Line::line, _Ecore_Exe_Event_Data::lines, _Ecore_Exe_Event_Data_Line::size, and _Ecore_Exe_Event_Data::size.

§ ecore_exe_event_data_free()

EAPI void ecore_exe_event_data_free ( Ecore_Exe_Event_Data e)

Frees the given event data.

Parameters
eThe given event data.

References _Ecore_Exe_Event_Data::data, EAPI, and _Ecore_Exe_Event_Data::lines.

§ ecore_exe_free()

EAPI 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
exeThe given process handle.
Returns
The data attached to the handle when ecore_exe_run was called.
Examples:
ecore_exe_example.c.

References EAPI, ecore_main_fd_handler_del(), ecore_timer_del(), EINA_INLIST_GET, eina_inlist_remove(), and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

§ ecore_exe_pid_get()

EAPI pid_t ecore_exe_pid_get ( const Ecore_Exe exe)

Retrieves the process ID of the given spawned process.

Parameters
exeHandle to the given spawned process.
Returns
The process ID on success. -1 otherwise.
Examples:
ecore_exe_example.c.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

§ ecore_exe_tag_set()

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

Sets the string tag for the given process handle.

Parameters
exeThe given process handle.
tagThe string tag to set on the process handle.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_tag_get()

EAPI 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
exeThe 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.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

§ ecore_exe_cmd_get()

EAPI const char * ecore_exe_cmd_get ( const Ecore_Exe exe)

Retrieves the command of the given spawned process.

Parameters
exeHandle 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.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

§ ecore_exe_data_get()

EAPI void * ecore_exe_data_get ( const Ecore_Exe exe)

Retrieves the data attached to the given process handle.

Parameters
exeThe given process handle.
Returns
The data pointer attached to exe Given to ecore_exe_run() or ecore_exe_pipe_run()

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

§ ecore_exe_data_set()

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

Sets the data attached to the given process handle.

Parameters
exeThe given process handle.
dataThe 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
1.1

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

§ ecore_exe_flags_get()

EAPI Ecore_Exe_Flags ecore_exe_flags_get ( const Ecore_Exe exe)

Retrieves the flags attached to the given process handle.

Parameters
exeThe given process handle.
Returns
The flags attached to exe.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

§ ecore_exe_pause()

EAPI void ecore_exe_pause ( Ecore_Exe exe)

Pauses the given process by sending it a SIGSTOP signal.

Parameters
exeProcess handle to the given process.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_continue()

EAPI void ecore_exe_continue ( Ecore_Exe exe)

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

Parameters
exeProcess handle to the given process.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_interrupt()

EAPI void ecore_exe_interrupt ( Ecore_Exe exe)

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

Parameters
exeProcess handle to the given process.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_quit()

EAPI void ecore_exe_quit ( Ecore_Exe exe)

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

Parameters
exeProcess handle to the given process.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_terminate()

EAPI void ecore_exe_terminate ( Ecore_Exe exe)

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

Parameters
exeProcess handle to the given process.

References EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_kill()

EAPI void ecore_exe_kill ( Ecore_Exe exe)

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

Parameters
exeProcess handle to the given process.

References ecore_timer_add(), ecore_timer_del(), and EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_signal()

EAPI void ecore_exe_signal ( Ecore_Exe exe,
int  num 
)

Sends a SIGUSR signal to the given spawned process.

Parameters
exeProcess handle to the given process.
numThe number user signal to send. Must be either 1 or 2, or the signal will be ignored.

References EAPI, and EINA_MAIN_LOOP_CHECK_RETURN.

§ ecore_exe_hup()

EAPI void ecore_exe_hup ( Ecore_Exe exe)

Sends a SIGHUP signal to the given spawned process.

Parameters
exeProcess handle to the given process.

References EINA_MAIN_LOOP_CHECK_RETURN.

Variable Documentation

§ ECORE_EXE_EVENT_DEL

int ECORE_EXE_EVENT_DEL

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

§ ECORE_EXE_EVENT_DATA

int ECORE_EXE_EVENT_DATA

Data from a child process.

Examples:
ecore_exe_example.c.

§ ECORE_EXE_EVENT_ERROR

int ECORE_EXE_EVENT_ERROR

Errors from a child process.