projects / OpenSPARC-T2-DV / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / IPC::Open3.3
CommitLineData
86530b38
AT		 1.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
13.de Sp \" Vertical space (when we can't use .PP)
14.if t .sp .5v
15.if n .sp
16..
17.de Vb \" Begin verbatim text
18.ft CW
19.nf
20.ne \\$1
21..
22.de Ve \" End verbatim text
23.ft R
24.fi
25..
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr
33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34.ie n \{\
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
43'br\}
44.el\{\
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
49'br\}
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
58..
59. nr % 0
60. rr F
61.\}
62.\"
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
71.if n \{\
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
77.\}
78.if t \{\
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
84.\}
85. \" simple accents for nroff and troff
86.if n \{\
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
93.\}
94.if t \{\
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
101.\}
102. \" troff and (daisy-wheel) nroff accents
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
112. \" corrections for vroff
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115. \" for low resolution devices (crt and lpr)
116.if \n(.H>23 .if \n(.V>19 \
117\{\
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
127.\}
128.rm #[ #] #H #V #F C
129.\" ========================================================================
130.\"
131.IX Title "IPC::Open3 3"
132.TH IPC::Open3 3 "2002-06-01" "perl v5.8.0" "Perl Programmers Reference Guide"
133.SH "NAME"
134IPC::Open3, open3 \- open a process for reading, writing, and error handling
135.SH "SYNOPSIS"
136.IX Header "SYNOPSIS"
137.Vb 2
138\& $pid = open3(\e*WTRFH, \e*RDRFH, \e*ERRFH,
139\& 'some cmd and args', 'optarg', ...);
140.Ve
141.PP
142.Vb 3
143\& my($wtr, $rdr, $err);
144\& $pid = open3($wtr, $rdr, $err,
145\& 'some cmd and args', 'optarg', ...);
146.Ve
147.SH "DESCRIPTION"
148.IX Header "DESCRIPTION"
149Extremely similar to \fIopen2()\fR, \fIopen3()\fR spawns the given \f(CW$cmd\fR and
150connects \s-1RDRFH\s0 for reading, \s-1WTRFH\s0 for writing, and \s-1ERRFH\s0 for errors. If
151\&\s-1ERRFH\s0 is false, or the same file descriptor as \s-1RDRFH\s0, then \s-1STDOUT\s0 and
152\&\s-1STDERR\s0 of the child are on the same filehandle. The \s-1WTRFH\s0 will have
153autoflush turned on.
154.PP
155If \s-1WTRFH\s0 begins with \f(CW\*(C`<&\*(C'\fR, then \s-1WTRFH\s0 will be closed in the parent, and
156the child will read from it directly. If \s-1RDRFH\s0 or \s-1ERRFH\s0 begins with
157\&\f(CW\*(C`>&\*(C'\fR, then the child will send output directly to that filehandle.
158In both cases, there will be a \fIdup\fR\|(2) instead of a \fIpipe\fR\|(2) made.
159.PP
160If either reader or writer is the null string, this will be replaced
161by an autogenerated filehandle. If so, you must pass a valid lvalue
162in the parameter slot so it can be overwritten in the caller, or
163an exception will be raised.
164.PP
165The filehandles may also be integers, in which case they are understood
166as file descriptors.
167.PP
168\&\fIopen3()\fR returns the process \s-1ID\s0 of the child process. It doesn't return on
169failure: it just raises an exception matching \f(CW\*(C`/^open3:/\*(C'\fR. However,
170\&\f(CW\*(C`exec\*(C'\fR failures in the child are not detected. You'll have to
171trap \s-1SIGPIPE\s0 yourself.
172.PP
173\&\fIopen3()\fR does not wait for and reap the child process after it exits.
174Except for short programs where it's acceptable to let the operating system
175take care of this, you need to do this yourself. This is normally as
176simple as calling \f(CW\*(C`waitpid $pid, 0\*(C'\fR when you're done with the process.
177Failing to do this can result in an accumulation of defunct or \*(L"zombie\*(R"
178processes. See \*(L"waitpid\*(R" in perlfunc for more information.
179.PP
180If you try to read from the child's stdout writer and their stderr
181writer, you'll have problems with blocking, which means you'll want
182to use \fIselect()\fR or the IO::Select, which means you'd best use
183\&\fIsysread()\fR instead of \fIreadline()\fR for normal stuff.
184.PP
185This is very dangerous, as you may block forever. It assumes it's
186going to talk to something like \fBbc\fR, both writing to it and reading
187from it. This is presumably safe because you \*(L"know\*(R" that commands
188like \fBbc\fR will read a line at a time and output a line at a time.
189Programs like \fBsort\fR that read their entire input stream first,
190however, are quite apt to cause deadlock.
191.PP
192The big problem with this approach is that if you don't have control
193over source code being run in the child process, you can't control
194what it does with pipe buffering. Thus you can't just open a pipe to
195\&\f(CW\*(C`cat \-v\*(C'\fR and continually read and write a line from it.
196.SH "WARNING"
197.IX Header "WARNING"
198The order of arguments differs from that of \fIopen2()\fR.
Full OpenSPARC design & verification tarball including full HDL.