Routines for launching and managing applications as subprocesses. More...

Collaboration diagram for Subprocess Management:

Files
file	process.h

Data Structures
struct	bu_process_func_info

Macros
#define	ERROR_PROCESS_ABORTED 1067L

Typedefs
typedef int(*	bu_process_func_t) (void *data)

Enumerations
enum	bu_process_io_t { BU_PROCESS_STDIN , BU_PROCESS_STDOUT , BU_PROCESS_STDERR }

enum	bu_process_opts { BU_PROCESS_DEFAULT = 0x0 , BU_PROCESS_OUT_EQ_ERR = 0x1 , BU_PROCESS_HIDE_WINDOW = 0x2 }

Functions
void	bu_process_create (struct bu_process pinfo, const char argv, int process_creation_opts)
	Wrapper for creating a sub-process. Allocates bu_process and starts process.

int	bu_process_func (struct bu_process_func_info info, bu_process_func_t func, void data, int timeout_ms, int flags)
	Run a callback in a subprocess and wait for it to complete.

int	bu_process_wait_n (struct bu_process **pinfo, int wtime)
	wait for a sub-process to complete, release all process allocations, and release the process itself.

int	bu_process_alive (struct bu_process *pinfo)
	determine whether process is still running

int	bu_process_poll (struct bu_process pinfo, int exit_status)
	Poll a subprocess without blocking or releasing its resources.

int	bu_process_terminate (struct bu_process *pinfo)
	Forcefully terminate a subprocess and its descendants.

int	bu_process_pending (int fd)
	Check a process descriptor for readable data without blocking.

int	bu_process_read_n (struct bu_process pinfo, bu_process_io_t d, int n, char buff)
	Read from a process's specified output channel.

FILE *	bu_process_file_open (struct bu_process *pinfo, bu_process_io_t d)
	Open and return a FILE pointer associated with the specified channel.

void	bu_process_file_close (struct bu_process *pinfo, bu_process_io_t d)
	Close any FILE pointers internally opened via bu_process_file_open().

int	bu_process_fileno (struct bu_process *pinfo, bu_process_io_t d)
	Retrieve the file descriptor to the I/O channel associated with the process.

int	bu_process_pid (struct bu_process *pinfo)
	Return the pid of the subprocess.

int	bu_process_args_n (struct bu_process pinfo, const char cmd, const char const **argv)

int	bu_pid (void)
	Return the process ID of the calling process.

int	bu_pid_alive (int pid)
	determine whether process is still running using its ID

int	bu_pid_terminate (int pid)
	terminate a given process and any children.

int	bu_interactive (void)
	detect whether or not a program is being run in interactive mode

Deprecated process APIs
DEPRECATED void	bu_process_exec (struct bu_process *info, const char cmd, int argc, const char **argv, int out_eql_err, int hide_window)

DEPRECATED int	bu_process_wait (int aborted, struct bu_process pinfo, int wtime)

DEPRECATED int	bu_process_read (char buff, int count, struct bu_process *pinfo, bu_process_io_t d, int n)

DEPRECATED FILE *	bu_process_open (struct bu_process *pinfo, bu_process_io_t d)

DEPRECATED void	bu_process_close (struct bu_process *pinfo, bu_process_io_t d)

DEPRECATED int	bu_process_args (const char *cmd, const char const *argv, struct bu_process pinfo)

DEPRECATED int	bu_process_id (void)

DEPRECATED int	bu_terminate (int process)

Detailed Description

Routines for launching and managing applications as subprocesses.

Routines for process and sub-process management.

Macro Definition Documentation

◆ ERROR_PROCESS_ABORTED

#define ERROR_PROCESS_ABORTED 1067L

Definition at line 57 of file process.h.

Typedef Documentation

◆ bu_process_func_t

typedef int(* bu_process_func_t) (void *data)

Callback type used by bu_process_func().

The callback runs in a subprocess. On POSIX platforms this is implemented using fork(), so the callback should restrict itself to fork-safe operations.

Parameters

[in] data - opaque pointer supplied to bu_process_func()

Returns: integer exit status for the subprocess

Definition at line 72 of file process.h.

Enumeration Type Documentation

◆ bu_process_io_t

enum bu_process_io_t

Enumerator
BU_PROCESS_STDIN
BU_PROCESS_STDOUT
BU_PROCESS_STDERR

Definition at line 43 of file process.h.

◆ bu_process_opts

enum bu_process_opts

Enumerator
BU_PROCESS_DEFAULT
BU_PROCESS_OUT_EQ_ERR
BU_PROCESS_HIDE_WINDOW

Definition at line 49 of file process.h.

Function Documentation

◆ bu_process_create()

void bu_process_create	(	struct bu_process **	pinfo,
		const char **	argv,
		int	process_creation_opts
	)

extern

Wrapper for creating a sub-process. Allocates bu_process and starts process.

Parameters

[out]	pinfo	- newly allocated process handle, or NULL if setup fails
[in]	argv	- array of command line arguments to executed. Last element MUST be NULL
[in]	process_creation_opts	- bit field for bu_process_opts

