Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
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 "PERLIOL 1" | |
132 | .TH PERLIOL 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perliol \- C API for Perl's implementation of IO in Layers. | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 2 | |
138 | \& /* Defining a layer ... */ | |
139 | \& #include <perliol.h> | |
140 | .Ve | |
141 | .SH "DESCRIPTION" | |
142 | .IX Header "DESCRIPTION" | |
143 | This document describes the behavior and implementation of the PerlIO | |
144 | abstraction described in perlapio when \f(CW\*(C`USE_PERLIO\*(C'\fR is defined (and | |
145 | \&\f(CW\*(C`USE_SFIO\*(C'\fR is not). | |
146 | .Sh "History and Background" | |
147 | .IX Subsection "History and Background" | |
148 | The PerlIO abstraction was introduced in perl5.003_02 but languished as | |
149 | just an abstraction until perl5.7.0. However during that time a number | |
150 | of perl extensions switched to using it, so the \s-1API\s0 is mostly fixed to | |
151 | maintain (source) compatibility. | |
152 | .PP | |
153 | The aim of the implementation is to provide the PerlIO \s-1API\s0 in a flexible | |
154 | and platform neutral manner. It is also a trial of an \*(L"Object Oriented | |
155 | C, with vtables\*(R" approach which may be applied to perl6. | |
156 | .Sh "Basic Structure" | |
157 | .IX Subsection "Basic Structure" | |
158 | PerlIO is a stack of layers. | |
159 | .PP | |
160 | The low levels of the stack work with the low-level operating system | |
161 | calls (file descriptors in C) getting bytes in and out, the higher | |
162 | layers of the stack buffer, filter, and otherwise manipulate the I/O, | |
163 | and return characters (or bytes) to Perl. Terms \fIabove\fR and \fIbelow\fR | |
164 | are used to refer to the relative positioning of the stack layers. | |
165 | .PP | |
166 | A layer contains a \*(L"vtable\*(R", the table of I/O operations (at C level | |
167 | a table of function pointers), and status flags. The functions in the | |
168 | vtable implement operations like \*(L"open\*(R", \*(L"read\*(R", and \*(L"write\*(R". | |
169 | .PP | |
170 | When I/O, for example \*(L"read\*(R", is requested, the request goes from Perl | |
171 | first down the stack using \*(L"read\*(R" functions of each layer, then at the | |
172 | bottom the input is requested from the operating system services, then | |
173 | the result is returned up the stack, finally being interpreted as Perl | |
174 | data. | |
175 | .PP | |
176 | The requests do not necessarily go always all the way down to the | |
177 | operating system: that's where PerlIO buffering comes into play. | |
178 | .PP | |
179 | When you do an \fIopen()\fR and specify extra PerlIO layers to be deployed, | |
180 | the layers you specify are \*(L"pushed\*(R" on top of the already existing | |
181 | default stack. One way to see it is that \*(L"operating system is | |
182 | on the left\*(R" and \*(L"Perl is on the right\*(R". | |
183 | .PP | |
184 | What exact layers are in this default stack depends on a lot of | |
185 | things: your operating system, Perl version, Perl compile time | |
186 | configuration, and Perl runtime configuration. See PerlIO, | |
187 | \&\*(L"\s-1PERLIO\s0\*(R" in perlrun, and open for more information. | |
188 | .PP | |
189 | \&\fIbinmode()\fR operates similarly to \fIopen()\fR: by default the specified | |
190 | layers are pushed on top of the existing stack. | |
191 | .PP | |
192 | However, note that even as the specified layers are \*(L"pushed on top\*(R" | |
193 | for \fIopen()\fR and \fIbinmode()\fR, this doesn't mean that the effects are | |
194 | limited to the \*(L"top\*(R": PerlIO layers can be very 'active' and inspect | |
195 | and affect layers also deeper in the stack. As an example there | |
196 | is a layer called \*(L"raw\*(R" which repeatedly \*(L"pops\*(R" layers until | |
197 | it reaches the first layer that has declared itself capable of | |
198 | handling binary data. The \*(L"pushed\*(R" layers are processed in left-to-right | |
199 | order. | |
200 | .PP | |
201 | \&\fIsysopen()\fR operates (unsurprisingly) at a lower level in the stack than | |
202 | \&\fIopen()\fR. For example in \s-1UNIX\s0 or UNIX-like systems \fIsysopen()\fR operates | |
203 | directly at the level of file descriptors: in the terms of PerlIO | |
204 | layers, it uses only the \*(L"unix\*(R" layer, which is a rather thin wrapper | |
205 | on top of the \s-1UNIX\s0 file descriptors. | |
206 | .Sh "Layers vs Disciplines" | |
207 | .IX Subsection "Layers vs Disciplines" | |
208 | Initial discussion of the ability to modify \s-1IO\s0 streams behaviour used | |
209 | the term \*(L"discipline\*(R" for the entities which were added. This came (I | |
210 | believe) from the use of the term in \*(L"sfio\*(R", which in turn borrowed it | |
211 | from \*(L"line disciplines\*(R" on Unix terminals. However, this document (and | |
212 | the C code) uses the term \*(L"layer\*(R". | |
213 | .PP | |
214 | This is, I hope, a natural term given the implementation, and should | |
215 | avoid connotations that are inherent in earlier uses of \*(L"discipline\*(R" | |
216 | for things which are rather different. | |
217 | .Sh "Data Structures" | |
218 | .IX Subsection "Data Structures" | |
219 | The basic data structure is a PerlIOl: | |
220 | .PP | |
221 | .Vb 3 | |
222 | \& typedef struct _PerlIO PerlIOl; | |
223 | \& typedef struct _PerlIO_funcs PerlIO_funcs; | |
224 | \& typedef PerlIOl *PerlIO; | |
225 | .Ve | |
226 | .PP | |
227 | .Vb 6 | |
228 | \& struct _PerlIO | |
229 | \& { | |
230 | \& PerlIOl * next; /* Lower layer */ | |
231 | \& PerlIO_funcs * tab; /* Functions for this layer */ | |
232 | \& IV flags; /* Various flags for state */ | |
233 | \& }; | |
234 | .Ve | |
235 | .PP | |
236 | A \f(CW\*(C`PerlIOl *\*(C'\fR is a pointer to the struct, and the \fIapplication\fR | |
237 | level \f(CW\*(C`PerlIO *\*(C'\fR is a pointer to a \f(CW\*(C`PerlIOl *\*(C'\fR \- i.e. a pointer | |
238 | to a pointer to the struct. This allows the application level \f(CW\*(C`PerlIO *\*(C'\fR | |
239 | to remain constant while the actual \f(CW\*(C`PerlIOl *\*(C'\fR underneath | |
240 | changes. (Compare perl's \f(CW\*(C`SV *\*(C'\fR which remains constant while its | |
241 | \&\f(CW\*(C`sv_any\*(C'\fR field changes as the scalar's type changes.) An \s-1IO\s0 stream is | |
242 | then in general represented as a pointer to this linked-list of | |
243 | \&\*(L"layers\*(R". | |
244 | .PP | |
245 | It should be noted that because of the double indirection in a \f(CW\*(C`PerlIO *\*(C'\fR, | |
246 | a \f(CW\*(C`&(perlio\->next)\*(C'\fR \*(L"is\*(R" a \f(CW\*(C`PerlIO *\*(C'\fR, and so to some degree | |
247 | at least one layer can use the \*(L"standard\*(R" \s-1API\s0 on the next layer down. | |
248 | .PP | |
249 | A \*(L"layer\*(R" is composed of two parts: | |
250 | .IP "1." 4 | |
251 | The functions and attributes of the \*(L"layer class\*(R". | |
252 | .IP "2." 4 | |
253 | The per-instance data for a particular handle. | |
254 | .Sh "Functions and Attributes" | |
255 | .IX Subsection "Functions and Attributes" | |
256 | The functions and attributes are accessed via the \*(L"tab\*(R" (for table) | |
257 | member of \f(CW\*(C`PerlIOl\*(C'\fR. The functions (methods of the layer \*(L"class\*(R") are | |
258 | fixed, and are defined by the \f(CW\*(C`PerlIO_funcs\*(C'\fR type. They are broadly the | |
259 | same as the public \f(CW\*(C`PerlIO_xxxxx\*(C'\fR functions: | |
260 | .PP | |
261 | .Vb 39 | |
262 | \& struct _PerlIO_funcs | |
263 | \& { | |
264 | \& Size_t fsize; | |
265 | \& char * name; | |
266 | \& Size_t size; | |
267 | \& IV kind; | |
268 | \& IV (*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg, PerlIO_funcs *tab); | |
269 | \& IV (*Popped)(pTHX_ PerlIO *f); | |
270 | \& PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, | |
271 | \& AV *layers, IV n, | |
272 | \& const char *mode, | |
273 | \& int fd, int imode, int perm, | |
274 | \& PerlIO *old, | |
275 | \& int narg, SV **args); | |
276 | \& IV (*Binmode)(pTHX_ PerlIO *f); | |
277 | \& SV * (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags) | |
278 | \& IV (*Fileno)(pTHX_ PerlIO *f); | |
279 | \& PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flags) | |
280 | \& /* Unix-like functions - cf sfio line disciplines */ | |
281 | \& SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count); | |
282 | \& SSize_t (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count); | |
283 | \& SSize_t (*Write)(pTHX_ PerlIO *f, const void *vbuf, Size_t count); | |
284 | \& IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence); | |
285 | \& Off_t (*Tell)(pTHX_ PerlIO *f); | |
286 | \& IV (*Close)(pTHX_ PerlIO *f); | |
287 | \& /* Stdio-like buffered IO functions */ | |
288 | \& IV (*Flush)(pTHX_ PerlIO *f); | |
289 | \& IV (*Fill)(pTHX_ PerlIO *f); | |
290 | \& IV (*Eof)(pTHX_ PerlIO *f); | |
291 | \& IV (*Error)(pTHX_ PerlIO *f); | |
292 | \& void (*Clearerr)(pTHX_ PerlIO *f); | |
293 | \& void (*Setlinebuf)(pTHX_ PerlIO *f); | |
294 | \& /* Perl's snooping functions */ | |
295 | \& STDCHAR * (*Get_base)(pTHX_ PerlIO *f); | |
296 | \& Size_t (*Get_bufsiz)(pTHX_ PerlIO *f); | |
297 | \& STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f); | |
298 | \& SSize_t (*Get_cnt)(pTHX_ PerlIO *f); | |
299 | \& void (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt); | |
300 | \& }; | |
301 | .Ve | |
302 | .PP | |
303 | The first few members of the struct give a function table size for | |
304 | compatibility check \*(L"name\*(R" for the layer, the size to \f(CW\*(C`malloc\*(C'\fR for the per-instance data, | |
305 | and some flags which are attributes of the class as whole (such as whether it is a buffering | |
306 | layer), then follow the functions which fall into four basic groups: | |
307 | .IP "1." 4 | |
308 | Opening and setup functions | |
309 | .IP "2." 4 | |
310 | Basic \s-1IO\s0 operations | |
311 | .IP "3." 4 | |
312 | Stdio class buffering options. | |
313 | .IP "4." 4 | |
314 | Functions to support Perl's traditional \*(L"fast\*(R" access to the buffer. | |
315 | .PP | |
316 | A layer does not have to implement all the functions, but the whole | |
317 | table has to be present. Unimplemented slots can be \s-1NULL\s0 (which will | |
318 | result in an error when called) or can be filled in with stubs to | |
319 | \&\*(L"inherit\*(R" behaviour from a \*(L"base class\*(R". This \*(L"inheritance\*(R" is fixed | |
320 | for all instances of the layer, but as the layer chooses which stubs | |
321 | to populate the table, limited \*(L"multiple inheritance\*(R" is possible. | |
322 | .Sh "Per-instance Data" | |
323 | .IX Subsection "Per-instance Data" | |
324 | The per-instance data are held in memory beyond the basic PerlIOl | |
325 | struct, by making a PerlIOl the first member of the layer's struct | |
326 | thus: | |
327 | .PP | |
328 | .Vb 10 | |
329 | \& typedef struct | |
330 | \& { | |
331 | \& struct _PerlIO base; /* Base "class" info */ | |
332 | \& STDCHAR * buf; /* Start of buffer */ | |
333 | \& STDCHAR * end; /* End of valid part of buffer */ | |
334 | \& STDCHAR * ptr; /* Current position in buffer */ | |
335 | \& Off_t posn; /* Offset of buf into the file */ | |
336 | \& Size_t bufsiz; /* Real size of buffer */ | |
337 | \& IV oneword; /* Emergency buffer */ | |
338 | \& } PerlIOBuf; | |
339 | .Ve | |
340 | .PP | |
341 | In this way (as for perl's scalars) a pointer to a PerlIOBuf can be | |
342 | treated as a pointer to a PerlIOl. | |
343 | .Sh "Layers in action." | |
344 | .IX Subsection "Layers in action." | |
345 | .Vb 8 | |
346 | \& table perlio unix | |
347 | \& | | | |
348 | \& +-----------+ +----------+ +--------+ | |
349 | \& PerlIO ->| |--->| next |--->| NULL | | |
350 | \& +-----------+ +----------+ +--------+ | |
351 | \& | | | buffer | | fd | | |
352 | \& +-----------+ | | +--------+ | |
353 | \& | | +----------+ | |
354 | .Ve | |
355 | .PP | |
356 | The above attempts to show how the layer scheme works in a simple case. | |
357 | The application's \f(CW\*(C`PerlIO *\*(C'\fR points to an entry in the table(s) | |
358 | representing open (allocated) handles. For example the first three slots | |
359 | in the table correspond to \f(CW\*(C`stdin\*(C'\fR,\f(CW\*(C`stdout\*(C'\fR and \f(CW\*(C`stderr\*(C'\fR. The table | |
360 | in turn points to the current \*(L"top\*(R" layer for the handle \- in this case | |
361 | an instance of the generic buffering layer \*(L"perlio\*(R". That layer in turn | |
362 | points to the next layer down \- in this case the lowlevel \*(L"unix\*(R" layer. | |
363 | .PP | |
364 | The above is roughly equivalent to a \*(L"stdio\*(R" buffered stream, but with | |
365 | much more flexibility: | |
366 | .IP "\(bu" 4 | |
367 | If Unix level \f(CW\*(C`read\*(C'\fR/\f(CW\*(C`write\*(C'\fR/\f(CW\*(C`lseek\*(C'\fR is not appropriate for (say) | |
368 | sockets then the \*(L"unix\*(R" layer can be replaced (at open time or even | |
369 | dynamically) with a \*(L"socket\*(R" layer. | |
370 | .IP "\(bu" 4 | |
371 | Different handles can have different buffering schemes. The \*(L"top\*(R" | |
372 | layer could be the \*(L"mmap\*(R" layer if reading disk files was quicker | |
373 | using \f(CW\*(C`mmap\*(C'\fR than \f(CW\*(C`read\*(C'\fR. An \*(L"unbuffered\*(R" stream can be implemented | |
374 | simply by not having a buffer layer. | |
375 | .IP "\(bu" 4 | |
376 | Extra layers can be inserted to process the data as it flows through. | |
377 | This was the driving need for including the scheme in perl 5.7.0+ \- we | |
378 | needed a mechanism to allow data to be translated between perl's | |
379 | internal encoding (conceptually at least Unicode as \s-1UTF\-8\s0), and the | |
380 | \&\*(L"native\*(R" format used by the system. This is provided by the | |
381 | \&\*(L":encoding(xxxx)\*(R" layer which typically sits above the buffering layer. | |
382 | .IP "\(bu" 4 | |
383 | A layer can be added that does \*(L"\en\*(R" to \s-1CRLF\s0 translation. This layer | |
384 | can be used on any platform, not just those that normally do such | |
385 | things. | |
386 | .Sh "Per-instance flag bits" | |
387 | .IX Subsection "Per-instance flag bits" | |
388 | The generic flag bits are a hybrid of \f(CW\*(C`O_XXXXX\*(C'\fR style flags deduced | |
389 | from the mode string passed to \f(CW\*(C`PerlIO_open()\*(C'\fR, and state bits for | |
390 | typical buffer layers. | |
391 | .IP "\s-1PERLIO_F_EOF\s0" 4 | |
392 | .IX Item "PERLIO_F_EOF" | |
393 | End of file. | |
394 | .IP "\s-1PERLIO_F_CANWRITE\s0" 4 | |
395 | .IX Item "PERLIO_F_CANWRITE" | |
396 | Writes are permitted, i.e. opened as \*(L"w\*(R" or \*(L"r+\*(R" or \*(L"a\*(R", etc. | |
397 | .IP "\s-1PERLIO_F_CANREAD\s0" 4 | |
398 | .IX Item "PERLIO_F_CANREAD" | |
399 | Reads are permitted i.e. opened \*(L"r\*(R" or \*(L"w+\*(R" (or even \*(L"a+\*(R" \- ick). | |
400 | .IP "\s-1PERLIO_F_ERROR\s0" 4 | |
401 | .IX Item "PERLIO_F_ERROR" | |
402 | An error has occurred (for \f(CW\*(C`PerlIO_error()\*(C'\fR). | |
403 | .IP "\s-1PERLIO_F_TRUNCATE\s0" 4 | |
404 | .IX Item "PERLIO_F_TRUNCATE" | |
405 | Truncate file suggested by open mode. | |
406 | .IP "\s-1PERLIO_F_APPEND\s0" 4 | |
407 | .IX Item "PERLIO_F_APPEND" | |
408 | All writes should be appends. | |
409 | .IP "\s-1PERLIO_F_CRLF\s0" 4 | |
410 | .IX Item "PERLIO_F_CRLF" | |
411 | Layer is performing Win32\-like \*(L"\en\*(R" mapped to \s-1CR\s0,LF for output and \s-1CR\s0,LF | |
412 | mapped to \*(L"\en\*(R" for input. Normally the provided \*(L"crlf\*(R" layer is the only | |
413 | layer that need bother about this. \f(CW\*(C`PerlIO_binmode()\*(C'\fR will mess with this | |
414 | flag rather than add/remove layers if the \f(CW\*(C`PERLIO_K_CANCRLF\*(C'\fR bit is set | |
415 | for the layers class. | |
416 | .IP "\s-1PERLIO_F_UTF8\s0" 4 | |
417 | .IX Item "PERLIO_F_UTF8" | |
418 | Data written to this layer should be \s-1UTF\-8\s0 encoded; data provided | |
419 | by this layer should be considered \s-1UTF\-8\s0 encoded. Can be set on any layer | |
420 | by \*(L":utf8\*(R" dummy layer. Also set on \*(L":encoding\*(R" layer. | |
421 | .IP "\s-1PERLIO_F_UNBUF\s0" 4 | |
422 | .IX Item "PERLIO_F_UNBUF" | |
423 | Layer is unbuffered \- i.e. write to next layer down should occur for | |
424 | each write to this layer. | |
425 | .IP "\s-1PERLIO_F_WRBUF\s0" 4 | |
426 | .IX Item "PERLIO_F_WRBUF" | |
427 | The buffer for this layer currently holds data written to it but not sent | |
428 | to next layer. | |
429 | .IP "\s-1PERLIO_F_RDBUF\s0" 4 | |
430 | .IX Item "PERLIO_F_RDBUF" | |
431 | The buffer for this layer currently holds unconsumed data read from | |
432 | layer below. | |
433 | .IP "\s-1PERLIO_F_LINEBUF\s0" 4 | |
434 | .IX Item "PERLIO_F_LINEBUF" | |
435 | Layer is line buffered. Write data should be passed to next layer down | |
436 | whenever a \*(L"\en\*(R" is seen. Any data beyond the \*(L"\en\*(R" should then be | |
437 | processed. | |
438 | .IP "\s-1PERLIO_F_TEMP\s0" 4 | |
439 | .IX Item "PERLIO_F_TEMP" | |
440 | File has been \f(CW\*(C`unlink()\*(C'\fRed, or should be deleted on \f(CW\*(C`close()\*(C'\fR. | |
441 | .IP "\s-1PERLIO_F_OPEN\s0" 4 | |
442 | .IX Item "PERLIO_F_OPEN" | |
443 | Handle is open. | |
444 | .IP "\s-1PERLIO_F_FASTGETS\s0" 4 | |
445 | .IX Item "PERLIO_F_FASTGETS" | |
446 | This instance of this layer supports the "fast \f(CW\*(C`gets\*(C'\fR" interface. | |
447 | Normally set based on \f(CW\*(C`PERLIO_K_FASTGETS\*(C'\fR for the class and by the | |
448 | existence of the function(s) in the table. However a class that | |
449 | normally provides that interface may need to avoid it on a | |
450 | particular instance. The \*(L"pending\*(R" layer needs to do this when | |
451 | it is pushed above a layer which does not support the interface. | |
452 | (Perl's \f(CW\*(C`sv_gets()\*(C'\fR does not expect the streams fast \f(CW\*(C`gets\*(C'\fR behaviour | |
453 | to change during one \*(L"get\*(R".) | |
454 | .Sh "Methods in Detail" | |
455 | .IX Subsection "Methods in Detail" | |
456 | .IP "fsize" 4 | |
457 | .IX Item "fsize" | |
458 | .Vb 1 | |
459 | \& Size_t fsize; | |
460 | .Ve | |
461 | .Sp | |
462 | Size of the function table. This is compared against the value PerlIO | |
463 | code \*(L"knows\*(R" as a compatibility check. Future versions \fImay\fR be able | |
464 | to tolerate layers compiled against an old version of the headers. | |
465 | .IP "name" 4 | |
466 | .IX Item "name" | |
467 | .Vb 1 | |
468 | \& char * name; | |
469 | .Ve | |
470 | .Sp | |
471 | The name of the layer whose \fIopen()\fR method Perl should invoke on | |
472 | \&\fIopen()\fR. For example if the layer is called \s-1APR\s0, you will call: | |
473 | .Sp | |
474 | .Vb 1 | |
475 | \& open $fh, ">:APR", ... | |
476 | .Ve | |
477 | .Sp | |
478 | and Perl knows that it has to invoke the \fIPerlIOAPR_open()\fR method | |
479 | implemented by the \s-1APR\s0 layer. | |
480 | .IP "size" 4 | |
481 | .IX Item "size" | |
482 | .Vb 1 | |
483 | \& Size_t size; | |
484 | .Ve | |
485 | .Sp | |
486 | The size of the per-instance data structure, e.g.: | |
487 | .Sp | |
488 | .Vb 1 | |
489 | \& sizeof(PerlIOAPR) | |
490 | .Ve | |
491 | .Sp | |
492 | If this field is zero then \f(CW\*(C`PerlIO_pushed\*(C'\fR does not malloc anything | |
493 | and assumes layer's Pushed function will do any required layer stack | |
494 | manipulation \- used to avoid malloc/free overhead for dummy layers. | |
495 | If the field is non-zero it must be at least the size of \f(CW\*(C`PerlIOl\*(C'\fR, | |
496 | \&\f(CW\*(C`PerlIO_pushed\*(C'\fR will allocate memory for the layer's data structures | |
497 | and link new layer onto the stream's stack. (If the layer's Pushed | |
498 | method returns an error indication the layer is popped again.) | |
499 | .IP "kind" 4 | |
500 | .IX Item "kind" | |
501 | .Vb 1 | |
502 | \& IV kind; | |
503 | .Ve | |
504 | .RS 4 | |
505 | .IP "* \s-1PERLIO_K_BUFFERED\s0" 4 | |
506 | .IX Item "PERLIO_K_BUFFERED" | |
507 | The layer is buffered. | |
508 | .IP "* \s-1PERLIO_K_RAW\s0" 4 | |
509 | .IX Item "PERLIO_K_RAW" | |
510 | The layer is acceptable to have in a binmode(\s-1FH\s0) stack \- i.e. it does not | |
511 | (or will configure itself not to) transform bytes passing through it. | |
512 | .IP "* \s-1PERLIO_K_CANCRLF\s0" 4 | |
513 | .IX Item "PERLIO_K_CANCRLF" | |
514 | Layer can translate between \*(L"\en\*(R" and \s-1CRLF\s0 line ends. | |
515 | .IP "* \s-1PERLIO_K_FASTGETS\s0" 4 | |
516 | .IX Item "PERLIO_K_FASTGETS" | |
517 | Layer allows buffer snooping. | |
518 | .IP "* \s-1PERLIO_K_MULTIARG\s0" 4 | |
519 | .IX Item "PERLIO_K_MULTIARG" | |
520 | Used when the layer's \fIopen()\fR accepts more arguments than usual. The | |
521 | extra arguments should come not before the \f(CW\*(C`MODE\*(C'\fR argument. When this | |
522 | flag is used it's up to the layer to validate the args. | |
523 | .RE | |
524 | .RS 4 | |
525 | .RE | |
526 | .IP "Pushed" 4 | |
527 | .IX Item "Pushed" | |
528 | .Vb 1 | |
529 | \& IV (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg); | |
530 | .Ve | |
531 | .Sp | |
532 | The only absolutely mandatory method. Called when the layer is pushed | |
533 | onto the stack. The \f(CW\*(C`mode\*(C'\fR argument may be \s-1NULL\s0 if this occurs | |
534 | post\-open. The \f(CW\*(C`arg\*(C'\fR will be non\-\f(CW\*(C`NULL\*(C'\fR if an argument string was | |
535 | passed. In most cases this should call \f(CW\*(C`PerlIOBase_pushed()\*(C'\fR to | |
536 | convert \f(CW\*(C`mode\*(C'\fR into the appropriate \f(CW\*(C`PERLIO_F_XXXXX\*(C'\fR flags in | |
537 | addition to any actions the layer itself takes. If a layer is not | |
538 | expecting an argument it need neither save the one passed to it, nor | |
539 | provide \f(CW\*(C`Getarg()\*(C'\fR (it could perhaps \f(CW\*(C`Perl_warn\*(C'\fR that the argument | |
540 | was un\-expected). | |
541 | .Sp | |
542 | Returns 0 on success. On failure returns \-1 and should set errno. | |
543 | .IP "Popped" 4 | |
544 | .IX Item "Popped" | |
545 | .Vb 1 | |
546 | \& IV (*Popped)(pTHX_ PerlIO *f); | |
547 | .Ve | |
548 | .Sp | |
549 | Called when the layer is popped from the stack. A layer will normally | |
550 | be popped after \f(CW\*(C`Close()\*(C'\fR is called. But a layer can be popped | |
551 | without being closed if the program is dynamically managing layers on | |
552 | the stream. In such cases \f(CW\*(C`Popped()\*(C'\fR should free any resources | |
553 | (buffers, translation tables, ...) not held directly in the layer's | |
554 | struct. It should also \f(CW\*(C`Unread()\*(C'\fR any unconsumed data that has been | |
555 | read and buffered from the layer below back to that layer, so that it | |
556 | can be re-provided to what ever is now above. | |
557 | .Sp | |
558 | Returns 0 on success and failure. If \f(CW\*(C`Popped()\*(C'\fR returns \fItrue\fR then | |
559 | \&\fIperlio.c\fR assumes that either the layer has popped itself, or the | |
560 | layer is super special and needs to be retained for other reasons. | |
561 | In most cases it should return \fIfalse\fR. | |
562 | .IP "Open" 4 | |
563 | .IX Item "Open" | |
564 | .Vb 1 | |
565 | \& PerlIO * (*Open)(...); | |
566 | .Ve | |
567 | .Sp | |
568 | The \f(CW\*(C`Open()\*(C'\fR method has lots of arguments because it combines the | |
569 | functions of perl's \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`PerlIO_open\*(C'\fR, perl's \f(CW\*(C`sysopen\*(C'\fR, | |
570 | \&\f(CW\*(C`PerlIO_fdopen\*(C'\fR and \f(CW\*(C`PerlIO_reopen\*(C'\fR. The full prototype is as | |
571 | follows: | |
572 | .Sp | |
573 | .Vb 6 | |
574 | \& PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, | |
575 | \& AV *layers, IV n, | |
576 | \& const char *mode, | |
577 | \& int fd, int imode, int perm, | |
578 | \& PerlIO *old, | |
579 | \& int narg, SV **args); | |
580 | .Ve | |
581 | .Sp | |
582 | Open should (perhaps indirectly) call \f(CW\*(C`PerlIO_allocate()\*(C'\fR to allocate | |
583 | a slot in the table and associate it with the layers information for | |
584 | the opened file, by calling \f(CW\*(C`PerlIO_push\*(C'\fR. The \fIlayers\fR \s-1AV\s0 is an | |
585 | array of all the layers destined for the \f(CW\*(C`PerlIO *\*(C'\fR, and any | |
586 | arguments passed to them, \fIn\fR is the index into that array of the | |
587 | layer being called. The macro \f(CW\*(C`PerlIOArg\*(C'\fR will return a (possibly | |
588 | \&\f(CW\*(C`NULL\*(C'\fR) \s-1SV\s0 * for the argument passed to the layer. | |
589 | .Sp | |
590 | The \fImode\fR string is an "\f(CW\*(C`fopen()\*(C'\fR\-like" string which would match | |
591 | the regular expression \f(CW\*(C`/^[I#]?[rwa]\e+?[bt]?$/\*(C'\fR. | |
592 | .Sp | |
593 | The \f(CW'I'\fR prefix is used during creation of \f(CW\*(C`stdin\*(C'\fR..\f(CW\*(C`stderr\*(C'\fR via | |
594 | special \f(CW\*(C`PerlIO_fdopen\*(C'\fR calls; the \f(CW'#'\fR prefix means that this is | |
595 | \&\f(CW\*(C`sysopen\*(C'\fR and that \fIimode\fR and \fIperm\fR should be passed to | |
596 | \&\f(CW\*(C`PerlLIO_open3\*(C'\fR; \f(CW'r'\fR means \fBr\fRead, \f(CW'w'\fR means \fBw\fRrite and | |
597 | \&\f(CW'a'\fR means \fBa\fRppend. The \f(CW'+'\fR suffix means that both reading and | |
598 | writing/appending are permitted. The \f(CW'b'\fR suffix means file should | |
599 | be binary, and \f(CW't'\fR means it is text. (Almost all layers should do | |
600 | the \s-1IO\s0 in binary mode, and ignore the b/t bits. The \f(CW\*(C`:crlf\*(C'\fR layer | |
601 | should be pushed to handle the distinction.) | |
602 | .Sp | |
603 | If \fIold\fR is not \f(CW\*(C`NULL\*(C'\fR then this is a \f(CW\*(C`PerlIO_reopen\*(C'\fR. Perl itself | |
604 | does not use this (yet?) and semantics are a little vague. | |
605 | .Sp | |
606 | If \fIfd\fR not negative then it is the numeric file descriptor \fIfd\fR, | |
607 | which will be open in a manner compatible with the supplied mode | |
608 | string, the call is thus equivalent to \f(CW\*(C`PerlIO_fdopen\*(C'\fR. In this case | |
609 | \&\fInargs\fR will be zero. | |
610 | .Sp | |
611 | If \fInargs\fR is greater than zero then it gives the number of arguments | |
612 | passed to \f(CW\*(C`open\*(C'\fR, otherwise it will be 1 if for example | |
613 | \&\f(CW\*(C`PerlIO_open\*(C'\fR was called. In simple cases SvPV_nolen(*args) is the | |
614 | pathname to open. | |
615 | .Sp | |
616 | Having said all that translation-only layers do not need to provide | |
617 | \&\f(CW\*(C`Open()\*(C'\fR at all, but rather leave the opening to a lower level layer | |
618 | and wait to be \*(L"pushed\*(R". If a layer does provide \f(CW\*(C`Open()\*(C'\fR it should | |
619 | normally call the \f(CW\*(C`Open()\*(C'\fR method of next layer down (if any) and | |
620 | then push itself on top if that succeeds. | |
621 | .Sp | |
622 | If \f(CW\*(C`PerlIO_push\*(C'\fR was performed and open has failed, it must | |
623 | \&\f(CW\*(C`PerlIO_pop\*(C'\fR itself, since if it's not, the layer won't be removed | |
624 | and may cause bad problems. | |
625 | .Sp | |
626 | Returns \f(CW\*(C`NULL\*(C'\fR on failure. | |
627 | .IP "Binmode" 4 | |
628 | .IX Item "Binmode" | |
629 | .Vb 1 | |
630 | \& IV (*Binmode)(pTHX_ PerlIO *f); | |
631 | .Ve | |
632 | .Sp | |
633 | Optional. Used when \f(CW\*(C`:raw\*(C'\fR layer is pushed (explicitly or as a result | |
634 | of binmode(\s-1FH\s0)). If not present layer will be popped. If present | |
635 | should configure layer as binary (or pop itself) and return 0. | |
636 | If it returns \-1 for error \f(CW\*(C`binmode\*(C'\fR will fail with layer | |
637 | still on the stack. | |
638 | .IP "Getarg" 4 | |
639 | .IX Item "Getarg" | |
640 | .Vb 2 | |
641 | \& SV * (*Getarg)(pTHX_ PerlIO *f, | |
642 | \& CLONE_PARAMS *param, int flags); | |
643 | .Ve | |
644 | .Sp | |
645 | Optional. If present should return an \s-1SV\s0 * representing the string | |
646 | argument passed to the layer when it was | |
647 | pushed. e.g. \*(L":encoding(ascii)\*(R" would return an SvPV with value | |
648 | \&\*(L"ascii\*(R". (\fIparam\fR and \fIflags\fR arguments can be ignored in most | |
649 | cases) | |
650 | .Sp | |
651 | \&\f(CW\*(C`Dup\*(C'\fR uses \f(CW\*(C`Getarg\*(C'\fR to retrieve the argument originally passed to | |
652 | \&\f(CW\*(C`Pushed\*(C'\fR, so you must implement this function if your layer has an | |
653 | extra argument to \f(CW\*(C`Pushed\*(C'\fR and will ever be \f(CW\*(C`Dup\*(C'\fRed. | |
654 | .IP "Fileno" 4 | |
655 | .IX Item "Fileno" | |
656 | .Vb 1 | |
657 | \& IV (*Fileno)(pTHX_ PerlIO *f); | |
658 | .Ve | |
659 | .Sp | |
660 | Returns the Unix/Posix numeric file descriptor for the handle. Normally | |
661 | \&\f(CW\*(C`PerlIOBase_fileno()\*(C'\fR (which just asks next layer down) will suffice | |
662 | for this. | |
663 | .Sp | |
664 | Returns \-1 on error, which is considered to include the case where the | |
665 | layer cannot provide such a file descriptor. | |
666 | .IP "Dup" 4 | |
667 | .IX Item "Dup" | |
668 | .Vb 2 | |
669 | \& PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, | |
670 | \& CLONE_PARAMS *param, int flags); | |
671 | .Ve | |
672 | .Sp | |
673 | \&\s-1XXX:\s0 Needs more docs. | |
674 | .Sp | |
675 | Used as part of the \*(L"clone\*(R" process when a thread is spawned (in which | |
676 | case param will be non\-NULL) and when a stream is being duplicated via | |
677 | \&'&' in the \f(CW\*(C`open\*(C'\fR. | |
678 | .Sp | |
679 | Similar to \f(CW\*(C`Open\*(C'\fR, returns PerlIO* on success, \f(CW\*(C`NULL\*(C'\fR on failure. | |
680 | .IP "Read" 4 | |
681 | .IX Item "Read" | |
682 | .Vb 1 | |
683 | \& SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count); | |
684 | .Ve | |
685 | .Sp | |
686 | Basic read operation. | |
687 | .Sp | |
688 | Typically will call \f(CW\*(C`Fill\*(C'\fR and manipulate pointers (possibly via the | |
689 | \&\s-1API\s0). \f(CW\*(C`PerlIOBuf_read()\*(C'\fR may be suitable for derived classes which | |
690 | provide \*(L"fast gets\*(R" methods. | |
691 | .Sp | |
692 | Returns actual bytes read, or \-1 on an error. | |
693 | .IP "Unread" 4 | |
694 | .IX Item "Unread" | |
695 | .Vb 2 | |
696 | \& SSize_t (*Unread)(pTHX_ PerlIO *f, | |
697 | \& const void *vbuf, Size_t count); | |
698 | .Ve | |
699 | .Sp | |
700 | A superset of stdio's \f(CW\*(C`ungetc()\*(C'\fR. Should arrange for future reads to | |
701 | see the bytes in \f(CW\*(C`vbuf\*(C'\fR. If there is no obviously better implementation | |
702 | then \f(CW\*(C`PerlIOBase_unread()\*(C'\fR provides the function by pushing a \*(L"fake\*(R" | |
703 | \&\*(L"pending\*(R" layer above the calling layer. | |
704 | .Sp | |
705 | Returns the number of unread chars. | |
706 | .IP "Write" 4 | |
707 | .IX Item "Write" | |
708 | .Vb 1 | |
709 | \& SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count); | |
710 | .Ve | |
711 | .Sp | |
712 | Basic write operation. | |
713 | .Sp | |
714 | Returns bytes written or \-1 on an error. | |
715 | .IP "Seek" 4 | |
716 | .IX Item "Seek" | |
717 | .Vb 1 | |
718 | \& IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence); | |
719 | .Ve | |
720 | .Sp | |
721 | Position the file pointer. Should normally call its own \f(CW\*(C`Flush\*(C'\fR | |
722 | method and then the \f(CW\*(C`Seek\*(C'\fR method of next layer down. | |
723 | .Sp | |
724 | Returns 0 on success, \-1 on failure. | |
725 | .IP "Tell" 4 | |
726 | .IX Item "Tell" | |
727 | .Vb 1 | |
728 | \& Off_t (*Tell)(pTHX_ PerlIO *f); | |
729 | .Ve | |
730 | .Sp | |
731 | Return the file pointer. May be based on layers cached concept of | |
732 | position to avoid overhead. | |
733 | .Sp | |
734 | Returns \-1 on failure to get the file pointer. | |
735 | .IP "Close" 4 | |
736 | .IX Item "Close" | |
737 | .Vb 1 | |
738 | \& IV (*Close)(pTHX_ PerlIO *f); | |
739 | .Ve | |
740 | .Sp | |
741 | Close the stream. Should normally call \f(CW\*(C`PerlIOBase_close()\*(C'\fR to flush | |
742 | itself and close layers below, and then deallocate any data structures | |
743 | (buffers, translation tables, ...) not held directly in the data | |
744 | structure. | |
745 | .Sp | |
746 | Returns 0 on success, \-1 on failure. | |
747 | .IP "Flush" 4 | |
748 | .IX Item "Flush" | |
749 | .Vb 1 | |
750 | \& IV (*Flush)(pTHX_ PerlIO *f); | |
751 | .Ve | |
752 | .Sp | |
753 | Should make stream's state consistent with layers below. That is, any | |
754 | buffered write data should be written, and file position of lower layers | |
755 | adjusted for data read from below but not actually consumed. | |
756 | (Should perhaps \f(CW\*(C`Unread()\*(C'\fR such data to the lower layer.) | |
757 | .Sp | |
758 | Returns 0 on success, \-1 on failure. | |
759 | .IP "Fill" 4 | |
760 | .IX Item "Fill" | |
761 | .Vb 1 | |
762 | \& IV (*Fill)(pTHX_ PerlIO *f); | |
763 | .Ve | |
764 | .Sp | |
765 | The buffer for this layer should be filled (for read) from layer | |
766 | below. When you \*(L"subclass\*(R" PerlIOBuf layer, you want to use its | |
767 | \&\fI_read\fR method and to supply your own fill method, which fills the | |
768 | PerlIOBuf's buffer. | |
769 | .Sp | |
770 | Returns 0 on success, \-1 on failure. | |
771 | .IP "Eof" 4 | |
772 | .IX Item "Eof" | |
773 | .Vb 1 | |
774 | \& IV (*Eof)(pTHX_ PerlIO *f); | |
775 | .Ve | |
776 | .Sp | |
777 | Return end-of-file indicator. \f(CW\*(C`PerlIOBase_eof()\*(C'\fR is normally sufficient. | |
778 | .Sp | |
779 | Returns 0 on end\-of\-file, 1 if not end\-of\-file, \-1 on error. | |
780 | .IP "Error" 4 | |
781 | .IX Item "Error" | |
782 | .Vb 1 | |
783 | \& IV (*Error)(pTHX_ PerlIO *f); | |
784 | .Ve | |
785 | .Sp | |
786 | Return error indicator. \f(CW\*(C`PerlIOBase_error()\*(C'\fR is normally sufficient. | |
787 | .Sp | |
788 | Returns 1 if there is an error (usually when \f(CW\*(C`PERLIO_F_ERROR\*(C'\fR is set, | |
789 | 0 otherwise. | |
790 | .IP "Clearerr" 4 | |
791 | .IX Item "Clearerr" | |
792 | .Vb 1 | |
793 | \& void (*Clearerr)(pTHX_ PerlIO *f); | |
794 | .Ve | |
795 | .Sp | |
796 | Clear end-of-file and error indicators. Should call \f(CW\*(C`PerlIOBase_clearerr()\*(C'\fR | |
797 | to set the \f(CW\*(C`PERLIO_F_XXXXX\*(C'\fR flags, which may suffice. | |
798 | .IP "Setlinebuf" 4 | |
799 | .IX Item "Setlinebuf" | |
800 | .Vb 1 | |
801 | \& void (*Setlinebuf)(pTHX_ PerlIO *f); | |
802 | .Ve | |
803 | .Sp | |
804 | Mark the stream as line buffered. \f(CW\*(C`PerlIOBase_setlinebuf()\*(C'\fR sets the | |
805 | \&\s-1PERLIO_F_LINEBUF\s0 flag and is normally sufficient. | |
806 | .IP "Get_base" 4 | |
807 | .IX Item "Get_base" | |
808 | .Vb 1 | |
809 | \& STDCHAR * (*Get_base)(pTHX_ PerlIO *f); | |
810 | .Ve | |
811 | .Sp | |
812 | Allocate (if not already done so) the read buffer for this layer and | |
813 | return pointer to it. Return \s-1NULL\s0 on failure. | |
814 | .IP "Get_bufsiz" 4 | |
815 | .IX Item "Get_bufsiz" | |
816 | .Vb 1 | |
817 | \& Size_t (*Get_bufsiz)(pTHX_ PerlIO *f); | |
818 | .Ve | |
819 | .Sp | |
820 | Return the number of bytes that last \f(CW\*(C`Fill()\*(C'\fR put in the buffer. | |
821 | .IP "Get_ptr" 4 | |
822 | .IX Item "Get_ptr" | |
823 | .Vb 1 | |
824 | \& STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f); | |
825 | .Ve | |
826 | .Sp | |
827 | Return the current read pointer relative to this layer's buffer. | |
828 | .IP "Get_cnt" 4 | |
829 | .IX Item "Get_cnt" | |
830 | .Vb 1 | |
831 | \& SSize_t (*Get_cnt)(pTHX_ PerlIO *f); | |
832 | .Ve | |
833 | .Sp | |
834 | Return the number of bytes left to be read in the current buffer. | |
835 | .IP "Set_ptrcnt" 4 | |
836 | .IX Item "Set_ptrcnt" | |
837 | .Vb 2 | |
838 | \& void (*Set_ptrcnt)(pTHX_ PerlIO *f, | |
839 | \& STDCHAR *ptr, SSize_t cnt); | |
840 | .Ve | |
841 | .Sp | |
842 | Adjust the read pointer and count of bytes to match \f(CW\*(C`ptr\*(C'\fR and/or \f(CW\*(C`cnt\*(C'\fR. | |
843 | The application (or layer above) must ensure they are consistent. | |
844 | (Checking is allowed by the paranoid.) | |
845 | .Sh "Utilities" | |
846 | .IX Subsection "Utilities" | |
847 | To ask for the next layer down use PerlIONext(PerlIO *f). | |
848 | .PP | |
849 | To check that a PerlIO* is valid use PerlIOValid(PerlIO *f). (All | |
850 | this does is really just to check that the pointer is non-NULL and | |
851 | that the pointer behind that is non\-NULL.) | |
852 | .PP | |
853 | PerlIOBase(PerlIO *f) returns the \*(L"Base\*(R" pointer, or in other words, | |
854 | the \f(CW\*(C`PerlIOl*\*(C'\fR pointer. | |
855 | .PP | |
856 | PerlIOSelf(PerlIO* f, type) return the PerlIOBase cast to a type. | |
857 | .PP | |
858 | Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) either | |
859 | calls the \fIcallback\fR from the functions of the layer \fIf\fR (just by | |
860 | the name of the \s-1IO\s0 function, like \*(L"Read\*(R") with the \fIargs\fR, or if | |
861 | there is no such callback, calls the \fIbase\fR version of the callback | |
862 | with the same args, or if the f is invalid, set errno to \s-1EBADF\s0 and | |
863 | return \fIfailure\fR. | |
864 | .PP | |
865 | Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) either calls | |
866 | the \fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR, | |
867 | or if there is no such callback, set errno to \s-1EINVAL\s0. Or if the f is | |
868 | invalid, set errno to \s-1EBADF\s0 and return \fIfailure\fR. | |
869 | .PP | |
870 | Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) either calls | |
871 | the \fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR, | |
872 | or if there is no such callback, calls the \fIbase\fR version of the | |
873 | callback with the same args, or if the f is invalid, set errno to | |
874 | \&\s-1EBADF\s0. | |
875 | .PP | |
876 | Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) either calls the | |
877 | \&\fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR, or if | |
878 | there is no such callback, set errno to \s-1EINVAL\s0. Or if the f is | |
879 | invalid, set errno to \s-1EBADF\s0. | |
880 | .Sh "Implementing PerlIO Layers" | |
881 | .IX Subsection "Implementing PerlIO Layers" | |
882 | If you find the implementation document unclear or not sufficient, | |
883 | look at the existing PerlIO layer implementations, which include: | |
884 | .IP "* C implementations" 4 | |
885 | .IX Item "C implementations" | |
886 | The \fIperlio.c\fR and \fIperliol.h\fR in the Perl core implement the | |
887 | \&\*(L"unix\*(R", \*(L"perlio\*(R", \*(L"stdio\*(R", \*(L"crlf\*(R", \*(L"utf8\*(R", \*(L"byte\*(R", \*(L"raw\*(R", \*(L"pending\*(R" | |
888 | layers, and also the \*(L"mmap\*(R" and \*(L"win32\*(R" layers if applicable. | |
889 | (The \*(L"win32\*(R" is currently unfinished and unused, to see what is used | |
890 | instead in Win32, see \*(L"Querying the layers of filehandles\*(R" in PerlIO .) | |
891 | .Sp | |
892 | PerlIO::encoding, PerlIO::scalar, PerlIO::via in the Perl core. | |
893 | .Sp | |
894 | PerlIO::gzip and APR::PerlIO (mod_perl 2.0) on \s-1CPAN\s0. | |
895 | .IP "* Perl implementations" 4 | |
896 | .IX Item "Perl implementations" | |
897 | PerlIO::via::QuotedPrint in the Perl core and PerlIO::via::* on \s-1CPAN\s0. | |
898 | .PP | |
899 | If you are creating a PerlIO layer, you may want to be lazy, in other | |
900 | words, implement only the methods that interest you. The other methods | |
901 | you can either replace with the \*(L"blank\*(R" methods | |
902 | .PP | |
903 | .Vb 2 | |
904 | \& PerlIOBase_noop_ok | |
905 | \& PerlIOBase_noop_fail | |
906 | .Ve | |
907 | .PP | |
908 | (which do nothing, and return zero and \-1, respectively) or for | |
909 | certain methods you may assume a default behaviour by using a \s-1NULL\s0 | |
910 | method. The Open method looks for help in the 'parent' layer. | |
911 | The following table summarizes the behaviour: | |
912 | .PP | |
913 | .Vb 1 | |
914 | \& method behaviour with NULL | |
915 | .Ve | |
916 | .PP | |
917 | .Vb 24 | |
918 | \& Clearerr PerlIOBase_clearerr | |
919 | \& Close PerlIOBase_close | |
920 | \& Dup PerlIOBase_dup | |
921 | \& Eof PerlIOBase_eof | |
922 | \& Error PerlIOBase_error | |
923 | \& Fileno PerlIOBase_fileno | |
924 | \& Fill FAILURE | |
925 | \& Flush SUCCESS | |
926 | \& Getarg SUCCESS | |
927 | \& Get_base FAILURE | |
928 | \& Get_bufsiz FAILURE | |
929 | \& Get_cnt FAILURE | |
930 | \& Get_ptr FAILURE | |
931 | \& Open INHERITED | |
932 | \& Popped SUCCESS | |
933 | \& Pushed SUCCESS | |
934 | \& Read PerlIOBase_read | |
935 | \& Seek FAILURE | |
936 | \& Set_cnt FAILURE | |
937 | \& Set_ptrcnt FAILURE | |
938 | \& Setlinebuf PerlIOBase_setlinebuf | |
939 | \& Tell FAILURE | |
940 | \& Unread PerlIOBase_unread | |
941 | \& Write FAILURE | |
942 | .Ve | |
943 | .PP | |
944 | .Vb 4 | |
945 | \& FAILURE Set errno (to EINVAL in UNIXish, to LIB$_INVARG in VMS) and | |
946 | \& return -1 (for numeric return values) or NULL (for pointers) | |
947 | \& INHERITED Inherited from the layer below | |
948 | \& SUCCESS Return 0 (for numeric return values) or a pointer | |
949 | .Ve | |
950 | .Sh "Core Layers" | |
951 | .IX Subsection "Core Layers" | |
952 | The file \f(CW\*(C`perlio.c\*(C'\fR provides the following layers: | |
953 | .ie n .IP """unix""" 4 | |
954 | .el .IP "``unix''" 4 | |
955 | .IX Item "unix" | |
956 | A basic non-buffered layer which calls Unix/POSIX \f(CW\*(C`read()\*(C'\fR, \f(CW\*(C`write()\*(C'\fR, | |
957 | \&\f(CW\*(C`lseek()\*(C'\fR, \f(CW\*(C`close()\*(C'\fR. No buffering. Even on platforms that distinguish | |
958 | between O_TEXT and O_BINARY this layer is always O_BINARY. | |
959 | .ie n .IP """perlio""" 4 | |
960 | .el .IP "``perlio''" 4 | |
961 | .IX Item "perlio" | |
962 | A very complete generic buffering layer which provides the whole of | |
963 | PerlIO \s-1API\s0. It is also intended to be used as a \*(L"base class\*(R" for other | |
964 | layers. (For example its \f(CW\*(C`Read()\*(C'\fR method is implemented in terms of | |
965 | the \f(CW\*(C`Get_cnt()\*(C'\fR/\f(CW\*(C`Get_ptr()\*(C'\fR/\f(CW\*(C`Set_ptrcnt()\*(C'\fR methods). | |
966 | .Sp | |
967 | \&\*(L"perlio\*(R" over \*(L"unix\*(R" provides a complete replacement for stdio as seen | |
968 | via PerlIO \s-1API\s0. This is the default for \s-1USE_PERLIO\s0 when system's stdio | |
969 | does not permit perl's \*(L"fast gets\*(R" access, and which do not | |
970 | distinguish between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR. | |
971 | .ie n .IP """stdio""" 4 | |
972 | .el .IP "``stdio''" 4 | |
973 | .IX Item "stdio" | |
974 | A layer which provides the PerlIO \s-1API\s0 via the layer scheme, but | |
975 | implements it by calling system's stdio. This is (currently) the default | |
976 | if system's stdio provides sufficient access to allow perl's \*(L"fast gets\*(R" | |
977 | access and which do not distinguish between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR. | |
978 | .ie n .IP """crlf""" 4 | |
979 | .el .IP "``crlf''" 4 | |
980 | .IX Item "crlf" | |
981 | A layer derived using \*(L"perlio\*(R" as a base class. It provides Win32\-like | |
982 | \&\*(L"\en\*(R" to \s-1CR\s0,LF translation. Can either be applied above \*(L"perlio\*(R" or serve | |
983 | as the buffer layer itself. \*(L"crlf\*(R" over \*(L"unix\*(R" is the default if system | |
984 | distinguishes between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR opens. (At some point | |
985 | \&\*(L"unix\*(R" will be replaced by a \*(L"native\*(R" Win32 \s-1IO\s0 layer on that platform, | |
986 | as Win32's read/write layer has various drawbacks.) The \*(L"crlf\*(R" layer is | |
987 | a reasonable model for a layer which transforms data in some way. | |
988 | .ie n .IP """mmap""" 4 | |
989 | .el .IP "``mmap''" 4 | |
990 | .IX Item "mmap" | |
991 | If Configure detects \f(CW\*(C`mmap()\*(C'\fR functions this layer is provided (with | |
992 | \&\*(L"perlio\*(R" as a \*(L"base\*(R") which does \*(L"read\*(R" operations by \fImmap()\fRing the | |
993 | file. Performance improvement is marginal on modern systems, so it is | |
994 | mainly there as a proof of concept. It is likely to be unbundled from | |
995 | the core at some point. The \*(L"mmap\*(R" layer is a reasonable model for a | |
996 | minimalist \*(L"derived\*(R" layer. | |
997 | .ie n .IP """pending""" 4 | |
998 | .el .IP "``pending''" 4 | |
999 | .IX Item "pending" | |
1000 | An \*(L"internal\*(R" derivative of \*(L"perlio\*(R" which can be used to provide | |
1001 | \&\fIUnread()\fR function for layers which have no buffer or cannot be | |
1002 | bothered. (Basically this layer's \f(CW\*(C`Fill()\*(C'\fR pops itself off the stack | |
1003 | and so resumes reading from layer below.) | |
1004 | .ie n .IP """raw""" 4 | |
1005 | .el .IP "``raw''" 4 | |
1006 | .IX Item "raw" | |
1007 | A dummy layer which never exists on the layer stack. Instead when | |
1008 | \&\*(L"pushed\*(R" it actually pops the stack removing itself, it then calls | |
1009 | Binmode function table entry on all the layers in the stack \- normally | |
1010 | this (via PerlIOBase_binmode) removes any layers which do not have | |
1011 | \&\f(CW\*(C`PERLIO_K_RAW\*(C'\fR bit set. Layers can modify that behaviour by defining | |
1012 | their own Binmode entry. | |
1013 | .ie n .IP """utf8""" 4 | |
1014 | .el .IP "``utf8''" 4 | |
1015 | .IX Item "utf8" | |
1016 | Another dummy layer. When pushed it pops itself and sets the | |
1017 | \&\f(CW\*(C`PERLIO_F_UTF8\*(C'\fR flag on the layer which was (and now is once more) | |
1018 | the top of the stack. | |
1019 | .PP | |
1020 | In addition \fIperlio.c\fR also provides a number of \f(CW\*(C`PerlIOBase_xxxx()\*(C'\fR | |
1021 | functions which are intended to be used in the table slots of classes | |
1022 | which do not need to do anything special for a particular method. | |
1023 | .Sh "Extension Layers" | |
1024 | .IX Subsection "Extension Layers" | |
1025 | Layers can made available by extension modules. When an unknown layer | |
1026 | is encountered the PerlIO code will perform the equivalent of : | |
1027 | .PP | |
1028 | .Vb 1 | |
1029 | \& use PerlIO 'layer'; | |
1030 | .Ve | |
1031 | .PP | |
1032 | Where \fIlayer\fR is the unknown layer. \fIPerlIO.pm\fR will then attempt to: | |
1033 | .PP | |
1034 | .Vb 1 | |
1035 | \& require PerlIO::layer; | |
1036 | .Ve | |
1037 | .PP | |
1038 | If after that process the layer is still not defined then the \f(CW\*(C`open\*(C'\fR | |
1039 | will fail. | |
1040 | .PP | |
1041 | The following extension layers are bundled with perl: | |
1042 | .ie n .IP """:encoding""" 4 | |
1043 | .el .IP "``:encoding''" 4 | |
1044 | .IX Item ":encoding" | |
1045 | .Vb 1 | |
1046 | \& use Encoding; | |
1047 | .Ve | |
1048 | .Sp | |
1049 | makes this layer available, although \fIPerlIO.pm\fR \*(L"knows\*(R" where to | |
1050 | find it. It is an example of a layer which takes an argument as it is | |
1051 | called thus: | |
1052 | .Sp | |
1053 | .Vb 1 | |
1054 | \& open( $fh, "<:encoding(iso-8859-7)", $pathname ); | |
1055 | .Ve | |
1056 | .ie n .IP """:scalar""" 4 | |
1057 | .el .IP "``:scalar''" 4 | |
1058 | .IX Item ":scalar" | |
1059 | Provides support for reading data from and writing data to a scalar. | |
1060 | .Sp | |
1061 | .Vb 1 | |
1062 | \& open( $fh, "+<:scalar", \e$scalar ); | |
1063 | .Ve | |
1064 | .Sp | |
1065 | When a handle is so opened, then reads get bytes from the string value | |
1066 | of \fI$scalar\fR, and writes change the value. In both cases the position | |
1067 | in \fI$scalar\fR starts as zero but can be altered via \f(CW\*(C`seek\*(C'\fR, and | |
1068 | determined via \f(CW\*(C`tell\*(C'\fR. | |
1069 | .Sp | |
1070 | Please note that this layer is implied when calling \fIopen()\fR thus: | |
1071 | .Sp | |
1072 | .Vb 1 | |
1073 | \& open( $fh, "+<", \e$scalar ); | |
1074 | .Ve | |
1075 | .ie n .IP """:via""" 4 | |
1076 | .el .IP "``:via''" 4 | |
1077 | .IX Item ":via" | |
1078 | Provided to allow layers to be implemented as Perl code. For instance: | |
1079 | .Sp | |
1080 | .Vb 2 | |
1081 | \& use PerlIO::via::StripHTML; | |
1082 | \& open( my $fh, "<:via(StripHTML)", "index.html" ); | |
1083 | .Ve | |
1084 | .Sp | |
1085 | See PerlIO::via for details. | |
1086 | .SH "TODO" | |
1087 | .IX Header "TODO" | |
1088 | Things that need to be done to improve this document. | |
1089 | .IP "\(bu" 4 | |
1090 | Explain how to make a valid fh without going through \fIopen()\fR(i.e. apply | |
1091 | a layer). For example if the file is not opened through perl, but we | |
1092 | want to get back a fh, like it was opened by Perl. | |
1093 | .Sp | |
1094 | How PerlIO_apply_layera fits in, where its docs, was it made public? | |
1095 | .Sp | |
1096 | Currently the example could be something like this: | |
1097 | .Sp | |
1098 | .Vb 8 | |
1099 | \& PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...) | |
1100 | \& { | |
1101 | \& char *mode; /* "w", "r", etc */ | |
1102 | \& const char *layers = ":APR"; /* the layer name */ | |
1103 | \& PerlIO *f = PerlIO_allocate(aTHX); | |
1104 | \& if (!f) { | |
1105 | \& return NULL; | |
1106 | \& } | |
1107 | .Ve | |
1108 | .Sp | |
1109 | .Vb 1 | |
1110 | \& PerlIO_apply_layers(aTHX_ f, mode, layers); | |
1111 | .Ve | |
1112 | .Sp | |
1113 | .Vb 5 | |
1114 | \& if (f) { | |
1115 | \& PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR); | |
1116 | \& /* fill in the st struct, as in _open() */ | |
1117 | \& st->file = file; | |
1118 | \& PerlIOBase(f)->flags |= PERLIO_F_OPEN; | |
1119 | .Ve | |
1120 | .Sp | |
1121 | .Vb 4 | |
1122 | \& return f; | |
1123 | \& } | |
1124 | \& return NULL; | |
1125 | \& } | |
1126 | .Ve | |
1127 | .IP "\(bu" 4 | |
1128 | fix/add the documentation in places marked as \s-1XXX\s0. | |
1129 | .IP "\(bu" 4 | |
1130 | The handling of errors by the layer is not specified. e.g. when $! | |
1131 | should be set explicitly, when the error handling should be just | |
1132 | delegated to the top layer. | |
1133 | .Sp | |
1134 | Probably give some hints on using \s-1\fISETERRNO\s0()\fR or pointers to where they | |
1135 | can be found. | |
1136 | .IP "\(bu" 4 | |
1137 | I think it would help to give some concrete examples to make it easier | |
1138 | to understand the \s-1API\s0. Of course I agree that the \s-1API\s0 has to be | |
1139 | concise, but since there is no second document that is more of a | |
1140 | guide, I think that it'd make it easier to start with the doc which is | |
1141 | an \s-1API\s0, but has examples in it in places where things are unclear, to | |
1142 | a person who is not a PerlIO guru (yet). |