Start a process and perform I/O using stdin, stdout, and stderr

Functions
M_io_error_t	M_io_process_create (const char *command, M_list_str_t *args, M_hash_dict_t *env, M_uint64 timeout_ms, M_io_t **proc, M_io_t **proc_stdin, M_io_t **proc_stdout, M_io_t **proc_stderr)
M_bool	M_io_process_get_result_code (M_io_t *proc, int *result_code)
int	M_io_process_get_pid (M_io_t *proc)

Detailed Description

A process starts an executable and opens the processes communication endpoints of stdin, stdout, and stderr as unidirectional pipes for communicating with the process.

Function Documentation

M_io_process_create()

M_io_error_t M_io_process_create	(	const char *	command,
		M_list_str_t *	args,
		M_hash_dict_t *	env,
		M_uint64	timeout_ms,
		M_io_t **	proc,
		M_io_t **	proc_stdin,
		M_io_t **	proc_stdout,
		M_io_t **	proc_stderr
	)

Create a process and return IO handles for the process itself as well as unidirectional pipes for stdin, stdout, and stderr.

Validation will be performed on the command upon calling this function, but the process will not actually be started until the 'proc' returned value is associated with an event loop. It is possible that the process may fail to start due to system resource limitations or missing validations for system ACLs; an ERROR event will be delivered in such a case. Otherwise if the process is started successfully, a DISCONNECT will be triggered on exit regardless of the process exit code (unless the specified timeout is exceeded, then an ERROR) event will be triggered.

NOTE: If using stdin to pass data to the command, stdin MUST be closed once done to notify the remote process there is no more data or the process may hang indefinitely.

Parameters

[in]	command	Required. Command to execute. If an absolute path or relative path is not provided, will search the PATH environment variable, which can be overwritten in the 'env' parameter and honored. On Windows, the current working directory is also scanned as is common practice (but not on any other OS).
[in]	args	Optional. List of arguments to pass to command.
[in]	env	Optional. List of environment variables to pass on to process. Use NULL to pass current environment through.
[in]	timeout_ms	Optional. Maximum execution time of the process before it is forcibly terminated. Use 0 for infinite.
[out]	proc	Required. The io object handle for the process itself. Used to notify when the process has exited, or request termination of process.
[out]	proc_stdin	Optional. The io object handle for the write-only stdin process handle. If NULL is passed, will close handle to process. The stdin endpoint will not be notified when the process closes so it must be tracked and closed when the process exits by the caller.
[out]	proc_stdout	Optional. The io object handle for the read-only stdout process handle. If NULL is passed, will close handle to process.
[out]	proc_stderr	Optional. The io object handle for the read-only stderr process handle. If NULL is passed, will close handle to process.

Returns

M_IO_ERROR_SUCCESS on SUCCESS. Otherwise, M_IO_ERROR_INVALID on misuse, M_IO_ERROR_NOTFOUND if specified executable not found, M_IO_ERROR_NOTPERM if execution not permitted.

M_io_process_get_result_code()

M_bool M_io_process_get_result_code	(	M_io_t *	proc,
		int *	result_code
	)

Retrieve the result code of the process.

Parameters

[in]	proc	Proc IO object returned from M_io_process_create();
[out]	result_code	Exit code returned from process.

Returns

M_TRUE if process exited with a return code. M_FALSE if invalid request due to process state or other error.

M_io_process_get_pid()

int M_io_process_get_pid

(

M_io_t *

proc

)

Retrieve the OS Process ID of the process.

Parameters

[in]

proc

Proc IO object returned from M_io_process_create();

Returns

Return the process id of the process