| 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). |