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