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