Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / IPC::Run::IO.3pm

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IPC::Run::IO 3"
.TH IPC::Run::IO 3 "2009-07-13" "perl v5.8.7" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IPC::Run::IO \-\- I/O channels for IPC::Run.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fB\s-1NOT\s0 \s-1IMPLEMENTED\s0 \s-1YET\s0 \s-1ON\s0 Win32! Win32 does not allow \f(BIselect()\fB on
normal file descriptors; \s-1IPC::RUN::IO\s0 needs to use IPC::Run::Win32Helper
to do this.\fR
.PP
.Vb 1
\&   use IPC::Run qw( io );
\&
\&   ## The sense of \*(Aq>\*(Aq and \*(Aq<\*(Aq is opposite of perl\*(Aqs open(),
\&   ## but agrees with IPC::Run.
\&   $io = io( "filename", \*(Aq>\*(Aq,  \e$recv );
\&   $io = io( "filename", \*(Aqr\*(Aq,  \e$recv );
\&
\&   ## Append to $recv:
\&   $io = io( "filename", \*(Aq>>\*(Aq, \e$recv );
\&   $io = io( "filename", \*(Aqra\*(Aq, \e$recv );
\&
\&   $io = io( "filename", \*(Aq<\*(Aq,  \e$send );
\&   $io = io( "filename", \*(Aqw\*(Aq,  \e$send );
\&
\&   $io = io( "filename", \*(Aq<<\*(Aq, \e$send );
\&   $io = io( "filename", \*(Aqwa\*(Aq, \e$send );
\&
\&   ## Handles / IO objects that the caller opens:
\&   $io = io( \e*HANDLE,   \*(Aq<\*(Aq,  \e$send );
\&
\&   $f = IO::Handle\->new( ... ); # Any subclass of IO::Handle
\&   $io = io( $f, \*(Aq<\*(Aq, \e$send );
\&
\&   require IPC::Run::IO;
\&   $io = IPC::Run::IO\->new( ... );
\&
\&   ## Then run(), harness(), or start():
\&   run $io, ...;
\&
\&   ## You can, of course, use io() or IPC::Run::IO\->new() as an
\&   ## argument to run(), harness, or start():
\&   run io( ... );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class and module allows filehandles and filenames to be harnessed for
I/O when used IPC::Run, independant of anything else IPC::Run is doing
(except that errors & exceptions can affect all things that IPC::Run is
doing).
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
\&\s-1INCOMPATIBLE\s0 \s-1CHANGE:\s0 due to the awkwardness introduced in ripping pseudohashes
out of Perl, this class \fIno longer\fR uses the fields pragma.
.SH "TODO"
.IX Header "TODO"
Implement bidirectionality.
.SH "AUTHOR"
.IX Header "AUTHOR"
Barrie Slaymaker <barries@slaysys.com>
.IP "filename" 4
.IX Item "filename"
Gets/sets the filename.  Returns the value after the name change, if
any.
.IP "init" 4
.IX Item "init"
Does initialization required before this can be run.  This includes \fIopen()\fRing
the file, if necessary, and clearing the destination scalar if necessary.
.IP "open" 4
.IX Item "open"
If a filename was passed in, opens it.  Determines if the handle is open
via \fIfileno()\fR.  Throws an exception on error.
.IP "open_pipe" 4
.IX Item "open_pipe"
If this is a redirection \s-1IO\s0 object, this opens the pipe in a platform
independant manner.
.IP "close" 4
.IX Item "close"
Closes the handle.  Throws an exception on failure.
.IP "fileno" 4
.IX Item "fileno"
Returns the fileno of the handle.  Throws an exception on failure.
.IP "mode" 4
.IX Item "mode"
Returns the operator in terms of 'r', 'w', and 'a'.  There is a state
\&'ra', unlike Perl's \fIopen()\fR, which indicates that data read from the
handle or file will be appended to the output if the output is a scalar.
This is only meaningful if the output is a scalar, it has no effect if
the output is a subroutine.
.Sp
The redirection operators can be a little confusing, so here's a reference
table:
.Sp
.Vb 6
\&   >      r      Read from handle in to process
\&   <      w      Write from process out to handle
\&   >>     ra     Read from handle in to process, appending it to existing
\&                 data if the destination is a scalar.
\&   <<     wa     Write from process out to handle, appending to existing
\&                 data if IPC::Run::IO opened a named file.
.Ve
.IP "op" 4
.IX Item "op"
Returns the operation: '<', '>', '<<', '>>'.  See \*(L"mode\*(R" if you want
to spell these 'r', 'w', etc.
.IP "binmode" 4
.IX Item "binmode"
Sets/gets whether this pipe is in binmode or not.  No effect off of Win32
OSs, of course, and on Win32, no effect after the harness is \fIstart()\fRed.
.IP "dir" 4
.IX Item "dir"
Returns the first character of \f(CW$self\fR\->op.  This is either \*(L"<\*(R" or \*(L">\*(R".