Functions that deal with and send signals to spawned processes. 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 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 | |
EAPI void | ecore_exe_run_priority_set (int pri) |
Sets the priority at which to launch processes. | |
EAPI int | ecore_exe_run_priority_get (void) |
Gets the priority at which to launch processes. | |
EAPI Ecore_Exe * | ecore_exe_run (const char *exe_cmd, const void *data) |
Spawns a child process. | |
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. | |
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. | |
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. | |
EAPI void | ecore_exe_close_stdin (Ecore_Exe *exe) |
The stdin of the given child process will close when the write buffer is empty. | |
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. | |
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. | |
EAPI void | ecore_exe_event_data_free (Ecore_Exe_Event_Data *e) |
Frees the given event data. | |
EAPI void * | ecore_exe_free (Ecore_Exe *exe) |
Frees the given process handle. | |
EAPI pid_t | ecore_exe_pid_get (const Ecore_Exe *exe) |
Retrieves the process ID of the given spawned process. | |
EAPI void | ecore_exe_tag_set (Ecore_Exe *exe, const char *tag) |
Sets the string tag for the given process handle. | |
EAPI const char * | ecore_exe_tag_get (const Ecore_Exe *exe) |
Retrieves the tag attached to the given process handle. | |
EAPI const char * | ecore_exe_cmd_get (const Ecore_Exe *exe) |
Retrieves the command of the given spawned process. | |
EAPI void * | ecore_exe_data_get (const Ecore_Exe *exe) |
Retrieves the data attached to the given process handle. | |
EAPI void * | ecore_exe_data_set (Ecore_Exe *exe, void *data) |
Sets the data attached to the given process handle. | |
EAPI Ecore_Exe_Flags | ecore_exe_flags_get (const Ecore_Exe *exe) |
Retrieves the flags attached to the given process handle. | |
EAPI void | ecore_exe_pause (Ecore_Exe *exe) |
Pauses the given process by sending it a SIGSTOP signal. | |
EAPI void | ecore_exe_continue (Ecore_Exe *exe) |
Continues the given paused process by sending it a SIGCONT signal. | |
EAPI void | ecore_exe_interrupt (Ecore_Exe *exe) |
Sends the given spawned process a interrupt (SIGINT ) signal. | |
EAPI void | ecore_exe_quit (Ecore_Exe *exe) |
Sends the given spawned process a quit (SIGQUIT ) signal. | |
EAPI void | ecore_exe_terminate (Ecore_Exe *exe) |
Sends the given spawned process a terminate (SIGTERM ) signal. | |
EAPI void | ecore_exe_kill (Ecore_Exe *exe) |
Kills the given spawned process by sending it a SIGKILL signal. | |
EAPI void | ecore_exe_signal (Ecore_Exe *exe, int num) |
Sends a SIGUSR signal to the given spawned process. | |
EAPI void | ecore_exe_hup (Ecore_Exe *exe) |
Sends a SIGHUP signal to the given spawned process. |
Variables | |
EAPI int | ECORE_EXE_EVENT_ADD |
A child process has been added. | |
EAPI int | ECORE_EXE_EVENT_DEL |
A child process has been deleted (it exited, naming consistent with the rest of ecore). | |
EAPI int | ECORE_EXE_EVENT_DATA |
Data from a child process. | |
EAPI int | ECORE_EXE_EVENT_ERROR |
Errors from a child process. |
Detailed Description
Functions that deal with and send signals to spawned processes.
Enumeration Type Documentation
enum _Ecore_Exe_Flags |
Flags for executing a child with its stdin and/or stdout piped back.
- Enumerator:
Defines the priority of the proccess.
- Enumerator:
Function Documentation
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
-
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.
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
-
exe The child process to attach the pre_free function. func The function to call before exe is freed.
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
-
exe The child process
EAPI 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.
EAPI 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.
EAPI 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()
EAPI 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
EAPI void ecore_exe_event_data_free | ( | Ecore_Exe_Event_Data * | e | ) |
Frees the given event data.
- Parameters
-
e The given event data.
References _Ecore_Exe_Event_Data::data, and _Ecore_Exe_Event_Data::lines.
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
-
exe The given process handle. flags Is this a ECORE_EXE_PIPE_READ or ECORE_EXE_PIPE_ERROR?
- Returns
- The event data.
References _Ecore_Exe_Event_Data::data, ECORE_EXE_PIPE_ERROR, ECORE_EXE_PIPE_ERROR_LINE_BUFFERED, ECORE_EXE_PIPE_READ, ECORE_EXE_PIPE_READ_LINE_BUFFERED, _Ecore_Exe_Event_Data::exe, _Ecore_Exe_Event_Data::lines, and _Ecore_Exe_Event_Data::size.
EAPI 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
.
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
-
exe The given process handle.
- Returns
- The data attached to the handle when ecore_exe_run was called.
References ecore_main_fd_handler_del(), and ecore_timer_del().
Referenced by ecore_exe_pipe_run().
EAPI void ecore_exe_hup | ( | Ecore_Exe * | exe | ) |
Sends a SIGHUP
signal to the given spawned process.
- Parameters
-
exe Process handle to the given process.
EAPI void ecore_exe_interrupt | ( | Ecore_Exe * | exe | ) |
Sends the given spawned process a interrupt (SIGINT
) signal.
- Parameters
-
exe Process handle to the given process.
EAPI 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 ecore_timer_add(), and ecore_timer_del().
EAPI 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.
EAPI 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.
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_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.
References ecore_event_add(), ECORE_EXE_EVENT_ADD, ecore_exe_free(), ECORE_EXE_PIPE_AUTO, ECORE_EXE_PIPE_ERROR, ECORE_EXE_PIPE_READ, ECORE_EXE_PIPE_WRITE, ECORE_EXE_PRIORITY_INHERIT, ecore_exe_terminate(), ECORE_FD_READ, ECORE_FD_WRITE, ecore_main_fd_handler_active_set(), ecore_main_fd_handler_add(), and _Ecore_Exe_Event_Add::exe.
Referenced by ecore_exe_run().
EAPI void ecore_exe_quit | ( | Ecore_Exe * | exe | ) |
Sends the given spawned process a quit (SIGQUIT
) signal.
- Parameters
-
exe Process handle to the given process.
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()
- 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().
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()
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().
- 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.
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
-
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.
References ECORE_FD_WRITE, and ecore_main_fd_handler_active_set().
EAPI 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.
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
-
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 beNULL
.
EAPI 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.
EAPI void ecore_exe_terminate | ( | Ecore_Exe * | exe | ) |
Sends the given spawned process a terminate (SIGTERM
) signal.
- Parameters
-
exe Process handle to the given process.
Referenced by ecore_exe_pipe_run().
Variable Documentation
EAPI int ECORE_EXE_EVENT_DATA |
Data from a child process.
EAPI int ECORE_EXE_EVENT_DEL |
A child process has been deleted (it exited, naming consistent with the rest of ecore).
EAPI int ECORE_EXE_EVENT_ERROR |
Errors from a child process.