1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
|
<html><head><title>Acknowledgements</title></head>
<body>
<a name="495399"><CENTER><h1>Acknowledgements</h1></CENTER></a>
<hr><p><a name="495400">
A special acknowledgement is due to Lee Minner who helped with the socket and remote execution facility in PPC.<p>
</a>
<a name="495484">
<h1>1.0 </a>Introduction</h1>
</a>
<a name="495559">
The </a>Portable Process Control library (</a>PPC) is a set of routines to execute and communicate with other </a>processes in environments which permit such operations. The goal is to establish an easy to use interface which can be implemented on a wide variety of platforms. The </a>standard C library </a>I/O interface was taken as a model. In this view, processes are treated as much like files as is possible. In particular, a process is </a>opened and </a>closed as is a </a>file and that means that it is </a>forked by the </a>parent to start with and </a>killed at the end. While a process is open it may be written to and read from with PPC functions which are analogous to the standard C I/O functions </a>fprintf and </a>fgets. In addition, there are functions to monitor the </a>status of the </a>child processes. These do not have precise analogs to file routines, but since the basic interface has been established by the open/close and read/write routines, these have obvious usages.<p>
</a>
<a name="495537">
PPC is one part of PACT, Portable Application Code Toolkit. See the section </a>Other PACT Documentation at the end for more information about PACT.<p>
</a>
<a name="495497">
<h1>2.0 </a>PPC Model</h1>
</a>
<a name="495498">
This section describes the </a>interprocess communication (</a>IPC) model used in PPC and gives a high level overview of some of the key features of the library. Much of this discussion is involved with UNIX since that environment is one of the richest (and hence most confusing) environments for IPC. We believe that the concepts are fundamental and hence permit PPC to be ported to environments with different semantics. Also the prevalence of the </a>TCP/IP standard makes it a reasonable one to study in the context of distributed IPC.<p>
</a>
<a name="495499">
<h2>2.1 </a>Pipes, Sockets, and Pseudo Terminals</h2>
</a>
<a name="495500">
In UNIX environments there are three ways for processes to communicate that seem suitable for PPC. They are pipes, sockets, and pseudo terminals (</a>PTY’s). Although one might argue that for local processes there is no real advantage to using pipes over sockets or vice versa, PPC supports them both to guard against platforms where one or the other has some non-standard feature. By contrast, PTY’s have a crucial significance in that some programs with which a code may wish to communicate behave differently when talking to a terminal than they do when talking to a socket or pipe. FTP is a classic example of this phenomenon. Only sockets are available for remote processes.<p>
</a>
<a name="495501">
When an application opens a child process it must specify the IPC medium. In this way the application developer has control over how the parent and child communicate.<p>
</a>
<a name="495503">
<h2>2.2 </a>Interrupt Driven and Multiplexed I/O</h2>
</a>
<a name="495504">
When communicating with one or more child processes, an application is often in the position of having or wanting to get input from the terminal or one or more child processes. There are three ways that are commonly used to do this:<p>
</a>
<A NAME="495506"><PRE> </PRE>unblocking the input channels and polling in the application
<BR><A NAME="495507"><PRE> </PRE>using a </a>multiplex I/O system call (e.g. </a>select or </a>poll)
<BR><A NAME="495508"><PRE> </PRE>using interrupts on input channels
<BR><a name="495505">
PPC supports all three of these options.<p>
</a>
<a name="495524">
<h2>2.3 Remote File Access</h2>
</a>
<a name="495533">
Sometimes applications need to access files on remote systems which cannot be mounted via some standard mechanism such as NFS or AFS. Using the IPC machinery inherent in its design, PPC also supplies a facility to do I/O on remote files. The model here is in two parts.<p>
</a>
<a name="495541">
<h3>2.3.1 </a>File I/O Interface</h3>
</a>
<a name="495542">
SCORE defines the following set of function pointers:<p>
</a>
<A NAME="495543">io_open_hook default value fopen
<P><A NAME="495544">io_tell_hook default value ftell
<P><A NAME="495545">io_read_hook default value fread
<P><A NAME="495546">io_write_hook default value fwrite
<P><A NAME="495547">io_setvbuf_hook default value setvbuf
<P><A NAME="495548">io_close_hook default value fclose
<P><A NAME="495550">io_seek_hook default value fseek
<P><A NAME="495612">io_printf_hook default value fprintf
<P><A NAME="495618">io_puts_hook default value fputs
<P><A NAME="495619">io_getc_hook default value fgetc
<P><A NAME="495620">io_ungetc_hook default value ungetc
<P><A NAME="495621">io_flush_hook default value fflush
<P><A NAME="495622">io_gets_hook default value fgets
<P><a name="495623">
and macros<p>
</a>
<A NAME="495624">#define io_open (*io_open_hook)
<P><A NAME="495625">#define io_setvbuf (*io_setvbuf_hook)
<P><A NAME="495626">#define io_tell (*io_tell_hook)
<P><A NAME="495627">#define io_read (*io_read_hook)
<P><A NAME="495628">#define io_write (*io_write_hook)
<P><A NAME="495629">#define io_close (*io_close_hook)
<P><A NAME="495630">#define io_seek (*io_seek_hook)
<P><A NAME="495631">#define io_printf (*io_printf_hook)
<P><A NAME="495632">#define io_puts (*io_puts_hook)
<P><A NAME="495633">#define io_getc (*io_getc_hook)
<P><A NAME="495634">#define io_ungetc (*io_ungetc_hook)
<P><A NAME="495635">#define io_flush (*io_flush_hook)
<P><A NAME="495636">#define io_gets (*io_gets_hook)
<P><a name="495637">
These give a call compatible interface to the major portion of the standard C file I/O library. It also provides a simple way for an application to supply its own functions to make variations on the functionality. In particular, PPC supplies a set of functions to access files on remote hosts. The function </a>PC_io_connect toggles between the default set of functions and the remote access versions.<p>
</a>
<a name="495638">
<h3>2.3.2 File Access Server</h3>
</a>
<a name="495639">
The remote file access functions mentioned in the last section depend on a server running on the remote host. The utililty </a>pcexec is that server.<p>
</a>
<a name="495640">
When a request to open a file with a name using the syntax discussed in the section </a>PCEXEC indicates a file on a remote host, </a>pcexec is started on that host in server mode. It then handles all file access requests made by the other calls in the previous section. Any number of files can be managed per host per user. When the last file that the remote </a>pcexec session knows about is closed, </a>pcexec exits. NOTE: if your application crashes, there will most likely be an orphaned </a>pcexec running on the remote host and you will have to kill it yourself.<p>
</a>
<a name="495451">
<h2>2.4 </a>Communication Paths and PPC Routines</h2>
</a>
<a name="495496">
Use PPC routines </a>PC_printf and </a>PC_gets to communicate with child processes. Use C routines </a>fgets and </a>fprintf to communicate with parent processes.<img src="ppc5.doc.anc.gif"><p>
</a>
<a name="495398">
<h1>3.0 The PPC Library</h1>
</a>
<a name="495648">
This section describes the PPC library and related information necessary to use PPC in your applications.<p>
</a>
<a name="495515">
<h2>3.1 </a>The PPC API</h2>
</a>
<a name="495402">
These routines form the interface between applications programs and the low level operating system dependent </a>process control and </a>communication calls. As such they may lack some of the flexibility which the low level routines afford, but they are much easier to use and for most applications they do everything that is necessary.<p>
</a>
<a name="495407">
Most of these routines put an </a>error message into a </a>global variable called </a>PC_err. The message contains the name of the function in which the error occurred thus eliminating the need for a cross reference document on error codes. In this way applications programs can check for error conditions themselves and decide in what manner to use the PPC error messages instead of having error messages printed by the system routines. Error messages are not stacked and must be processed by the application before any other PPC calls are made in order to avoid potential overwrites.<p>
</a>
<A NAME="495682"><BR><B>int </a>PC_block(PROCESS *pp)
</B><BR><a name="495683">
Set the PROCESS pp to be </a>blocked (</a>wait for messages).<p>
</a>
<A NAME="495684">Input: pp, a pointer to a PROCESS.
<P><A NAME="495685">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495408"><BR><B>int </a>PC_block_fd(int fd)
</B><BR><a name="495409">
Set the </a>file descriptor to be </a>blocked (</a>wait for messages).<p>
</a>
<A NAME="495410">Input: fd, an integer file descriptor.
<P><A NAME="495411">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495412"><BR><B>int </a>PC_block_file(FILE *fp)
</B><BR><a name="495413">
Set the </a>FILE to be </a>blocked (</a>wait for messages).<p>
</a>
<A NAME="495415">Input: fp, a pointer to a FILE.
<P><A NAME="495423">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495427"><BR><B>int </a>PC_close(PROCESS *pp)
</B><BR><a name="495428">
</a>Kill the process specified by pp. This is used to </a>terminate and remove a process when it is not needed (even if the executable process has terminated).<p>
</a>
<A NAME="495429">Input: pp, a pointer to a </a>PROCESS.
<P><A NAME="495430">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495431"><BR><B>int </a>PC_echo_off_fd(int fd)
</B><BR><a name="495432">
Set the </a>file descriptor input to be </a>unechoed.<p>
</a>
<A NAME="495433">Input: fd, an integer file descriptor.
<P><A NAME="495434">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495435"><BR><B>int </a>PC_echo_off_file(FILE *fp)
</B><BR><a name="495436">
Set the </a>FILE input to be </a>unechoed.<p>
</a>
<A NAME="495437">Input: fp, a pointer to a FILE.
<P><A NAME="495438">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495439"><BR><B>int </a>PC_echo_on_fd(int fd)
</B><BR><a name="495440">
Set the </a>file descriptor input to be </a>echoed.<p>
</a>
<A NAME="495441">Input: fd, an integer file descriptor.
<P><A NAME="495442">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495443"><BR><B>int </a>PC_echo_on_file(FILE *fp)
</B><BR><a name="495444">
Set the </a>FILE input to be </a>echoed.<p>
</a>
<A NAME="495445">Input: fp, a pointer to a FILE.
<P><A NAME="495446">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495447"><BR><B>int </a>PC_flush(PROCESS *pp)
</B><BR><a name="495448">
</a>Flush the input and output streams for the given process.<p>
</a>
<A NAME="495449">Input: pp, a pointer to a </a>PROCESS.
<P><A NAME="495450">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495453"><BR><B>int </a>PC_gets(char *bf, int len, PROCESS *pp)
</B><BR><a name="495454">
</a>Read a string from a process into the buffer provided. This behaves exactly like </a>fgets except that if there is no input available, NULL is returned without waiting.<p>
</a>
<A NAME="495455">Input: bf, a pointer to an ASCII string.
<P><A NAME="495456"><PRE> len, an integer length of the buffer bf.
</PRE><A NAME="495457"><PRE> pp, a pointer to the </a>PROCESS from which to read the input.
</PRE><A NAME="495458">Output: a pointer to bf if successful or NULL if nothing is available to be read.
<P><A NAME="495693"><BR><B>int </a>PC_io_callback_fd(int fd, PFVoid fnc)
</B><BR><a name="495695">
Change the state of the specified file descriptor so that the specified function will be called when there is input available (</a>interrupt driven or </a>multiplexed).<p>
</a>
<A NAME="495696">Input: fd, an integer file descriptor.
<P><A NAME="495702"><PRE> fnc, a pointer to a function returning nothing which will handle the input.
</PRE><A NAME="495697">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495698"><BR><B>int </a>PC_io_callback_file(FILE *fp, PFVoid fnc)
</B><BR><a name="495699">
Change the state of the specified FILE so that the specified function will be called when there is input available (</a>interrupt driven or </a>multiplexed).<p>
</a>
<A NAME="495700">Input: fp, a pointer to a FILE.
<P><A NAME="495703"><PRE> fnc, a pointer to a function returning nothing which will handle the input.
</PRE><A NAME="495701">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495704"><BR><B>int PC_io_connect(int flag)
</B><BR><a name="495705">
If flag is </a>PC_REMOTE set the I/O hooks (see </a>File I/O Interface section) to the functions for remote file access and if flag is </a>PC_LOCAL set them to the standard C library calls for local access.<p>
</a>
<A NAME="495706">Input: flag, an integer flag.
<P><A NAME="495708">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495459"><BR><B>PROCESS *</a>PC_open(char **argv, char **envp, char *mode)
</B><BR><a name="495460">
</a>Execute a </a>process with </a>command line arguments from argv in some (as yet unspecified) mode. The arguments are handled exactly like those of C programs where argv[0] is the name of the process/program and the remaining entries in argv are null terminated strings each corresponding to a command line argument.<p>
</a>
<a name="495707">
The legal modes are expressed similarly to those for the standard C fopen call:<p>
</a>
<A NAME="495717"><PRE> ( ’r’ | ’w’ | ’a’)[’p’ | ’s’ | ’t’][’b’]
</PRE><a name="495709">
where<p>
</a>
<A NAME="495718"><PRE> r Read only (child stdout only connected to parent)
</PRE><A NAME="495710"><PRE> w Write only (child stdin only connected to parent)
</PRE><A NAME="495711"><PRE> a Append or read/write (child stdin and stdout connnected to parent)
</PRE><A NAME="495713"><PRE> p Communicate via pipe
</PRE><A NAME="495714"><PRE> s Communicate via socket
</PRE><A NAME="495715"><PRE> t Communicate via PTY
</PRE><A NAME="495716"><PRE> b Binary data exchanged
</PRE><a name="495731">
For example, for bidirectional communication with a local child via a pseudo TTY in plain ASCII mode use "at". At this point read only and write only are not fully implemented.<p>
</a>
<A NAME="495719">The default is "as" for remote processes and "ap" for local processes.
<P><A NAME="495712">Input: argv, an array of pointers to the arguments.
<P><A NAME="495462"><PRE> envp, an array of pointers to the environment strings.
</PRE><A NAME="495463"><PRE> mode, an ASCII string indicating the IPC mode.
</PRE><A NAME="495464">Output: a pointer to a </a>PROCESS.
<P><A NAME="495465"><BR><B>int </a>PC_printf(PROCESS *pp, char *fmt, ...)
</B><BR><a name="495466">
</a>Write the arguments to the </a>PROCESS pp according to the </a>format fmt.<p>
</a>
<A NAME="495467">Input: pp, a pointer to a PROCESS.
<P><A NAME="495468"><PRE> fmt, an ASCII string which specifies the </a>output format.
</PRE><A NAME="495469"><PRE> ..., the arguments specified in the format.
</PRE><A NAME="495470">Output: TRUE, if successful and FALSE otherwise.
<P><A NAME="495641"><BR><B>int </a>PC_read(void *bf, char *type, size_t ni, PROCESS *pp)
</B><BR><a name="495642">
Do a binary read of ni items of type type from the </a>PROCESS pp into the buffer bf.<p>
</a>
<A NAME="495643">Input: bf, a pointer to memory into which the data is to be read.
<P><A NAME="495644"><PRE> type, an ASCII string which specifies the data type of items to be read.
</PRE><A NAME="495645"><PRE> ni, an integer (size_t) number of items to be read.
</PRE><A NAME="495646"><PRE> pp, a pointer to a PROCESS.
</PRE><A NAME="495647">Output: The number of items successfully read.
<P><A NAME="495686"><BR><B>int PC_set_attr(PROCESS *pp, int i, int state)
</B><BR><a name="495687">
Set the status flags for the specified PROCESS. The flags which can be set are:<p>
</a>
<A NAME="495461"><PRE> </a>PC_LINE line at a time input
</PRE><A NAME="495720"><PRE> </a>PC_NDELAY non-blocking I/O
</PRE><A NAME="495721"><PRE> </a>PC_APPEND append (writes guaranteed at the end)
</PRE><A NAME="495722"><PRE> </a>PC_SYNC synchronous write option
</PRE><A NAME="495723"><PRE> </a>PC_ASYNC interrupt-driven I/O for sockets
</PRE><A NAME="495688">Input: pp, a pointer to a PROCESS.
<P><A NAME="495689"><PRE> i, an integer value containing a bit pattern indicating attribute settings.
</PRE><A NAME="495690"><PRE> state, an integer value indicating to set or reset.
</PRE><A NAME="495692">Output: i if successful and -1 otherwise.
<P><A NAME="495471"><BR><B>int </a>PC_set_fd_attr(int fd, int i, int state)
</B><BR><a name="495472">
Set the </a>file </a>status flags for a specified </a>file descriptor. The flag which can be set are:<p>
</a>
<A NAME="495724"><PRE> </a>PC_LINE line at a time input
</PRE><A NAME="495725"><PRE> </a>PC_NDELAY non-blocking I/O
</PRE><A NAME="495726"><PRE> </a>PC_APPEND append (writes guaranteed at the end)
</PRE><A NAME="495727"><PRE> </a>PC_SYNC synchronous write option
</PRE><A NAME="495728"><PRE> </a>PC_ASYNC interrupt-driven I/O for sockets
</PRE><A NAME="495473">Input: fd, an integer file descriptor.
<P><A NAME="495474"><PRE> i, an integer value containing a bit pattern indicating attribute settings.
</PRE><A NAME="495656"><PRE> state, an integer value indicating to set or reset.
</PRE><A NAME="495475">Output: i if successful and -1 otherwise.
<P><A NAME="495476"><BR><B>void </a>PC_signal_handler(int signo)
</B><BR><a name="495477">
On receipt of a </a>signal that a </a>child process </a>status has changed, loop forever asking about children with changed status until the system says there are no more.<p>
</a>
<A NAME="495478">Input: signo, an integer signal number.
<P><A NAME="495479">Output: None.
<P><A NAME="495480"><BR><B>int </a>PC_status(PROCESS *pp)
</B><BR><a name="495481">
Return the </a>execution </a>status of the </a>PROCESS pp.<p>
</a>
<A NAME="495482">Input: pp, a pointer to a PROCESS.
<P><A NAME="495483">Output: an integer value, one of </a>RUNNING, </a>STOPPED, </a>EXITED, </a>COREDUMPED,
or </a>SIGNALED.
<P><A NAME="495665"><BR><B>int </a>PC_unblock(PROCESS *pp)
</B><BR><a name="495668">
Set the PROCESS to be </a>unblocked (</a>do not wait for messages).<p>
</a>
<A NAME="495729">Input: pp, a pointer to a PROCESS.
<P><A NAME="495730">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495485"><BR><B>int </a>PC_unblock_fd(int fd)
</B><BR><a name="495486">
Set the </a>file descriptor to be </a>unblocked (</a>do not wait for messages).<p>
</a>
<A NAME="495487">Input: fd, an integer file descriptor.
<P><A NAME="495488">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495489"><BR><B>int </a>PC_unblock_file(FILE *fp)
</B><BR><a name="495490">
Set the </a>FILE to be </a>unblocked (</a>do not wait for messages).<p>
</a>
<A NAME="495492">Input: fp, a pointer to a FILE.
<P><A NAME="495493">Output: TRUE, if successful, FALSE otherwise.
<P><A NAME="495649"><BR><B>int </a>PC_write(void *bf, char *type, size_t ni, PROCESS *pp)
</B><BR><a name="495650">
Do a binary write of ni items of type type to the </a>PROCESS pp from the buffer bf.<p>
</a>
<A NAME="495651">Input: bf, a pointer to memory containing the data to be written.
<P><A NAME="495652"><PRE> type, an ASCII string which specifies the data type of items to be written.
</PRE><A NAME="495653"><PRE> ni, an integer (size_t) number of items to be written.
</PRE><A NAME="495654"><PRE> pp, a pointer to a PROCESS.
</PRE><A NAME="495655">Output: The number of items successfully written.
<P><a name="495403">
<h2>3.2 </a>PPC Constants</h2>
</a>
<a name="495680">
The following #define’d constants should be used in the contexts indicated:<p>
</a>
<a name="495681">
<p>
</a>
<A NAME="495657"></a>RUNNING 0 return value of PC_status indicating process running
<P><A NAME="495658"></a>STOPPED 1 return value of PC_status indicating process stopped
<P><A NAME="495659"></a>CHANGED 2 return value of PC_status indicating process status changed
<P><A NAME="495660"></a>EXITED 4 return value of PC_status indicating process exited
<P><A NAME="495661"></a>COREDUMPED 8 return value of PC_status indicating process crashed
<P><A NAME="495662"></a>SIGNALED 16 return value of PC_status indicating process signalled
<P><A NAME="495663">
<P><A NAME="495666"></a>PC_LOCAL 102 value indicating process or file on current CPU
<P><A NAME="495667"></a>PC_REMOTE 103 value indicating process or file on remote host
<P><A NAME="495669">
<P><A NAME="495670"></a>USE_PTYS 50 value indicating IPC medium is a pseudo terminal
<P><A NAME="495671"></a>USE_SOCKETS 51 value indicating IPC medium is a socket
<P><A NAME="495672"></a>USE_PIPES 52 value indicating IPC medium is a pipe
<P><A NAME="495673">
<P><A NAME="495674"></a>PC_NDELAY used with </a>PC_set_attr to set non-blocking reads
<P><A NAME="495675"></a>PC_APPEND used with </a>PC_set_attr to specify writes at end
<P><A NAME="495676"></a>PC_SYNC used with </a>PC_set_attr to specify synchronous writes
<P><A NAME="495677"></a>PC_LINE used with </a>PC_set_attr to specify line-at-a-time input
<P><a name="495679">
<h2>3.3 </a>PPC Variables</h2>
</a>
<a name="495678">
PPC provides the following global variables:<p>
</a>
<A NAME="495691">char </a>PC_err[] Buffer for </a>error messages from PPC routines
<P><A NAME="495694">int </a>PC_io_interrupts_on Flag which iff TRUE enables </a>I/O </a>interrupts
<P><a name="495535">
<h2>3.4 </a>Compiling and Loading</h2>
</a>
<a name="495404">
To compile your C programs you must use the following<p>
</a>
<A NAME="495509"><PRE> #include <ppc.h>
</PRE><a name="495510">
in the source files which deal with the library routines.<p>
</a>
<a name="495511">
To link your application you must use the following libraries in the order specified.<p>
</a>
<A NAME="495512">-lppc -lpdb -lpml -lscore [ -lm ...]
<P><a name="495513">
Although this is expressed as if for a UNIX linker, the order would be the same for any system with a single pass linker. The items in [] are optional or system dependent.<p>
</a>
<a name="495514">
Each system has different naming conventions for its libraries and the reader is assumed to understand the appropriate naming conventions as well as knowing how to tell the linker to find the installed PACT libraries on each system that they use.<p>
</a>
<a name="495391">
<h2>3.5 </a>Data Structures for PPC</h2>
</a>
<A NAME="495397"><B></a>PROCESS
</B><BR><a name="495414">
The data structure which underlies </a>PPC is the PROCESS. It is analogous in purpose to the FILE structure used for file I/O. PROCESS structures contain the information necessary for PPC routines to monitor and communicate with child processes. They are passed to PPC routines the way the </a>FILE structure is passed in the </a>standard C file I/O routines.<p>
</a>
<a name="495491">
<h2>3.6 </a>Example</h2>
</a>
<a name="495557">
The following example is a basic test of PPC in which a small </a>polling loop gets </a>messages from the </a>controlling terminal and passes them to a </a>child </a>process while polling the child process for messages and sending them to the controlling terminal. This program should be entirely transparent to the application.<p>
</a>
<a name="495558">
<p>
</a>
<A NAME="495555"><PRE> #include "ppc.h"
</PRE><A NAME="495556"><PRE>
</PRE><A NAME="495560"><PRE> main(argc, argv, envp)
</PRE><A NAME="495561"><PRE> int argc;
</PRE><A NAME="495562"><PRE> char **argv, **envp;
</PRE><A NAME="495563"><PRE> {PROCESS *pp;
</PRE><A NAME="495564"><PRE> char s[BIGLINE];
</PRE><A NAME="495565"><PRE>
</PRE><A NAME="495566"><PRE> /* open the process */
</PRE><A NAME="495567"><PRE> if ((pp = PC_open(argv+1, envp, "w")) == NULL)
</PRE><A NAME="495568"><PRE> {printf("\nFailed to open: %s\n\n", argv[1]);
</PRE><A NAME="495569"><PRE> exit(1);};
</PRE><A NAME="495570"><PRE>
</PRE><A NAME="495571"><PRE> printf("\nRunning process: %s\n\n", argv[1]);
</PRE><A NAME="495572"><PRE>
</PRE><A NAME="495573"><PRE> /* unblock stdin and turn stdout buffering off */
</PRE><A NAME="495574"><PRE> PC_unblock_file(stdin);
</PRE><A NAME="495576"><PRE> setbuf(stdout, NULL);
</PRE><A NAME="495577"><PRE>
</PRE><A NAME="495578"><PRE> while (TRUE)
</PRE><A NAME="495579"><PRE> {PC_err[0] = ’\0’;
</PRE><A NAME="495581"><PRE> while (PC_gets(s, BIGLINE, pp) != NULL)
</PRE><A NAME="495582"><PRE> printf("%s", s);
</PRE><A NAME="495583"><PRE>
</PRE><A NAME="495584"><PRE> /* check the status of the process */
</PRE><A NAME="495585"><PRE> if (PC_status(pp) != RUNNING)
</PRE><A NAME="495586"><PRE> {printf("\nProcess %s terminated (%d %d)\n\n",
</PRE><A NAME="495587"><PRE> argv[1], pp->status, pp->reason);
</PRE><A NAME="495588"><PRE> break;};
</PRE><A NAME="495589"><PRE>
</PRE><A NAME="495590"><PRE> /* get any messages from tty, if available */
</PRE><A NAME="495591"><PRE> if (fgets(s, BIGLINE, stdin) != NULL)
</PRE><A NAME="495593"><PRE> PC_printf(pp, "%s", s);
</PRE><A NAME="495594"><PRE>
</PRE><A NAME="495595"><PRE> if (PC_err[0] != ’\0’)
</PRE><A NAME="495596"><PRE> {printf("\nERROR: %s\n\n", PC_err);
</PRE><A NAME="495597"><PRE> break;};};
</PRE><A NAME="495598"><PRE>
</PRE><A NAME="495599"><PRE> /* close the process */
</PRE><A NAME="495600"><PRE> PC_close(pp);
</PRE><A NAME="495601"><PRE>
</PRE><A NAME="495602"><PRE> printf("\nProcess test %s ended\n\n", argv[1]);
</PRE><A NAME="495603"><PRE>
</PRE><A NAME="495604"><PRE> /* turn on blocking for stdin (very important) */
</PRE><A NAME="495605"><PRE> PC_block_file(stdin);
</PRE><A NAME="495606"><PRE>
</PRE><A NAME="495607"><PRE> exit(0);}
</PRE><A NAME="495608"><PRE>
</PRE><a name="495613">
<h1>4.0 </a>PCEXEC</h1>
</a>
<a name="495495">
PPC includes an application program called </a>pcexec. It began as a test code for PPC but it has expanded to the point where it has utility in its own right. In fact, pcexec does two jobs. First, it can be used to run other programs in any of the modes discussed in the section </a>The PPC Model. Second, it acts as a file access server for the remote file access capability in PACT.<p>
</a>
<a name="495395">
<h2>4.1 Usage</h2>
</a>
<a name="495396">
Run prog as a child process:<p>
</a>
<A NAME="495516"><PRE> pcexec [-p | -s | -t] [-i] [-q] prog [arg1 ...]
</PRE><a name="495452">
Act as a file access server on host (triggered by -f):<p>
</a>
<A NAME="495518"><PRE> pcexec -f [-l] host
</PRE><a name="495517">
The forms for prog are:<p>
</a>
<A NAME="495519">name run name on local host
<P><A NAME="495520">host:name run name on remote host
<P><A NAME="495521">CPU@name run name on processor CPU
<P><A NAME="495522">host:CPU@name run name on processor CPU on remote host
<P><a name="495523">
The last two are not yet completed.<p>
</a>
<a name="495525">
The full syntax for host is one of the following:<p>
</a>
<A NAME="495526">hostname
<P><A NAME="495527">hostname,username
<P><A NAME="495528">hostname,username,passwd
<P><a name="495529">
Note: whitespace is NOT allowed<p>
</a>
<a name="495530">
Options:<p>
</a>
<A NAME="495531">i Poll explicitly instead of using system call
<P><A NAME="495532">l When acting as file server, log transactions to PC_fs.log in home directory
<P><A NAME="495536">q Print only messages from the child
<P><A NAME="495664">p Use pipes for communications (default for local processes)
<P><A NAME="495538">s Use sockets for communications (only mode for remote processes)
<P><A NAME="495539">t Use pseudo terminals for communications
<P><a name="495540">
All three modes (pipes, sockets, pseudo terminals) are available for local processes.<p>
</a>
<a name="495494">
<h1>5.0 Other </a>PACT </a>Documentation</h1>
</a>
<a name="495553">
</a>PPC uses functions from the PACT </a>SCORE and PDB libraries. The interested reader is referred to the other PACT documentation:<p>
</a>
<a name="495534">
The list of PACT Documents is:<p>
</a>
<A NAME="495549"><PRE> PACT User’s Guide, UCRL-MA-112087
</PRE><A NAME="495551"><PRE> SCORE User’s Manual, UCRL-MA-108976 Rev.1
</PRE><A NAME="495552"><PRE> PPC User’s Manual UCRL-MA-108964 Rev.1 (this document)
</PRE><A NAME="495554"><PRE> PML User’s Manual, UCRL-MA-108965 Rev.1
</PRE><A NAME="495575"><PRE> PDBLib User’s Manual, M-270 Rev.2
</PRE><A NAME="495580"><PRE> PGS User’s Manual, UCRL-MA-108966 Rev.1
</PRE><A NAME="495592"><PRE> PANACEA User’s Manual, M-276 Rev.2
</PRE><A NAME="495609"><PRE> ULTRA II User’s Manual, UCRL-MA-108967 Rev.1
</PRE><A NAME="495610"><PRE> PDBDiff User’s Manual, UCRL-MA-108975 Rev.1
</PRE><A NAME="495611"><PRE> PDBView User’s Manual, UCRL-MA-108968 Rev.1
</PRE><A NAME="495614"><PRE> SX User’s Manual, UCRL-MA-112315
</PRE><a name="495502">
<p>
</a>
<p><hr>
</body></html>
|
