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
DEPRECATED void	bu_process_exec (struct bu_process *info, const char cmd, int argc, const char **argv, int out_eql_err, int hide_window)
	Wrapper for executing a sub-process.

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.

DEPRECATED int	bu_process_wait (int aborted, 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_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_pending (int fd)
	determine whether there is data pending on fd

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

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.

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

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.

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

void	bu_process_file_close (struct bu_process *pinfo, bu_process_io_t d)
	Close any FILE pointers internally opened via bu_process_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.

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

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

DEPRECATED int	bu_process_id (void)
	Return the process ID of the calling process.

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

DEPRECATED int	bu_terminate (int process)
	terminate a given process and any children.

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

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

Wrapper for executing a sub-process.

Deprecated:: use bu_process_create() instead.

Note

Todo:: eliminate the last two options so all callers are not exposed to parameters not relevant to them.

◆ 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	- bu_process struct to be created
[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: does not guarantee child process started successfully. use bu_process_wait() to check 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()

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

extern

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

Deprecated:: use bu_process_wait_n instead.

Note

Todo:: 'aborted' argument may be unnecessary (could make function provide return value of the process waited for). wtime undocumented.

◆ 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]	pinfo	- bu_process structure of interest
[in]	wtime	- maximum wait time (in ms) before forcibly stopping process. NOTE: 0 is treated as INFINITE

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

int bu_process_pending ( int fd )

extern

determine whether there is data pending on fd

Parameters

[in] fd - file descriptor of interest

Returns: 1 if there is data on fd, else 0

◆ bu_process_read()

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

extern

Read up to n bytes into buff from a process's specified output channel (fd == 1 for output, fd == 2 for err).

Deprecated:: use bu_process_read_n instead

Note

Todo:: arg ordering and input/output grouping is wrong. partially redundant with bu_process_fd() and/or bu_process_open().

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

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

extern

Open and return a FILE pointer associated with the specified file descriptor for input (0), output (1), or error (2) respectively.

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

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

Todo:: misnomer, this does not open a process. Probably doesn't need to exist; just call fdopen().

Deprecated:: use bu_process_file_open instead.

◆ 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_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_close()

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

extern

Close any FILE pointers internally opened via bu_process_open().

Todo:: misnomer, this does not close a process. Probably doesn't need to exist; just call fclose().

Deprecated:: use bu_process_file_close instead.

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

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

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

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

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

Deprecated:: use bu_process_args_n instead

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

DEPRECATED int bu_process_id ( void )

extern

Return the process ID of the calling process.

Returns: process ID

Deprecated:: use bu_pid instead

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

DEPRECATED int bu_terminate ( int process )

extern

terminate a given process and any children.

returns truthfully whether the process could be killed.

Deprecated:: use bu_pid_terminate instead

◆ 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

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

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

◆ bu_process_create()

◆ bu_process_func()

◆ bu_process_wait()

◆ bu_process_wait_n()

◆ bu_process_alive()

◆ bu_process_pending()

◆ bu_process_read()

◆ bu_process_read_n()

◆ bu_process_open()

◆ bu_process_file_open()

◆ bu_process_close()

◆ bu_process_file_close()

◆ bu_process_fileno()

◆ bu_process_pid()

◆ bu_process_args()

◆ bu_process_args_n()

◆ bu_process_id()

◆ bu_pid()

◆ bu_pid_alive()

◆ bu_terminate()

◆ bu_pid_terminate()

◆ bu_interactive()