local-lib5/man/man3/IPC::Run::IO.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "IPC::Run::IO 3"
 127 .TH IPC::Run::IO 3 "2009-07-13" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 IPC::Run::IO \-\- I/O channels for IPC::Run.
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 \&\fB\s-1NOT\s0 \s-1IMPLEMENTED\s0 \s-1YET\s0 \s-1ON\s0 Win32! Win32 does not allow \f(BIselect()\fB on
 137 normal file descriptors; \s-1IPC::RUN::IO\s0 needs to use IPC::Run::Win32Helper
 138 to do this.\fR
 139 .PP
 140 .Vb 1
 141 \&   use IPC::Run qw( io );
 142 \&
 143 \&   ## The sense of \*(Aq>\*(Aq and \*(Aq<\*(Aq is opposite of perl\*(Aqs open(),
 144 \&   ## but agrees with IPC::Run.
 145 \&   $io = io( "filename", \*(Aq>\*(Aq,  \e$recv );
 146 \&   $io = io( "filename", \*(Aqr\*(Aq,  \e$recv );
 147 \&
 148 \&   ## Append to $recv:
 149 \&   $io = io( "filename", \*(Aq>>\*(Aq, \e$recv );
 150 \&   $io = io( "filename", \*(Aqra\*(Aq, \e$recv );
 151 \&
 152 \&   $io = io( "filename", \*(Aq<\*(Aq,  \e$send );
 153 \&   $io = io( "filename", \*(Aqw\*(Aq,  \e$send );
 154 \&
 155 \&   $io = io( "filename", \*(Aq<<\*(Aq, \e$send );
 156 \&   $io = io( "filename", \*(Aqwa\*(Aq, \e$send );
 157 \&
 158 \&   ## Handles / IO objects that the caller opens:
 159 \&   $io = io( \e*HANDLE,   \*(Aq<\*(Aq,  \e$send );
 160 \&
 161 \&   $f = IO::Handle\->new( ... ); # Any subclass of IO::Handle
 162 \&   $io = io( $f, \*(Aq<\*(Aq, \e$send );
 163 \&
 164 \&   require IPC::Run::IO;
 165 \&   $io = IPC::Run::IO\->new( ... );
 166 \&
 167 \&   ## Then run(), harness(), or start():
 168 \&   run $io, ...;
 169 \&
 170 \&   ## You can, of course, use io() or IPC::Run::IO\->new() as an
 171 \&   ## argument to run(), harness, or start():
 172 \&   run io( ... );
 173 .Ve
 174 .SH "DESCRIPTION"
 175 .IX Header "DESCRIPTION"
 176 This class and module allows filehandles and filenames to be harnessed for
 177 I/O when used IPC::Run, independant of anything else IPC::Run is doing
 178 (except that errors & exceptions can affect all things that IPC::Run is
 179 doing).
 180 .SH "SUBCLASSING"
 181 .IX Header "SUBCLASSING"
 182 \&\s-1INCOMPATIBLE\s0 \s-1CHANGE:\s0 due to the awkwardness introduced in ripping pseudohashes
 183 out of Perl, this class \fIno longer\fR uses the fields pragma.
 184 .SH "TODO"
 185 .IX Header "TODO"
 186 Implement bidirectionality.
 187 .SH "AUTHOR"
 188 .IX Header "AUTHOR"
 189 Barrie Slaymaker <barries@slaysys.com>
 190 .IP "filename" 4
 191 .IX Item "filename"
 192 Gets/sets the filename.  Returns the value after the name change, if
 193 any.
 194 .IP "init" 4
 195 .IX Item "init"
 196 Does initialization required before this can be run.  This includes \fIopen()\fRing
 197 the file, if necessary, and clearing the destination scalar if necessary.
 198 .IP "open" 4
 199 .IX Item "open"
 200 If a filename was passed in, opens it.  Determines if the handle is open
 201 via \fIfileno()\fR.  Throws an exception on error.
 202 .IP "open_pipe" 4
 203 .IX Item "open_pipe"
 204 If this is a redirection \s-1IO\s0 object, this opens the pipe in a platform
 205 independant manner.
 206 .IP "close" 4
 207 .IX Item "close"
 208 Closes the handle.  Throws an exception on failure.
 209 .IP "fileno" 4
 210 .IX Item "fileno"
 211 Returns the fileno of the handle.  Throws an exception on failure.
 212 .IP "mode" 4
 213 .IX Item "mode"
 214 Returns the operator in terms of 'r', 'w', and 'a'.  There is a state
 215 \&'ra', unlike Perl's \fIopen()\fR, which indicates that data read from the
 216 handle or file will be appended to the output if the output is a scalar.
 217 This is only meaningful if the output is a scalar, it has no effect if
 218 the output is a subroutine.
 219 .Sp
 220 The redirection operators can be a little confusing, so here's a reference
 221 table:
 222 .Sp
 223 .Vb 6
 224 \&   >      r      Read from handle in to process
 225 \&   <      w      Write from process out to handle
 226 \&   >>     ra     Read from handle in to process, appending it to existing
 227 \&                 data if the destination is a scalar.
 228 \&   <<     wa     Write from process out to handle, appending to existing
 229 \&                 data if IPC::Run::IO opened a named file.
 230 .Ve
 231 .IP "op" 4
 232 .IX Item "op"
 233 Returns the operation: '<', '>', '<<', '>>'.  See \*(L"mode\*(R" if you want
 234 to spell these 'r', 'w', etc.
 235 .IP "binmode" 4
 236 .IX Item "binmode"
 237 Sets/gets whether this pipe is in binmode or not.  No effect off of Win32
 238 OSs, of course, and on Win32, no effect after the harness is \fIstart()\fRed.
 239 .IP "dir" 4
 240 .IX Item "dir"
 241 Returns the first character of \f(CW$self\fR\->op.  This is either \*(L"<\*(R" or \*(L">\*(R".