Process Spawning Functions

Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
Process Spawning Functions
Ecore » Ecore main loop

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

## Data Structures
struct | _Ecore_Exe_Event_Add
| A structure that stores information of a Process add event. More...
struct | _Ecore_Exe_Event_Del
| A structure that stores information of a Process exit event. More...
struct | _Ecore_Exe_Event_Data_Line
| A structure that stores information of lines data from a child process. More...
struct | _Ecore_Exe_Event_Data
| A structure that stores information of data from a child process event. More...

## Macros
#define | ECORE_EXE_PRIORITY_INHERIT 9999
| Inherit priority from parent process.
#define | _ECORE_EXE_EO_CLASS_TYPE

## Typedefs
typedef enum _Ecore_Exe_Flags | Ecore_Exe_Flags
typedef enum _Ecore_Exe_Win32_Priority | Ecore_Exe_Win32_Priority
typedef Eo | 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 process. 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_Exe * | ecore_exe_run (const char *exe_cmd, const void *data)
| Spawns a child process. More...
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. 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_Data * | ecore_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 *data)
| 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...

## 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

- Ecore_exe

## Enumeration Type Documentation

## ◆ _Ecore_Exe_Flags

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.

## ◆ _Ecore_Exe_Win32_Priority

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

## ◆ ecore_exe_run_priority_set()

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 a Ecore_Exe_Win32_Priority value on Windows, -20 to 19 or ECORE_EXE_PRIORITY_INHERIT on other OS.

References EINA_MAIN_LOOP_CHECK_RETURN.

## ◆ ecore_exe_run_priority_get()

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

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ◆ ecore_exe_run()

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

References ecore_exe_pipe_run(), and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ◆ ecore_exe_pipe_run()

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.

Examples:
  ecore_exe_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, EINA_UNUSED, eo_add, and eo_data_scope_get().

Referenced by ecore_exe_run().

## ◆ ecore_exe_callback_pre_free_set()

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.

References EINA_MAIN_LOOP_CHECK_RETURN, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_send()

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.

Examples:
  ecore_exe_example.c.

References EINA_FALSE, EINA_MAIN_LOOP_CHECK_RETURN_VAL, eo_data_scope_get(), eo_isa(), and ERR.

## ◆ ecore_exe_close_stdin()

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

References EINA_MAIN_LOOP_CHECK_RETURN, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_auto_limits_set()

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.

References EINA_MAIN_LOOP_CHECK_RETURN, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_event_data_get()

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.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_event_data_free()

void ecore_exe_event_data_free | ( | Ecore_Exe_Event_Data * | data | ) |

Frees the given event data.

Parameters

  data | The given event data.

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

Referenced by ecore_exe_hup().

## ◆ ecore_exe_free()

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.

Examples:
  ecore_exe_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, eo_data_scope_get(), eo_del(), and eo_isa().

Referenced by ecore_exe_hup().

## ◆ ecore_exe_pid_get()

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.

Examples:
  ecore_exe_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_tag_set()

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.

References EINA_MAIN_LOOP_CHECK_RETURN, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_tag_get()

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`.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_cmd_get()

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.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ◆ ecore_exe_data_get()

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

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_data_set()

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
  1.1

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_flags_get()

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`.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_pause()

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.

## ◆ ecore_exe_continue()

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.

## ◆ ecore_exe_interrupt()

void ecore_exe_interrupt | ( | Ecore_Exe * | exe | ) |

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

Parameters

  exe | Process handle to the given process.

References EINA_MAIN_LOOP_CHECK_RETURN, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_quit()

void ecore_exe_quit | ( | Ecore_Exe * | exe | ) |

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

Parameters

  exe | Process handle to the given process.

References EINA_MAIN_LOOP_CHECK_RETURN, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_terminate()

void ecore_exe_terminate | ( | Ecore_Exe * | exe | ) |

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

Parameters

  exe | Process handle to the given process.

References EINA_MAIN_LOOP_CHECK_RETURN, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_kill()

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.

References EINA_MAIN_LOOP_CHECK_RETURN, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_signal()

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.

References EINA_MAIN_LOOP_CHECK_RETURN, eo_data_scope_get(), and eo_isa().

## ◆ ecore_exe_hup()

void ecore_exe_hup | ( | Ecore_Exe * | exe | ) |

Sends a `SIGHUP` signal to the given spawned process.

Parameters

  exe | Process handle to the given process.

References ecore_event_type_new(), ECORE_EXE_EVENT_ADD, ECORE_EXE_EVENT_DATA, ecore_exe_event_data_free(), ECORE_EXE_EVENT_DEL, ECORE_EXE_EVENT_ERROR, ecore_exe_free(), EINA_LIST_FOREACH, EINA_LIST_FOREACH_SAFE, EINA_MAIN_LOOP_CHECK_RETURN, EINA_UNUSED, eo_data_scope_get(), eo_isa(), and _Ecore_Exe_Event_Del::exe.

## 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).

Referenced by ecore_exe_hup().

## ◆ ECORE_EXE_EVENT_DATA

int ECORE_EXE_EVENT_DATA

Data from a child process.

Examples:
  ecore_exe_example.c.

Referenced by ecore_exe_hup().

## ◆ ECORE_EXE_EVENT_ERROR

int ECORE_EXE_EVENT_ERROR

Errors from a child process.

Referenced by ecore_exe_hup().