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

Collaboration diagram for Subprocess Management:

Files
file	process.h

Macros
#define	ERROR_PROCESS_ABORTED 1067L

Enumerations
enum	bu_process_io_t { BU_PROCESS_STDIN , BU_PROCESS_STDOUT , BU_PROCESS_STDERR }

enum	bu_process_create_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. More...

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

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

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

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

int	bu_process_pending (int fd)
	determine whether there is data pending on fd More...

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

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

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

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

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

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

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

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

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

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

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

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 56 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 42 of file process.h.

◆ bu_process_create_opts

enum bu_process_create_opts

Enumerator
BU_PROCESS_DEFAULT
BU_PROCESS_OUT_EQ_ERR
BU_PROCESS_HIDE_WINDOW

Definition at line 48 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
	)

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
	)

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_create_opts

Note: does not guarantee child process started successfully. use bu_process_wait() to check exit status

◆ bu_process_wait()

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.

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
	)

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 )

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 )

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
	)

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
	)

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
	)

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
	)

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
	)

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
	)

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 )

Return the process ID of the calling process.

Returns: process ID

Deprecated:: use bu_pid instead

◆ bu_pid()

int bu_pid ( void )

Return the process ID of the calling process.

Returns: process ID

◆ bu_pid_alive()

int bu_pid_alive ( int pid )

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 )

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 )

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 )

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

Returns: 1 if interactive, else 0

Files

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ERROR_PROCESS_ABORTED

Enumeration Type Documentation

◆ bu_process_io_t

◆ bu_process_create_opts

Function Documentation

◆ bu_process_exec()

◆ bu_process_create()

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