Note: Process creation does not guarantee the child started successfully. Use bu_process_wait_n() to check its exit status.

◆ bu_process_func()

int bu_process_func	(	struct bu_process_func_info *	info,
		bu_process_func_t	func,
		void *	data,
		int	timeout_ms,
		int	flags
	)

extern

Run a callback in a subprocess and wait for it to complete.

The callback runs in an isolated child process. On POSIX platforms this is implemented using fork(), so the callback should limit itself to fork-safe operations and communicate results back to the parent via its return code and any captured output.

If info is non-NULL, the status fields are populated on return. If info->out and/or info->err are non-NULL, those initialized bu_vls buffers are truncated and filled with captured child output. When BU_PROCESS_OUT_EQ_ERR is supplied, stderr is merged into the stdout capture buffer; if no stdout buffer is supplied, the merged stream is captured in info->err when available.

Parameters

[in,out]	info	- status record and optional capture buffers. May be NULL
[in]	func	- callback to run in the subprocess
[in]	data	- opaque pointer supplied to func
[in]	timeout_ms	- maximum wait time in milliseconds before forcibly stopping the subprocess. A value of 0 waits indefinitely
[in]	flags	- subprocess behavior flags. BU_PROCESS_OUT_EQ_ERR is currently supported; on non-POSIX platforms this API is not yet supported

Returns: callback return code if the subprocess exits normally; ERROR_PROCESS_ABORTED if it is terminated by a signal or times out; -1 on setup failure or unsupported platforms

◆ bu_process_wait_n()

int bu_process_wait_n	(	struct bu_process **	pinfo,
		int	wtime
	)

extern

wait for a sub-process to complete, release all process allocations, and release the process itself.

Parameters

[in,out]	pinfo	- address of the process handle; set to NULL on return
[in]	wtime	- maximum wait time (in ms) before forcibly stopping the process. A value of 0 waits indefinitely

Returns: 0 on success; ERROR_PROCESS_ABORTED for aborted process; Otherwise, platform specific exit status

◆ bu_process_alive()

int bu_process_alive ( struct bu_process * pinfo )

extern

determine whether process is still running

Parameters

[in] pinfo - bu_process structure of interest

Returns: 1 if alive, else 0

◆ bu_process_poll()

int bu_process_poll	(	struct bu_process *	pinfo,
		int *	exit_status
	)

extern

Poll a subprocess without blocking or releasing its resources.

Unlike bu_process_alive(), this routine also reports and preserves the subprocess exit status for a later bu_process_wait_n() call. Completion does not imply that all subprocess output has been read; callers may continue reading the process channels before releasing the process with bu_process_wait_n().

Parameters

[in]	pinfo	- bu_process structure of interest
[out]	exit_status	- subprocess exit status when complete; may be NULL

Returns: 1 if the subprocess has completed; 0 if it is still running; -1 on error

◆ bu_process_terminate()

int bu_process_terminate ( struct bu_process * pinfo )

extern

Forcefully terminate a subprocess and its descendants.

The subprocess remains available to bu_process_poll() and bu_process_wait_n() so callers can drain output and reap resources.

Parameters

[in] pinfo - bu_process structure of interest

Returns: non-zero if the process was already complete or termination was requested successfully; zero on error

◆ bu_process_pending()

int bu_process_pending ( int fd )

extern

Check a process descriptor for readable data without blocking.

This is a readiness hint. A zero result does not distinguish between no data, EOF, and an invalid descriptor or other error. Use bu_process_poll() to detect completion, perform any final reads, and then call bu_process_wait_n() to release the process.

Parameters

[in] fd - file descriptor of interest

Returns: 1 if a read can be attempted without blocking; otherwise 0

◆ bu_process_read_n()

int bu_process_read_n	(	struct bu_process *	pinfo,
		bu_process_io_t	d,
		int	n,
		char *	buff
	)

extern

Read from a process's specified output channel.

Parameters

[in]	pinfo	- bu_process structure of interest
[in]	d	- channel (BU_PROCESS_STDOUT, BU_PROCESS_STDERR)
[in]	n	- max number of bytes to be read
[out]	buff	- data read from channel

Returns: returns the number of bytes read into buff; 0 if read is at EOF; -1 on error

Note: the returned number of bytes read may be less than 'n' in a successful read.

◆ bu_process_file_open()

FILE * bu_process_file_open	(	struct bu_process *	pinfo,
		bu_process_io_t	d
	)

extern

Open and return a FILE pointer associated with the specified channel.

Input will be opened write, output and error will be opened read.

Caller should not close these FILE pointers directly. Call bu_process_file_close() instead.

Parameters

[in]	pinfo	- bu_process structure of interest
[in]	d	- channel (BU_PROCESS_STDIN, BU_PROCESS_STDOUT, BU_PROCESS_STDERR)

Returns: FILE pointer for specified channel

◆ bu_process_file_close()

