Debian Codegraph @

gui/GraphLib/libsrc/uimxR5/include/UxSubproc.h

raw
1 /* @(#)UxSubproc.h 17.1 (ESO-IPG) 01/25/02 17:26:03 */
2 /*---------------------------------------------------------------------
3 * $Date: 2003-06-04 14:49:18 $ $Revision: 1.1.1.1 $
4 *---------------------------------------------------------------------
5 *
6 *
7 * Copyright (c) 1988, Visual Edge Software Ltd.
8 *
9 * ALL RIGHTS RESERVED. Permission to use, copy, modify, and
10 * distribute this software and its documentation for any purpose
11 * and without fee is hereby granted, provided that the above
12 * copyright notice appear in all copies and that both that
13 * copyright notice and this permission notice appear in supporting
14 * documentation, and that the name of Visual Edge Software not be
15 * used in advertising or publicity pertaining to distribution of
16 * the software without specific, written prior permission. The year
17 * included in the notice is the year of the creation of the work.
18 *-------------------------------------------------------------------*/
19
20 #ifndef UXSUBPROC_H
21 #define UXSUBPROC_H
22
23 /****************************************************************************
24 DESCRIPTION:
25 ============
26
27 Include File: "UxSubproc.h"
28 =============
29
30
31 Subprocess creation:
32 ====================
33
34 Syntax: handle UxCreateSubproc(process, defarg, functionptr)
35
36 Arguments: char *process - name of the command line based program
37 char *defarg - default arguments passed to the process
38 void (*functionptr) - function to be executed on output
39 from the process
40
41 Return Type: handle - UIMX key to the subprocess
42
43
44 Description: Creates a subprocess object and returns a key to it.
45 The process is not executed by this function.
46
47 See also: UxExecSubproc, UxRunSubproc, UxSetSubprocClosure,
48 UxSetSubprocFunction
49
50 -----
51
52 Syntax: int UxSetSubprocEcho(subproc, echo)
53
54 Arguments: handle subproc - handle of the subprocess
55 int echo - flag whether echo is on or off
56
57 Return Type: -1 on error
58 0 otherwise
59
60 Description: Set whether command lines are echoed by the subprocess.
61 The default for this is off (0). It would typically not
62 be set unless the application being built with UIMX acts
63 as a terminal emulator in ful duplex mode.
64 This function must be called before the subprocess is
65 executed with either UxExecSubproc or UxRunSubproc, for
66 it to have any effect.
67
68 Subprocess execution:
69 =====================
70
71 Syntax: int UxRunSubproc(vh, arg)
72 int UxExecSubproc(vh, arg)
73
74 Arguments: handle vh - key returned by UxCreateSubproc
75 char *arg - argument to the subprocess
76 if arg is NULL, the default argument set
77 by UxCreateSubproc is used.
78
79 Return Type: -1 on error
80 0 otherwise
81
82 Description: Both functions execute the child process created with
83 UxCreateSubproc, UxRunSubproc and UxExecSubproc. The
84 functions differ only on repeated execution. UxRunSubproc
85 returns an error if the subprocess is still running whereas
86 UxExecSubproc terminates the running process and executes
87 it again.
88
89 See also: UxCreateSubproc, UxSetSubprocClosure, UxSetSubprocFunction
90
91
92
93 Setting the Subprocess output function:
94 =======================================
95
96 Syntax: int UxSetSubprocFunction(vh, fnt)
97
98 Arguments: handle vh - key returned by UxCreateSubproc
99 void (*fnt)() - function ptr that handles the output
100 from the subprocess
101 Return Type: -1 on error
102 0 otherwise
103
104 Description: Overrides the function pointer passed to UxCreateSubproc.
105 This function allows the user to change the output
106 handling of the subprocess during execution of the program.
107
108 See also: UxCreateSubproc, UxSetSubprocClosure and output function format.
109
110
111 Setting the Subprocess output function:
112 =======================================
113
114 Syntax: int UxSetSubprocClosure(vh, data)
115
116 Arguments: handle vh - key returned by UxCreateSubproc
117 char *data - Data passed to the output function.
118
119 Return Type: -1 on error
120 0 otherwise
121
122 Description: Sets the data passed to the output function of the subprocess.
123
124 See also: UxCreateSubproc, UxSetSubprocFunction and output function
125 format.
126
127
128 Sending commands to the Subprocess:
129 ===================================
130
131 Syntax: int UxSendSubproc(vh, command)
132
133 Arguments: handle vh - key returned by UxCreateSubproc
134 char *command - String send to the subprocess
135
136 Return Type: -1 on error
137 0 otherwise
138
139 Description: Sends the command string to the subprocess. A carriage
140 return is automatically appended to the command string.
141
142
143 -----
144
145 Syntax: int UxSendSubprocNoCR(vh, command)
146
147 Arguments: handle vh - key returned by UxCreateSubproc
148 char *command - String send to the subprocess
149
150 Return Type: -1 on error
151 0 otherwise
152
153 Description: Sends the command string to the subprocess. No carriage
154 return is appended to the command string.
155
156
157 Terminating a running Subprocess:
158 =================================
159
160 Syntax: int UxExitSubproc(vh)
161
162 Arguments: handle vh - key returned by UxCreateSubproc
163
164 Return Type: -1 on error
165 0 otherwise
166
167 Description: Terminates a running subprocess
168
169 See also: UxCreateSubproc, UxExecSubproc and UxRunSubproc
170
171
172 Getting the process id of a Subprocess:
173 =======================================
174
175 Syntax: int UxGetSubprocPid(vh)
176
177 Arguments: handle vh - key returned by UxCreateSubproc
178
179 Return Type: Process id of the running process
180 0 otherwise
181
182 Description: Checks if a process is still running and returns the
183 process id of it. If the process was improperly
184 terminated, it performs error checking and closes
185 open file descriptors associated with the running
186 process.
187
188 See also: UxExitSubproc
189
190
191 Destroying a Subprocess:
192 ========================
193
194 Syntax: int UxDeleteSubproc (vh)
195
196
197 Arguments: handle vh - key returned by UxCreateSubproc
198
199 Return type: ERROR/NO_ERROR
200
201
202 Description: Destroys the subprocess information,
203 after calling UxExitSuproc to terminate the process.
204 After a call to this function, the handle vh
205 no longer identifies a valid subprocess.
206
207 See also: UxCreateSubproc, UxExitSubproc, UxDelayedDeleteSubproc.
208
209
210 Delayed Destruction of a Subprocess:
211 ====================================
212
213 Syntax: int UxDelayedDeleteSubproc (vh)
214
215
216 Arguments: handle vh - key returned by UxCreateSubproc
217
218 Return type: ERROR/NO_ERROR
219
220
221 Description: Delayed destruction of the subprocess information.
222 Deletion actually takes place the next time this
223 function is called. This is useful in cases
224 where you want to delete the data associated
225 with the subprocess from the subprocess exit
226 callback.
227
228 See also: UxCreateSubproc, UxExitSubproc, UxDeleteSubproc.
229
230
231 Format of the Subprocess output function:
232 =========================================
233
234 Syntax: void USER_FUNCTION(fd, data)
235
236 Arguments: int fd - file descriptor with output from the
237 subprocess
238 char *data - data set with UxSetSubprocClosure
239
240 Description: When data is returned from the subprocess, the
241 function set with UxSetSubprocFunction is executed.
242
243
244 See also: UxSetSubprocFunction and UxSetSubprocClosure
245
246
247 User utility functions:
248 =======================
249
250 Syntax: void UxAppendTo(fd, wid)
251
252 Arguments: int fd - file descriptor with output from the
253 subprocess
254 Widget wid - data set with UxSetSubprocClosure
255
256 Description: When data is returned from the subprocess with the
257 UxAppendTo as output function, it attempts to append
258 data to the text widget passed in as data. If wid is
259 NULL, the output is printed to stdout.
260
261
262 See also: UxCreateSubproc, UxSetSubprocFunction and UxSetSubprocClosure
263
264
265
266
267 Syntax: char *UxTransferToBuffer(fd, status)
268
269 Arguments: int fd - file descriptor with output from the
270 subprocess
271 int *status - Filled in by UxTransferToBuffer.
272 0 if there is no more output data
273 1 if more output data is present
274
275 Return Type: char * - Null terminated ouput text string.
276 The buffer containing the text string
277 is a static text buffer of 512 bytes.
278
279 Description: Utility function to read blocks of data from the file
280 descriptor into a NULL terminated text buffer.
281
282
283 See also: UxCreateSubproc, UxSetSubprocFunction and UxSetSubprocClosure
284
285
286
287 CREATION: Jul 20 1988 Visual Edge Software
288 ---------------------------------------------------------------------------*/
289
290
291 /*--- include files ---*/
292 #include <X11/Intrinsic.h>
293 #include "uxproto.h"
294
295 #ifdef __cplusplus
296 extern "C" { /* C++ compatability */
297 #endif /* __cplusplus */
298
299 /*--- macro symbolic constants ---*/
300 #ifndef ERROR
301 #define ERROR -1
302 #endif
303 #ifndef NO_ERROR
304 #define NO_ERROR 0
305 #endif
306
307 #ifndef MSGMAX
308 # define MSGMAX 2048
309 #endif /*MSGMAX*/
310
311 /*--- macro functions ---*/
312
313 /*--- types ---*/
314 typedef int handle;
315
316 /*--- external functions ---*/
317 extern handle UxCreateSubproc UXPROTO((char *process, char *defarg, void (*fnt)UXPROTO((int, Widget))));
318 extern int UxExecSubproc UXPROTO((handle sp_vh, char *cmd_line));
319 extern int UxRunSubproc UXPROTO((handle sp_vh, char *cmd_line));
320 extern int UxGetSubprocPid UXPROTO((handle sp_vh));
321 extern int UxSendSubproc UXPROTO((handle sp_vh, char *tex));
322 extern int UxSendSubprocNoCR UXPROTO((handle sp_vh, char *tex));
323 extern int UxSetSubprocEcho UXPROTO((handle sp_vh, int echo));
324 extern int UxExitSubproc UXPROTO((handle sp_vh));
325 extern int UxSetSubprocClosure UXPROTO((handle sp_vh, char *data));
326 extern int UxSetSubprocFunction UXPROTO((handle sp_vh, void (*fnt)()));
327 extern int UxDeleteSubproc UXPROTO((handle index));
328 extern int UxDelayedDeleteSubproc UXPROTO((handle index));
329 extern int UxSetSubprocExitCallback UXPROTO((handle h, void (*fnt)()));
330 extern char *UxTransferToBuffer UXPROTO((int fd, int *status));
331 extern void UxAppendTo UXPROTO((int fd, Widget tw));
332
333 /*--- external variables ---*/
334
335
336 #ifdef __cplusplus
337 } /* Close scope of 'extern "C"' declaration which encloses file. */
338 #endif /* __cplusplus */
339
340 #endif
341