BRL-CAD
Loading...
Searching...
No Matches
process.h
Go to the documentation of this file.
1/* P R O C E S S . H
2 * BRL-CAD
3 *
4 * Copyright (c) 2004-2025 United States Government as represented by
5 * the U.S. Army Research Laboratory.
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public License
9 * version 2.1 as published by the Free Software Foundation.
10 *
11 * This library is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this file; see the file named COPYING for more
18 * information.
19 */
20
21#ifndef BU_PROCESS_H
22#define BU_PROCESS_H
23
24#include "common.h"
25
26#include <stdio.h> /* FILE */
27#include "bu/defines.h"
28
30
31/** @addtogroup bu_process
32 *
33 * @brief
34 * Routines for process and sub-process management.
35 */
36/** @{ */
37/** @file bu/process.h */
38
39/* Wrappers for using subprocess execution */
40struct bu_process;
41
47
48typedef enum {
49 BU_PROCESS_DEFAULT = 0x0, // default creation: equiv to (bu_process_create_opts)0
50 BU_PROCESS_OUT_EQ_ERR = 0x1, // stdout reads from stderr instead
51 BU_PROCESS_HIDE_WINDOW = 0x2, // (Windows only)hide creation window if process would normally spawn one
53
54#ifndef ERROR_PROCESS_ABORTED
55// have a consistent 'aborted' return code on cross-platforms
56#define ERROR_PROCESS_ABORTED 1067L
57#endif
58
59/**
60 * @brief Wrapper for executing a sub-process
61 *
62 * @deprecated use bu_process_create() instead.
63 *
64 * @note FIXME: eliminate the last two options so all callers are not
65 * exposed to parameters not relevant to them.
66 */
67DEPRECATED BU_EXPORT extern void bu_process_exec(struct bu_process **info, const char *cmd, int argc, const char **argv, int out_eql_err, int hide_window);
68/**
69 * @brief Wrapper for creating a sub-process. Allocates bu_process and starts process
70 *
71 * @param[out] pinfo - bu_process struct to be created
72 * @param[in] argv - array of command line arguments to executed. Last element MUST be NULL
73 * @param[in] process_creation_opts - bit field for bu_process_create_opts
74 *
75 * @note
76 * does not guarantee child process started successfully. use bu_process_wait() to check exit status
77 */
78BU_EXPORT extern void bu_process_create(struct bu_process **pinfo, const char **argv, int process_creation_opts);
80
81/**
82 * @brief wait for a sub-process to complete, release all process
83 * allocations, and release the process itself.
84 *
85 * @deprecated use bu_process_wait_n instead.
86 *
87 * @note FIXME: 'aborted' argument may be unnecessary (could make function
88 * provide return value of the process waited for). wtime
89 * undocumented.
90 */
91 DEPRECATED BU_EXPORT extern int bu_process_wait(int *aborted, struct bu_process *pinfo, int wtime);
92/**
93 * @brief wait for a sub-process to complete, release all process
94 * allocations, and release the process itself.
95 *
96 * @param[in] pinfo - bu_process structure of interest
97 * @param[in] wtime - maximum wait time (in ms) before forcibly stopping process. NOTE: 0 is treated as INFINITE
98 *
99 * @return
100 * 0 on success; ERROR_PROCESS_ABORTED for aborted process; Otherwise, platform specific exit status
101 */
102 BU_EXPORT extern int bu_process_wait_n(struct bu_process **pinfo, int wtime);
103
105/**
106 * @brief determine whether process is still running
107 *
108 * @param[in] pinfo - bu_process structure of interest
109 *
110 * @return
111 * 1 if alive, else 0
112 */
113BU_EXPORT extern int bu_process_alive(struct bu_process* pinfo);
114
116/**
117 * @brief determine whether there is data pending on fd
118 *
119 * @param[in] fd - file descriptor of interest
120 *
121 * @return
122 * 1 if there is data on fd, else 0
123 */
124BU_EXPORT extern int bu_process_pending(int fd);
125
127/**
128 * Read up to n bytes into buff from a process's specified output
129 * channel (fd == 1 for output, fd == 2 for err).
130 *
131 * @deprecated use bu_process_read_n instead
132 *
133 * @note FIXME: arg ordering and input/output grouping is wrong. partially
134 * redundant with bu_process_fd() and/or bu_process_open().
135 */
136DEPRECATED BU_EXPORT extern int bu_process_read(char *buff, int *count, struct bu_process *pinfo, bu_process_io_t d, int n);
137/**
138 * @brief Read from a process's specified output channel
140 * @param[in] pinfo - bu_process structure of interest
141 * @param[in] d - channel (BU_PROCESS_STDOUT, BU_PROCESS_STDERR)
142 * @param[in] n - max number of bytes to be read
143 * @param[out] buff - data read from channel
144 *
145 * @return
146 * returns the number of bytes read into buff; 0 if read is at EOF; -1 on error
147 *
148 * @note the returned number of bytes read may be less than 'n'
149 * in a successful read.
150 */
151BU_EXPORT extern int bu_process_read_n(struct bu_process *pinfo, bu_process_io_t d, int n, char *buff);
152
153
154/**
155 * Open and return a FILE pointer associated with the specified file
156 * descriptor for input (0), output (1), or error (2) respectively.
157 *
158 * Input will be opened write, output and error will be opened
159 * read.
160 *
161 * Caller should not close these FILE pointers directly. Call
162 * bu_process_close() instead.
163 *
164 * FIXME: misnomer, this does not open a process. Probably doesn't
165 * need to exist; just call fdopen().
166 *
167 * @deprecated use bu_process_file_open instead.
168 */
169DEPRECATED BU_EXPORT extern FILE *bu_process_open(struct bu_process *pinfo, bu_process_io_t d);
170/**
171 * @brief Open and return a FILE pointer associated with the specified channel.
172 *
173 * Input will be opened write, output and error will be opened
174 * read.
175 *
176 * Caller should not close these FILE pointers directly. Call
177 * bu_process_close() instead.
178 *
179 * @param[in] pinfo - bu_process structure of interest
180 * @param[in] d - channel (BU_PROCESS_STDIN, BU_PROCESS_STDOUT, BU_PROCESS_STDERR)
181 *
182 * @return
183 * FILE pointer for specified channel
184 */
185BU_EXPORT extern FILE *bu_process_file_open(struct bu_process *pinfo, bu_process_io_t d);
186
187
188/**
189 * Close any FILE pointers internally opened via bu_process_open().
190 *
191 * FIXME: misnomer, this does not close a process. Probably doesn't
192 * need to exist; just call fclose().
193 *
194 * @deprecated use bu_process_file_close instead.
195 */
196DEPRECATED BU_EXPORT extern void bu_process_close(struct bu_process *pinfo, bu_process_io_t d);
197/**
198 * @brief Close any FILE pointers internally opened via bu_process_open().
199 *
200 * @param[in] pinfo - bu_process structure of interest
201 * @param[in] d - channel (BU_PROCESS_STDIN, BU_PROCESS_STDOUT, BU_PROCESS_STDERR)
202 */
203BU_EXPORT extern void bu_process_file_close(struct bu_process *pinfo, bu_process_io_t d);
204
205
206/**
207 * @brief Retrieve the file descriptor to the I/O channel associated with the process.
209 * @param[in] pinfo - bu_process structure of interest
210 * @param[in] d - channel (BU_PROCESS_STDIN, BU_PROCESS_STDOUT, BU_PROCESS_STDERR)
211 *
212 * @return
213 * file descriptor
214 *
215 * @note For Windows cases where HANDLE is needed, use _get_osfhandle
216 */
217BU_EXPORT int bu_process_fileno(struct bu_process *pinfo, bu_process_io_t d);
218
219
220/**
221 * @brief Return the pid of the subprocess.
223 * @param[in] pinfo - bu_process structure of interest
224 *
225 * @return
226 * process ID
227 */
228BU_EXPORT int bu_process_pid(struct bu_process *pinfo);
229
230
231/**
232 * Reports one or both of the command string and the argv array
233 * used to execute the process.
234 *
235 * The bu_process container owns all strings for both cmd and argv -
236 * for the caller they are read-only.
237 *
238 * If either cmd or argv are NULL they will be skipped - if the
239 * caller only wants one of these outputs the other argument can
240 * be set to NULL.
241 *
242 * @param[out] cmd - pointer to the cmd string used to launch pinfo
243 * @param[out] argv - pointer to the argv array used to launch pinfo
244 * @param[in] pinfo - the bu_process structure of interest
245 *
246 * @return
247 * the corresponding argc count for pinfo's argv array.
248 *
249 * @deprecated use bu_process_args_n instead
250 */
251DEPRECATED BU_EXPORT int bu_process_args(const char **cmd, const char * const **argv, struct bu_process *pinfo);
252/**
253 * Reports one or both of the command string and the argv array
254 * used to execute the process.
255 *
256 * The bu_process container owns all strings for both cmd and argv -
257 * for the caller they are read-only.
258 *
259 * If either cmd or argv are NULL they will be skipped - if the
260 * caller only wants one of these outputs the other argument can
261 * be set to NULL.
262 *
263 * @param[in] pinfo - the bu_process structure of interest
264 * @param[out] cmd - pointer to the cmd string used to launch pinfo
265 * @param[out] argv - pointer to the argv array used to launch pinfo
266 *
267 * @return
268 * the corresponding argc count for pinfo's argv array.
269 */
270BU_EXPORT int bu_process_args_n(struct bu_process *pinfo, const char **cmd, const char * const **argv);
271
272
273/**
274 * @brief Return the process ID of the calling process
276 * @return
277 * process ID
278 *
279 * @deprecated use bu_pid instead
280 */
281DEPRECATED BU_EXPORT extern int bu_process_id(void);
282/**
283 * @brief Return the process ID of the calling process
284 *
285 * @return
286 * process ID
287 */
288BU_EXPORT extern int bu_pid(void);
289
290
291/**
292 * @brief determine whether process is still running using its ID
294 * @param[in] pid - process ID of interest
295 *
296 * @return
297 * 1 if alive, else 0
298 */
299BU_EXPORT extern int bu_pid_alive(int pid);
300
301
302/**
303 * @brief terminate a given process and any children.
305 * returns truthfully whether the process could be killed.
306 *
307 * @deprecated use bu_pid_terminate instead
308 */
310/**
311 * @brief terminate a given process and any children.
312 *
313 * @param[in] pid - process ID of interest
315 * @return
316 * returns truthfully whether the process could be killed
317 */
318BU_EXPORT extern int bu_pid_terminate(int pid);
319
320
321/**
322 * @brief detect whether or not a program is being run in interactive mode
324 * @return
325 * 1 if interactive, else 0
326 */
327BU_EXPORT extern int bu_interactive(void);
328
329/** @} */
330
333#endif /* BU_PROCESS_H */
334
335/*
336 * Local Variables:
337 * mode: C
338 * tab-width: 8
339 * indent-tabs-mode: t
340 * c-file-style: "stroustrup"
341 * End:
342 * ex: shiftwidth=4 tabstop=8
343 */
Definition dvec.h:74
Header file for the BRL-CAD common definitions.
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_pending(int fd)
determine whether there is data pending on fd
int bu_interactive(void)
detect whether or not a program is being run in interactive mode
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.
DEPRECATED int bu_terminate(int process)
terminate a given process and any children.
DEPRECATED int bu_process_args(const char **cmd, const char *const **argv, struct bu_process *pinfo)
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.
int bu_pid_alive(int pid)
determine whether process is still running using its ID
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.
void bu_process_file_close(struct bu_process *pinfo, bu_process_io_t d)
Close any FILE pointers internally opened via bu_process_open().
bu_process_io_t
Definition process.h:42
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.
bu_process_create_opts
Definition process.h:48
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)
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
DEPRECATED void bu_process_close(struct bu_process *pinfo, bu_process_io_t d)
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_args_n(struct bu_process *pinfo, const char **cmd, const char *const **argv)
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.
int bu_pid_terminate(int pid)
terminate a given process and any children.
int bu_process_pid(struct bu_process *pinfo)
Return the pid of the subprocess.
@ BU_PROCESS_STDERR
Definition process.h:45
@ BU_PROCESS_STDIN
Definition process.h:43
@ BU_PROCESS_STDOUT
Definition process.h:44
@ BU_PROCESS_OUT_EQ_ERR
Definition process.h:50
@ BU_PROCESS_DEFAULT
Definition process.h:49
@ BU_PROCESS_HIDE_WINDOW
Definition process.h:51
void float float int * n
Definition tig.h:74
#define DEPRECATED
Definition common.h:401