[14489] | 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 perl6.
|
---|
| 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 | AV *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 lowlevel "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 | AV *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> AV 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 | Having said all that translation-only layers do not need to provide
|
---|
| 530 | C<Open()> at all, but rather leave the opening to a lower level layer
|
---|
| 531 | and wait to be "pushed". If a layer does provide C<Open()> it should
|
---|
| 532 | normally call the C<Open()> method of next layer down (if any) and
|
---|
| 533 | then push itself on top if that succeeds.
|
---|
| 534 |
|
---|
| 535 | If C<PerlIO_push> was performed and open has failed, it must
|
---|
| 536 | C<PerlIO_pop> itself, since if it's not, the layer won't be removed
|
---|
| 537 | and may cause bad problems.
|
---|
| 538 |
|
---|
| 539 | Returns C<NULL> on failure.
|
---|
| 540 |
|
---|
| 541 | =item Binmode
|
---|
| 542 |
|
---|
| 543 | IV (*Binmode)(pTHX_ PerlIO *f);
|
---|
| 544 |
|
---|
| 545 | Optional. Used when C<:raw> layer is pushed (explicitly or as a result
|
---|
| 546 | of binmode(FH)). If not present layer will be popped. If present
|
---|
| 547 | should configure layer as binary (or pop itself) and return 0.
|
---|
| 548 | If it returns -1 for error C<binmode> will fail with layer
|
---|
| 549 | still on the stack.
|
---|
| 550 |
|
---|
| 551 | =item Getarg
|
---|
| 552 |
|
---|
| 553 | SV * (*Getarg)(pTHX_ PerlIO *f,
|
---|
| 554 | CLONE_PARAMS *param, int flags);
|
---|
| 555 |
|
---|
| 556 | Optional. If present should return an SV * representing the string
|
---|
| 557 | argument passed to the layer when it was
|
---|
| 558 | pushed. e.g. ":encoding(ascii)" would return an SvPV with value
|
---|
| 559 | "ascii". (I<param> and I<flags> arguments can be ignored in most
|
---|
| 560 | cases)
|
---|
| 561 |
|
---|
| 562 | C<Dup> uses C<Getarg> to retrieve the argument originally passed to
|
---|
| 563 | C<Pushed>, so you must implement this function if your layer has an
|
---|
| 564 | extra argument to C<Pushed> and will ever be C<Dup>ed.
|
---|
| 565 |
|
---|
| 566 | =item Fileno
|
---|
| 567 |
|
---|
| 568 | IV (*Fileno)(pTHX_ PerlIO *f);
|
---|
| 569 |
|
---|
| 570 | Returns the Unix/Posix numeric file descriptor for the handle. Normally
|
---|
| 571 | C<PerlIOBase_fileno()> (which just asks next layer down) will suffice
|
---|
| 572 | for this.
|
---|
| 573 |
|
---|
| 574 | Returns -1 on error, which is considered to include the case where the
|
---|
| 575 | layer cannot provide such a file descriptor.
|
---|
| 576 |
|
---|
| 577 | =item Dup
|
---|
| 578 |
|
---|
| 579 | PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o,
|
---|
| 580 | CLONE_PARAMS *param, int flags);
|
---|
| 581 |
|
---|
| 582 | XXX: Needs more docs.
|
---|
| 583 |
|
---|
| 584 | Used as part of the "clone" process when a thread is spawned (in which
|
---|
| 585 | case param will be non-NULL) and when a stream is being duplicated via
|
---|
| 586 | '&' in the C<open>.
|
---|
| 587 |
|
---|
| 588 | Similar to C<Open>, returns PerlIO* on success, C<NULL> on failure.
|
---|
| 589 |
|
---|
| 590 | =item Read
|
---|
| 591 |
|
---|
| 592 | SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
|
---|
| 593 |
|
---|
| 594 | Basic read operation.
|
---|
| 595 |
|
---|
| 596 | Typically will call C<Fill> and manipulate pointers (possibly via the
|
---|
| 597 | API). C<PerlIOBuf_read()> may be suitable for derived classes which
|
---|
| 598 | provide "fast gets" methods.
|
---|
| 599 |
|
---|
| 600 | Returns actual bytes read, or -1 on an error.
|
---|
| 601 |
|
---|
| 602 | =item Unread
|
---|
| 603 |
|
---|
| 604 | SSize_t (*Unread)(pTHX_ PerlIO *f,
|
---|
| 605 | const void *vbuf, Size_t count);
|
---|
| 606 |
|
---|
| 607 | A superset of stdio's C<ungetc()>. Should arrange for future reads to
|
---|
| 608 | see the bytes in C<vbuf>. If there is no obviously better implementation
|
---|
| 609 | then C<PerlIOBase_unread()> provides the function by pushing a "fake"
|
---|
| 610 | "pending" layer above the calling layer.
|
---|
| 611 |
|
---|
| 612 | Returns the number of unread chars.
|
---|
| 613 |
|
---|
| 614 | =item Write
|
---|
| 615 |
|
---|
| 616 | SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);
|
---|
| 617 |
|
---|
| 618 | Basic write operation.
|
---|
| 619 |
|
---|
| 620 | Returns bytes written or -1 on an error.
|
---|
| 621 |
|
---|
| 622 | =item Seek
|
---|
| 623 |
|
---|
| 624 | IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
|
---|
| 625 |
|
---|
| 626 | Position the file pointer. Should normally call its own C<Flush>
|
---|
| 627 | method and then the C<Seek> method of next layer down.
|
---|
| 628 |
|
---|
| 629 | Returns 0 on success, -1 on failure.
|
---|
| 630 |
|
---|
| 631 | =item Tell
|
---|
| 632 |
|
---|
| 633 | Off_t (*Tell)(pTHX_ PerlIO *f);
|
---|
| 634 |
|
---|
| 635 | Return the file pointer. May be based on layers cached concept of
|
---|
| 636 | position to avoid overhead.
|
---|
| 637 |
|
---|
| 638 | Returns -1 on failure to get the file pointer.
|
---|
| 639 |
|
---|
| 640 | =item Close
|
---|
| 641 |
|
---|
| 642 | IV (*Close)(pTHX_ PerlIO *f);
|
---|
| 643 |
|
---|
| 644 | Close the stream. Should normally call C<PerlIOBase_close()> to flush
|
---|
| 645 | itself and close layers below, and then deallocate any data structures
|
---|
| 646 | (buffers, translation tables, ...) not held directly in the data
|
---|
| 647 | structure.
|
---|
| 648 |
|
---|
| 649 | Returns 0 on success, -1 on failure.
|
---|
| 650 |
|
---|
| 651 | =item Flush
|
---|
| 652 |
|
---|
| 653 | IV (*Flush)(pTHX_ PerlIO *f);
|
---|
| 654 |
|
---|
| 655 | Should make stream's state consistent with layers below. That is, any
|
---|
| 656 | buffered write data should be written, and file position of lower layers
|
---|
| 657 | adjusted for data read from below but not actually consumed.
|
---|
| 658 | (Should perhaps C<Unread()> such data to the lower layer.)
|
---|
| 659 |
|
---|
| 660 | Returns 0 on success, -1 on failure.
|
---|
| 661 |
|
---|
| 662 | =item Fill
|
---|
| 663 |
|
---|
| 664 | IV (*Fill)(pTHX_ PerlIO *f);
|
---|
| 665 |
|
---|
| 666 | The buffer for this layer should be filled (for read) from layer
|
---|
| 667 | below. When you "subclass" PerlIOBuf layer, you want to use its
|
---|
| 668 | I<_read> method and to supply your own fill method, which fills the
|
---|
| 669 | PerlIOBuf's buffer.
|
---|
| 670 |
|
---|
| 671 | Returns 0 on success, -1 on failure.
|
---|
| 672 |
|
---|
| 673 | =item Eof
|
---|
| 674 |
|
---|
| 675 | IV (*Eof)(pTHX_ PerlIO *f);
|
---|
| 676 |
|
---|
| 677 | Return end-of-file indicator. C<PerlIOBase_eof()> is normally sufficient.
|
---|
| 678 |
|
---|
| 679 | Returns 0 on end-of-file, 1 if not end-of-file, -1 on error.
|
---|
| 680 |
|
---|
| 681 | =item Error
|
---|
| 682 |
|
---|
| 683 | IV (*Error)(pTHX_ PerlIO *f);
|
---|
| 684 |
|
---|
| 685 | Return error indicator. C<PerlIOBase_error()> is normally sufficient.
|
---|
| 686 |
|
---|
| 687 | Returns 1 if there is an error (usually when C<PERLIO_F_ERROR> is set,
|
---|
| 688 | 0 otherwise.
|
---|
| 689 |
|
---|
| 690 | =item Clearerr
|
---|
| 691 |
|
---|
| 692 | void (*Clearerr)(pTHX_ PerlIO *f);
|
---|
| 693 |
|
---|
| 694 | Clear end-of-file and error indicators. Should call C<PerlIOBase_clearerr()>
|
---|
| 695 | to set the C<PERLIO_F_XXXXX> flags, which may suffice.
|
---|
| 696 |
|
---|
| 697 | =item Setlinebuf
|
---|
| 698 |
|
---|
| 699 | void (*Setlinebuf)(pTHX_ PerlIO *f);
|
---|
| 700 |
|
---|
| 701 | Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the
|
---|
| 702 | PERLIO_F_LINEBUF flag and is normally sufficient.
|
---|
| 703 |
|
---|
| 704 | =item Get_base
|
---|
| 705 |
|
---|
| 706 | STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
|
---|
| 707 |
|
---|
| 708 | Allocate (if not already done so) the read buffer for this layer and
|
---|
| 709 | return pointer to it. Return NULL on failure.
|
---|
| 710 |
|
---|
| 711 | =item Get_bufsiz
|
---|
| 712 |
|
---|
| 713 | Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
|
---|
| 714 |
|
---|
| 715 | Return the number of bytes that last C<Fill()> put in the buffer.
|
---|
| 716 |
|
---|
| 717 | =item Get_ptr
|
---|
| 718 |
|
---|
| 719 | STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);
|
---|
| 720 |
|
---|
| 721 | Return the current read pointer relative to this layer's buffer.
|
---|
| 722 |
|
---|
| 723 | =item Get_cnt
|
---|
| 724 |
|
---|
| 725 | SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
|
---|
| 726 |
|
---|
| 727 | Return the number of bytes left to be read in the current buffer.
|
---|
| 728 |
|
---|
| 729 | =item Set_ptrcnt
|
---|
| 730 |
|
---|
| 731 | void (*Set_ptrcnt)(pTHX_ PerlIO *f,
|
---|
| 732 | STDCHAR *ptr, SSize_t cnt);
|
---|
| 733 |
|
---|
| 734 | Adjust the read pointer and count of bytes to match C<ptr> and/or C<cnt>.
|
---|
| 735 | The application (or layer above) must ensure they are consistent.
|
---|
| 736 | (Checking is allowed by the paranoid.)
|
---|
| 737 |
|
---|
| 738 | =back
|
---|
| 739 |
|
---|
| 740 | =head2 Utilities
|
---|
| 741 |
|
---|
| 742 | To ask for the next layer down use PerlIONext(PerlIO *f).
|
---|
| 743 |
|
---|
| 744 | To check that a PerlIO* is valid use PerlIOValid(PerlIO *f). (All
|
---|
| 745 | this does is really just to check that the pointer is non-NULL and
|
---|
| 746 | that the pointer behind that is non-NULL.)
|
---|
| 747 |
|
---|
| 748 | PerlIOBase(PerlIO *f) returns the "Base" pointer, or in other words,
|
---|
| 749 | the C<PerlIOl*> pointer.
|
---|
| 750 |
|
---|
| 751 | PerlIOSelf(PerlIO* f, type) return the PerlIOBase cast to a type.
|
---|
| 752 |
|
---|
| 753 | Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) either
|
---|
| 754 | calls the I<callback> from the functions of the layer I<f> (just by
|
---|
| 755 | the name of the IO function, like "Read") with the I<args>, or if
|
---|
| 756 | there is no such callback, calls the I<base> version of the callback
|
---|
| 757 | with the same args, or if the f is invalid, set errno to EBADF and
|
---|
| 758 | return I<failure>.
|
---|
| 759 |
|
---|
| 760 | Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) either calls
|
---|
| 761 | the I<callback> of the functions of the layer I<f> with the I<args>,
|
---|
| 762 | or if there is no such callback, set errno to EINVAL. Or if the f is
|
---|
| 763 | invalid, set errno to EBADF and return I<failure>.
|
---|
| 764 |
|
---|
| 765 | Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) either calls
|
---|
| 766 | the I<callback> of the functions of the layer I<f> with the I<args>,
|
---|
| 767 | or if there is no such callback, calls the I<base> version of the
|
---|
| 768 | callback with the same args, or if the f is invalid, set errno to
|
---|
| 769 | EBADF.
|
---|
| 770 |
|
---|
| 771 | Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) either calls the
|
---|
| 772 | I<callback> of the functions of the layer I<f> with the I<args>, or if
|
---|
| 773 | there is no such callback, set errno to EINVAL. Or if the f is
|
---|
| 774 | invalid, set errno to EBADF.
|
---|
| 775 |
|
---|
| 776 | =head2 Implementing PerlIO Layers
|
---|
| 777 |
|
---|
| 778 | If you find the implementation document unclear or not sufficient,
|
---|
| 779 | look at the existing PerlIO layer implementations, which include:
|
---|
| 780 |
|
---|
| 781 | =over
|
---|
| 782 |
|
---|
| 783 | =item * C implementations
|
---|
| 784 |
|
---|
| 785 | The F<perlio.c> and F<perliol.h> in the Perl core implement the
|
---|
| 786 | "unix", "perlio", "stdio", "crlf", "utf8", "byte", "raw", "pending"
|
---|
| 787 | layers, and also the "mmap" and "win32" layers if applicable.
|
---|
| 788 | (The "win32" is currently unfinished and unused, to see what is used
|
---|
| 789 | instead in Win32, see L<PerlIO/"Querying the layers of filehandles"> .)
|
---|
| 790 |
|
---|
| 791 | PerlIO::encoding, PerlIO::scalar, PerlIO::via in the Perl core.
|
---|
| 792 |
|
---|
| 793 | PerlIO::gzip and APR::PerlIO (mod_perl 2.0) on CPAN.
|
---|
| 794 |
|
---|
| 795 | =item * Perl implementations
|
---|
| 796 |
|
---|
| 797 | PerlIO::via::QuotedPrint in the Perl core and PerlIO::via::* on CPAN.
|
---|
| 798 |
|
---|
| 799 | =back
|
---|
| 800 |
|
---|
| 801 | If you are creating a PerlIO layer, you may want to be lazy, in other
|
---|
| 802 | words, implement only the methods that interest you. The other methods
|
---|
| 803 | you can either replace with the "blank" methods
|
---|
| 804 |
|
---|
| 805 | PerlIOBase_noop_ok
|
---|
| 806 | PerlIOBase_noop_fail
|
---|
| 807 |
|
---|
| 808 | (which do nothing, and return zero and -1, respectively) or for
|
---|
| 809 | certain methods you may assume a default behaviour by using a NULL
|
---|
| 810 | method. The Open method looks for help in the 'parent' layer.
|
---|
| 811 | The following table summarizes the behaviour:
|
---|
| 812 |
|
---|
| 813 | method behaviour with NULL
|
---|
| 814 |
|
---|
| 815 | Clearerr PerlIOBase_clearerr
|
---|
| 816 | Close PerlIOBase_close
|
---|
| 817 | Dup PerlIOBase_dup
|
---|
| 818 | Eof PerlIOBase_eof
|
---|
| 819 | Error PerlIOBase_error
|
---|
| 820 | Fileno PerlIOBase_fileno
|
---|
| 821 | Fill FAILURE
|
---|
| 822 | Flush SUCCESS
|
---|
| 823 | Getarg SUCCESS
|
---|
| 824 | Get_base FAILURE
|
---|
| 825 | Get_bufsiz FAILURE
|
---|
| 826 | Get_cnt FAILURE
|
---|
| 827 | Get_ptr FAILURE
|
---|
| 828 | Open INHERITED
|
---|
| 829 | Popped SUCCESS
|
---|
| 830 | Pushed SUCCESS
|
---|
| 831 | Read PerlIOBase_read
|
---|
| 832 | Seek FAILURE
|
---|
| 833 | Set_cnt FAILURE
|
---|
| 834 | Set_ptrcnt FAILURE
|
---|
| 835 | Setlinebuf PerlIOBase_setlinebuf
|
---|
| 836 | Tell FAILURE
|
---|
| 837 | Unread PerlIOBase_unread
|
---|
| 838 | Write FAILURE
|
---|
| 839 |
|
---|
| 840 | FAILURE Set errno (to EINVAL in UNIXish, to LIB$_INVARG in VMS) and
|
---|
| 841 | return -1 (for numeric return values) or NULL (for pointers)
|
---|
| 842 | INHERITED Inherited from the layer below
|
---|
| 843 | SUCCESS Return 0 (for numeric return values) or a pointer
|
---|
| 844 |
|
---|
| 845 | =head2 Core Layers
|
---|
| 846 |
|
---|
| 847 | The file C<perlio.c> provides the following layers:
|
---|
| 848 |
|
---|
| 849 | =over 4
|
---|
| 850 |
|
---|
| 851 | =item "unix"
|
---|
| 852 |
|
---|
| 853 | A basic non-buffered layer which calls Unix/POSIX C<read()>, C<write()>,
|
---|
| 854 | C<lseek()>, C<close()>. No buffering. Even on platforms that distinguish
|
---|
| 855 | between O_TEXT and O_BINARY this layer is always O_BINARY.
|
---|
| 856 |
|
---|
| 857 | =item "perlio"
|
---|
| 858 |
|
---|
| 859 | A very complete generic buffering layer which provides the whole of
|
---|
| 860 | PerlIO API. It is also intended to be used as a "base class" for other
|
---|
| 861 | layers. (For example its C<Read()> method is implemented in terms of
|
---|
| 862 | the C<Get_cnt()>/C<Get_ptr()>/C<Set_ptrcnt()> methods).
|
---|
| 863 |
|
---|
| 864 | "perlio" over "unix" provides a complete replacement for stdio as seen
|
---|
| 865 | via PerlIO API. This is the default for USE_PERLIO when system's stdio
|
---|
| 866 | does not permit perl's "fast gets" access, and which do not
|
---|
| 867 | distinguish between C<O_TEXT> and C<O_BINARY>.
|
---|
| 868 |
|
---|
| 869 | =item "stdio"
|
---|
| 870 |
|
---|
| 871 | A layer which provides the PerlIO API via the layer scheme, but
|
---|
| 872 | implements it by calling system's stdio. This is (currently) the default
|
---|
| 873 | if system's stdio provides sufficient access to allow perl's "fast gets"
|
---|
| 874 | access and which do not distinguish between C<O_TEXT> and C<O_BINARY>.
|
---|
| 875 |
|
---|
| 876 | =item "crlf"
|
---|
| 877 |
|
---|
| 878 | A layer derived using "perlio" as a base class. It provides Win32-like
|
---|
| 879 | "\n" to CR,LF translation. Can either be applied above "perlio" or serve
|
---|
| 880 | as the buffer layer itself. "crlf" over "unix" is the default if system
|
---|
| 881 | distinguishes between C<O_TEXT> and C<O_BINARY> opens. (At some point
|
---|
| 882 | "unix" will be replaced by a "native" Win32 IO layer on that platform,
|
---|
| 883 | as Win32's read/write layer has various drawbacks.) The "crlf" layer is
|
---|
| 884 | a reasonable model for a layer which transforms data in some way.
|
---|
| 885 |
|
---|
| 886 | =item "mmap"
|
---|
| 887 |
|
---|
| 888 | If Configure detects C<mmap()> functions this layer is provided (with
|
---|
| 889 | "perlio" as a "base") which does "read" operations by mmap()ing the
|
---|
| 890 | file. Performance improvement is marginal on modern systems, so it is
|
---|
| 891 | mainly there as a proof of concept. It is likely to be unbundled from
|
---|
| 892 | the core at some point. The "mmap" layer is a reasonable model for a
|
---|
| 893 | minimalist "derived" layer.
|
---|
| 894 |
|
---|
| 895 | =item "pending"
|
---|
| 896 |
|
---|
| 897 | An "internal" derivative of "perlio" which can be used to provide
|
---|
| 898 | Unread() function for layers which have no buffer or cannot be
|
---|
| 899 | bothered. (Basically this layer's C<Fill()> pops itself off the stack
|
---|
| 900 | and so resumes reading from layer below.)
|
---|
| 901 |
|
---|
| 902 | =item "raw"
|
---|
| 903 |
|
---|
| 904 | A dummy layer which never exists on the layer stack. Instead when
|
---|
| 905 | "pushed" it actually pops the stack removing itself, it then calls
|
---|
| 906 | Binmode function table entry on all the layers in the stack - normally
|
---|
| 907 | this (via PerlIOBase_binmode) removes any layers which do not have
|
---|
| 908 | C<PERLIO_K_RAW> bit set. Layers can modify that behaviour by defining
|
---|
| 909 | their own Binmode entry.
|
---|
| 910 |
|
---|
| 911 | =item "utf8"
|
---|
| 912 |
|
---|
| 913 | Another dummy layer. When pushed it pops itself and sets the
|
---|
| 914 | C<PERLIO_F_UTF8> flag on the layer which was (and now is once more)
|
---|
| 915 | the top of the stack.
|
---|
| 916 |
|
---|
| 917 | =back
|
---|
| 918 |
|
---|
| 919 | In addition F<perlio.c> also provides a number of C<PerlIOBase_xxxx()>
|
---|
| 920 | functions which are intended to be used in the table slots of classes
|
---|
| 921 | which do not need to do anything special for a particular method.
|
---|
| 922 |
|
---|
| 923 | =head2 Extension Layers
|
---|
| 924 |
|
---|
| 925 | Layers can made available by extension modules. When an unknown layer
|
---|
| 926 | is encountered the PerlIO code will perform the equivalent of :
|
---|
| 927 |
|
---|
| 928 | use PerlIO 'layer';
|
---|
| 929 |
|
---|
| 930 | Where I<layer> is the unknown layer. F<PerlIO.pm> will then attempt to:
|
---|
| 931 |
|
---|
| 932 | require PerlIO::layer;
|
---|
| 933 |
|
---|
| 934 | If after that process the layer is still not defined then the C<open>
|
---|
| 935 | will fail.
|
---|
| 936 |
|
---|
| 937 | The following extension layers are bundled with perl:
|
---|
| 938 |
|
---|
| 939 | =over 4
|
---|
| 940 |
|
---|
| 941 | =item ":encoding"
|
---|
| 942 |
|
---|
| 943 | use Encoding;
|
---|
| 944 |
|
---|
| 945 | makes this layer available, although F<PerlIO.pm> "knows" where to
|
---|
| 946 | find it. It is an example of a layer which takes an argument as it is
|
---|
| 947 | called thus:
|
---|
| 948 |
|
---|
| 949 | open( $fh, "<:encoding(iso-8859-7)", $pathname );
|
---|
| 950 |
|
---|
| 951 | =item ":scalar"
|
---|
| 952 |
|
---|
| 953 | Provides support for reading data from and writing data to a scalar.
|
---|
| 954 |
|
---|
| 955 | open( $fh, "+<:scalar", \$scalar );
|
---|
| 956 |
|
---|
| 957 | When a handle is so opened, then reads get bytes from the string value
|
---|
| 958 | of I<$scalar>, and writes change the value. In both cases the position
|
---|
| 959 | in I<$scalar> starts as zero but can be altered via C<seek>, and
|
---|
| 960 | determined via C<tell>.
|
---|
| 961 |
|
---|
| 962 | Please note that this layer is implied when calling open() thus:
|
---|
| 963 |
|
---|
| 964 | open( $fh, "+<", \$scalar );
|
---|
| 965 |
|
---|
| 966 | =item ":via"
|
---|
| 967 |
|
---|
| 968 | Provided to allow layers to be implemented as Perl code. For instance:
|
---|
| 969 |
|
---|
| 970 | use PerlIO::via::StripHTML;
|
---|
| 971 | open( my $fh, "<:via(StripHTML)", "index.html" );
|
---|
| 972 |
|
---|
| 973 | See L<PerlIO::via> for details.
|
---|
| 974 |
|
---|
| 975 | =back
|
---|
| 976 |
|
---|
| 977 | =head1 TODO
|
---|
| 978 |
|
---|
| 979 | Things that need to be done to improve this document.
|
---|
| 980 |
|
---|
| 981 | =over
|
---|
| 982 |
|
---|
| 983 | =item *
|
---|
| 984 |
|
---|
| 985 | Explain how to make a valid fh without going through open()(i.e. apply
|
---|
| 986 | a layer). For example if the file is not opened through perl, but we
|
---|
| 987 | want to get back a fh, like it was opened by Perl.
|
---|
| 988 |
|
---|
| 989 | How PerlIO_apply_layera fits in, where its docs, was it made public?
|
---|
| 990 |
|
---|
| 991 | Currently the example could be something like this:
|
---|
| 992 |
|
---|
| 993 | PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...)
|
---|
| 994 | {
|
---|
| 995 | char *mode; /* "w", "r", etc */
|
---|
| 996 | const char *layers = ":APR"; /* the layer name */
|
---|
| 997 | PerlIO *f = PerlIO_allocate(aTHX);
|
---|
| 998 | if (!f) {
|
---|
| 999 | return NULL;
|
---|
| 1000 | }
|
---|
| 1001 |
|
---|
| 1002 | PerlIO_apply_layers(aTHX_ f, mode, layers);
|
---|
| 1003 |
|
---|
| 1004 | if (f) {
|
---|
| 1005 | PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR);
|
---|
| 1006 | /* fill in the st struct, as in _open() */
|
---|
| 1007 | st->file = file;
|
---|
| 1008 | PerlIOBase(f)->flags |= PERLIO_F_OPEN;
|
---|
| 1009 |
|
---|
| 1010 | return f;
|
---|
| 1011 | }
|
---|
| 1012 | return NULL;
|
---|
| 1013 | }
|
---|
| 1014 |
|
---|
| 1015 | =item *
|
---|
| 1016 |
|
---|
| 1017 | fix/add the documentation in places marked as XXX.
|
---|
| 1018 |
|
---|
| 1019 | =item *
|
---|
| 1020 |
|
---|
| 1021 | The handling of errors by the layer is not specified. e.g. when $!
|
---|
| 1022 | should be set explicitly, when the error handling should be just
|
---|
| 1023 | delegated to the top layer.
|
---|
| 1024 |
|
---|
| 1025 | Probably give some hints on using SETERRNO() or pointers to where they
|
---|
| 1026 | can be found.
|
---|
| 1027 |
|
---|
| 1028 | =item *
|
---|
| 1029 |
|
---|
| 1030 | I think it would help to give some concrete examples to make it easier
|
---|
| 1031 | to understand the API. Of course I agree that the API has to be
|
---|
| 1032 | concise, but since there is no second document that is more of a
|
---|
| 1033 | guide, I think that it'd make it easier to start with the doc which is
|
---|
| 1034 | an API, but has examples in it in places where things are unclear, to
|
---|
| 1035 | a person who is not a PerlIO guru (yet).
|
---|
| 1036 |
|
---|
| 1037 | =back
|
---|
| 1038 |
|
---|
| 1039 | =cut
|
---|