This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate perlio:
[perl5.git] / ext / PerlIO / Via / Via.pm
CommitLineData
e7a1fdd7
NIS
1package PerlIO::Via;
2our $VERSION = '0.01';
3use XSLoader ();
4XSLoader::load 'PerlIO::Via';
51;
6__END__
7
8=head1 NAME
9
10PerlIO::Via - Helper class for PerlIO layers implemented in perl
11
12=head1 SYNOPSIS
13
14 use Some::Package;
15
16 open($fh,"<:Via(Some::Package)",...);
17
18=head1 DESCRIPTION
19
20The package to be used as a layer should implement at least some of the
21following methods. In the method descriptions below I<$fh> will be
22a reference to a glob which can be treated as a perl file handle.
23It refers to the layer below. I<$fh> is not passed if the layer
24is at the bottom of the stack, for this reason and to maintain
25some level of "compatibility" with TIEHANDLE classes it is passed
26last.
27
28=over 4
29
30=item $class->PUSHED([$mode][,$fh])
31
32Should return an object or the class. (Compare TIEHANDLE.)
33Mandatory.
34
35=item $obj->POPPED([$fh])
36
37Optional - layer is about to be removed.
38
39=item $class->OPEN($path,$mode[,$fh])
40
41Not yet in use.
42
43=item $class->FDOPEN($fd)
44
45Not yet in use.
46
47=item $class->SYSOPEN($path,$imode,$perm,$fh)
48
49Not yet in use.
50
51=item $obj->FILENO($fh)
52
53Returns a numeric value for Unix-like file descriptor. Return -1
54if there isn't one.
55Optional -default is fileno($fh).
56
57=item $obj->READ($buffer,$len,$fh)
58
59Returns the number of octets placed in $buffer (must be less that $len).
60Optional - default is to use FILL instead.
61
62=item $obj->WRITE($buffer,$fh)
63
64Returns the number of octets from buffer that have been sucessfully written.
65
66=item $obj->FILL($fh)
67
68Should return a string to be placed in the buffer.
69Optional. If not provided must provide READ or reject handles open for
70reading in PUSHED.
71
72=item $obj->CLOSE($fh)
73
74Should return 0 on success, -1 on error.
75Optional.
76
77=item $obj->SEEK($posn,$whence,$fh)
78
79Should return 0 on success, -1 on error.
80Optional. Default is to fail, but that is likely to be changed.
81
82=item $obj->TELL($fh)
83
84Returns file postion.
85Optional. Default to be determined.
86
87=item $obj->UNREAD($buffer,$fh)
88
89Returns the number of octets from buffer that have been sucessfully saved
90to be returned on future FILL/READ calls.
91Optional. Default is to push data into a temporary layer above this one.
92
93=item $obj->FLUSH($fh)
94
95Flush any buffered write data.
96May possibly be called on readable handles too.
97Should return 0 on success, -1 on error.
98
99=item $obj->SETLINEBUF($fh)
100
101Optional. No return.
102
103=item $obj->CLEARERR($fh)
104
105Optional. No return.
106
107=item $obj->ERROR($fh)
108
109Optional. Returns error state. Default is no error until a mechanism
110to signal error (die?) is worked out.
111
112=item $obj->EOF($fh)
113
114Optional. Returns end-of-file state. Default is function of return value of FILL
115or READ.
116
117=back
118
119=cut
120
121