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
|
'\"macro stdmacro
.\"
.\" Copyright (c) 2017 Ken McDonell. All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMPROCESSPIPE 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3__pmProcessPipe\f1,
\f3__pmProcessPipeClose\f1 \- support for process execution at the end of a pipe
.SH "C SYNOPSIS"
.ft 3
#include "pmapi.h"
.br
#include "libpcp.h"
.sp
int __pmProcessPipe(__pmExecCtl_t **\fIhandle\fP, const char *\fItype\fP, int \fItoss\fP, FILE **\fIfp\fP);
.br
int __pmProcessPipeClose(FILE *\fIfp\fP);
.sp
cc ... \-lpcp
.ft 1
.SH CAVEAT
This documentation is intended for internal Performance Co-Pilot
(PCP) developer use.
.PP
These interfaces are not part of the PCP APIs that are guaranteed to
remain fixed across releases, and they may not work, or may provide
different semantics at some point in the future.
.SH DESCRIPTION
Within the libraries and applications of the Performance Co-Pilot
(PCP) these routines are provide a convenient and safe alternative
to
.BR popen (3)
and
.BR pclose (3)
for executing commands in a separate process that is connected
to the caller by a pipe.
.PP
Setting up the command and arguments is fully documented in
.BR __pmProcessAddArg (3)
and is identical to the procedure used to setup
.BR __pmProcessExec (3).
.PP
Once all the command name and arguments have been registered
calling
.B __pmProcessPipe
uses a
.BR pipe (2),
.BR fork (2)
and
.BR execvp (2)
sequence to execute the command.
.PP
The
.I type
argument needs to be
.B ``r''
to read from the pipe, else
.B ``w''
to write to the pipe.
.PP
The argument
.I toss
may be used to assign some or all of the standard I/O streams
for the command to
.I /dev/null
\- specifically
.I toss
is either
.B PM_EXEC_TOSS_NONE
to keep all I/O streams the same as the parent process, else
the bit-wise or of
.B PM_EXEC_TOSS_STDIN
and/or
.B PM_EXEC_TOSS_STDOUT
and/or
.B PM_EXEC_TOSS_STDERR
to reassign
.BR stdin ,
.B stdout
and
.B stderr
respectively.
.B PM_EXEC_TOSS_ALL
is a convenience macro equivalent to
.BR "PM_EXEC_TOSS_STDIN | PM_EXEC_TOSS_STDOUT | PM_EXEC_TOSS_STDERR" .
.PP
Obviously some combinations of argument values make no sense,
e.g. \c
.I type
equal to
.B ``r''
and
.B PM_EXEC_TOSS_STDOUT
set in
.I toss
or
.I type
equal to
.B ``w''
and
.B PM_EXEC_TOSS_STDIN
set in
.IR type .
.PP
.B __pmProcessPipe
returns a standard I/O stream for the pipe via the
.I fp
argument.
.PP
Once the caller determines all the work has been done,
.B __pmProcessPipeClose
should be called.
.PP
Nested calling of
.BR __pmProcessExec (3)
and/or
.B __pmProcessPipe
is not allowed. Once
.BR __pmProcessAddArg (3)
is called with
.I handle
set to
.BR NULL
to start the registration and execution sequence any attempt
to start a second registration sequence will be blocked until
the first one is completed by calling
.BR __pmProcessExec (3)
or
.BR __pmProcessPipe .
.SH DIAGNOSTICS
If successful
.B __pmProcessPipe
returns 0. Other conditions are rare (e.g. memory allocation failure) and are
indicated by a return value that can be decoded using
.BR pmErrStr (3).
.PP
The return status from
.B __pmProcessPipeClose
is a little more complicated.
If the command completes with an exit status of 0,
the return value is 0.
Return values less than 0 indicate a more serious error and the
value can be decoded using
.BR pmErrStr (3).
If the command was executed, but did not exit with status of 0 then
the return value is an encoding of the
.BR waitpid (2)
status as follows: 2000 if something unknown went wrong, else
if 1000 + signal number of the command was killed or stopped by
a signal, else the exit status of the command.
.SH SEE ALSO
.BR execvp (2),
.BR fork (2),
.BR pclose (2),
.BR pipe (2),
.BR popen (2),
.BR __pmProcessAddArg (3),
.BR __pmProcessExec (3)
and
.BR waitpid (3).
|