void bu_process_file_close	(	struct bu_process *	pinfo,
		bu_process_io_t	d
	)

extern

Close any FILE pointers internally opened via bu_process_file_open().

Parameters

[in]	pinfo	- bu_process structure of interest
[in]	d	- channel (BU_PROCESS_STDIN, BU_PROCESS_STDOUT, BU_PROCESS_STDERR)

◆ bu_process_fileno()

int bu_process_fileno	(	struct bu_process *	pinfo,
		bu_process_io_t	d
	)

Retrieve the file descriptor to the I/O channel associated with the process.

Parameters

[in]	pinfo	- bu_process structure of interest
[in]	d	- channel (BU_PROCESS_STDIN, BU_PROCESS_STDOUT, BU_PROCESS_STDERR)

Returns: file descriptor

Note: For Windows cases where HANDLE is needed, use _get_osfhandle

◆ bu_process_pid()

int bu_process_pid ( struct bu_process * pinfo )

Return the pid of the subprocess.

Parameters

[in] pinfo - bu_process structure of interest

Returns: process ID

◆ bu_process_args_n()

int bu_process_args_n	(	struct bu_process *	pinfo,
		const char **	cmd,
		const char const *	argv
	)

Reports one or both of the command string and the argv array used to execute the process.

The bu_process container owns all strings for both cmd and argv - for the caller they are read-only.

If either cmd or argv are NULL they will be skipped - if the caller only wants one of these outputs the other argument can be set to NULL.

Parameters

[in]	pinfo	- the bu_process structure of interest
[out]	cmd	- pointer to the cmd string used to launch pinfo
[out]	argv	- pointer to the argv array used to launch pinfo

Returns: the corresponding argc count for pinfo's argv array.

◆ bu_pid()

int bu_pid ( void )

extern

Return the process ID of the calling process.

Returns: process ID

◆ bu_pid_alive()

int bu_pid_alive ( int pid )

extern

determine whether process is still running using its ID

Parameters

[in] pid - process ID of interest

Returns: 1 if alive, else 0

◆ bu_pid_terminate()

int bu_pid_terminate ( int pid )

extern

terminate a given process and any children.

Parameters

[in] pid - process ID of interest

Returns: returns truthfully whether the process could be killed

◆ bu_interactive()

int bu_interactive ( void )

extern

detect whether or not a program is being run in interactive mode

Returns: 1 if interactive, else 0

◆ bu_process_exec()

DEPRECATED void bu_process_exec	(	struct bu_process **	info,
		const char *	cmd,
		int	argc,
		const char **	argv,
		int	out_eql_err,
		int	hide_window
	)

extern

Deprecated:: Use bu_process_create().

◆ bu_process_wait()

DEPRECATED int bu_process_wait	(	int *	aborted,
		struct bu_process *	pinfo,
		int	wtime
	)

extern

Deprecated:: Use bu_process_wait_n().

◆ bu_process_read()

DEPRECATED int bu_process_read	(	char *	buff,
		int *	count,
		struct bu_process *	pinfo,
		bu_process_io_t	d,
		int	n
	)

extern

Deprecated:: Use bu_process_read_n().

◆ bu_process_open()

DEPRECATED FILE * bu_process_open	(	struct bu_process *	pinfo,
		bu_process_io_t	d
	)

extern

Deprecated:: Use bu_process_file_open().

◆ bu_process_close()

DEPRECATED void bu_process_close	(	struct bu_process *	pinfo,
		bu_process_io_t	d
	)

extern

Deprecated:: Use bu_process_file_close().

◆ bu_process_args()

DEPRECATED int bu_process_args	(	const char **	cmd,
		const char const *	argv,
		struct bu_process *	pinfo
	)

Deprecated:: Use bu_process_args_n().

◆ bu_process_id()

DEPRECATED int bu_process_id ( void )

extern

Deprecated:: Use bu_pid().

◆ bu_terminate()

DEPRECATED int bu_terminate ( int process )

extern

Deprecated:: Use bu_pid_terminate().

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Deprecated process APIs

Detailed Description

Macro Definition Documentation

◆ ERROR_PROCESS_ABORTED

Typedef Documentation

◆ bu_process_func_t

Enumeration Type Documentation

◆ bu_process_io_t

◆ bu_process_opts

Function Documentation

◆ bu_process_create()

◆ bu_process_func()

◆ bu_process_wait_n()

◆ bu_process_alive()

◆ bu_process_poll()

◆ bu_process_terminate()

◆ bu_process_pending()

◆ bu_process_read_n()

◆ bu_process_file_open()

◆ bu_process_file_close()

◆ bu_process_fileno()

◆ bu_process_pid()

◆ bu_process_args_n()

◆ bu_pid()

◆ bu_pid_alive()

◆ bu_pid_terminate()

◆ bu_interactive()

◆ bu_process_exec()

◆ bu_process_wait()

◆ bu_process_read()

◆ bu_process_open()

◆ bu_process_close()

◆ bu_process_args()

◆ bu_process_id()

◆ bu_terminate()