This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[patch pod/perliol.pod] s/SvPV/SvPV_nolen/
[perl5.git] / pod / perliol.pod
CommitLineData
50b80e25
NIS
1
2=head1 NAME
3
4perliol - C API for Perl's implementation of IO in Layers.
5
6=head1 SYNOPSIS
7
8 /* Defining a layer ... */
9 #include <perliol.h>
10
11
12=head1 DESCRIPTION
13
9d799145
NIS
14This document describes the behavior and implementation of the PerlIO
15abstraction described in L<perlapio> when C<USE_PERLIO> is defined (and
16C<USE_SFIO> is not).
50b80e25
NIS
17
18=head2 History and Background
19
9d799145
NIS
20The PerlIO abstraction was introduced in perl5.003_02 but languished as
21just an abstraction until perl5.7.0. However during that time a number
d1be9408 22of perl extensions switched to using it, so the API is mostly fixed to
9d799145 23maintain (source) compatibility.
50b80e25 24
9d799145
NIS
25The aim of the implementation is to provide the PerlIO API in a flexible
26and platform neutral manner. It is also a trial of an "Object Oriented
27C, with vtables" approach which may be applied to perl6.
50b80e25
NIS
28
29=head2 Layers vs Disciplines
30
9d799145
NIS
31Initial discussion of the ability to modify IO streams behaviour used
32the term "discipline" for the entities which were added. This came (I
33believe) from the use of the term in "sfio", which in turn borrowed it
34from "line disciplines" on Unix terminals. However, this document (and
35the C code) uses the term "layer".
36
37This is, I hope, a natural term given the implementation, and should avoid
38connotations that are inherent in earlier uses of "discipline" for things
39which are rather different.
50b80e25
NIS
40
41=head2 Data Structures
42
43The basic data structure is a PerlIOl:
44
45 typedef struct _PerlIO PerlIOl;
46 typedef struct _PerlIO_funcs PerlIO_funcs;
47 typedef PerlIOl *PerlIO;
48
49 struct _PerlIO
50 {
51 PerlIOl * next; /* Lower layer */
52 PerlIO_funcs * tab; /* Functions for this layer */
53 IV flags; /* Various flags for state */
54 };
55
d1be9408 56A C<PerlIOl *> is a pointer to the struct, and the I<application> level
9d799145
NIS
57C<PerlIO *> is a pointer to a C<PerlIOl *> - i.e. a pointer to a pointer to
58the struct. This allows the application level C<PerlIO *> to remain
59constant while the actual C<PerlIOl *> underneath changes. (Compare perl's
60C<SV *> which remains constant while its C<sv_any> field changes as the
61scalar's type changes.) An IO stream is then in general represented as a
62pointer to this linked-list of "layers".
50b80e25 63
9d799145 64It should be noted that because of the double indirection in a C<PerlIO *>,
11e1c8f2
PP
65a C<< &(perlio-E<gt>next) >> "is" a C<PerlIO *>, and so to some degree
66at least one layer can use the "standard" API on the next layer down.
50b80e25
NIS
67
68A "layer" is composed of two parts:
69
70=over 4
71
210b36aa 72=item 1.
50b80e25 73
210b36aa
AMS
74The functions and attributes of the "layer class".
75
76=item 2.
77
78The per-instance data for a particular handle.
50b80e25
NIS
79
80=back
81
82=head2 Functions and Attributes
83
9d799145
NIS
84The functions and attributes are accessed via the "tab" (for table)
85member of C<PerlIOl>. The functions (methods of the layer "class") are
86fixed, and are defined by the C<PerlIO_funcs> type. They are broadly the
87same as the public C<PerlIO_xxxxx> functions:
50b80e25 88
b76cc8ba
NIS
89 struct _PerlIO_funcs
90 {
91 char * name;
92 Size_t size;
93 IV kind;
94 IV (*Pushed)(PerlIO *f,const char *mode,SV *arg);
95 IV (*Popped)(PerlIO *f);
96 PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab,
97 AV *layers, IV n,
98 const char *mode,
99 int fd, int imode, int perm,
100 PerlIO *old,
101 int narg, SV **args);
102 SV * (*Getarg)(PerlIO *f);
103 IV (*Fileno)(PerlIO *f);
104 /* Unix-like functions - cf sfio line disciplines */
105 SSize_t (*Read)(PerlIO *f, void *vbuf, Size_t count);
106 SSize_t (*Unread)(PerlIO *f, const void *vbuf, Size_t count);
107 SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);
108 IV (*Seek)(PerlIO *f, Off_t offset, int whence);
109 Off_t (*Tell)(PerlIO *f);
110 IV (*Close)(PerlIO *f);
111 /* Stdio-like buffered IO functions */
112 IV (*Flush)(PerlIO *f);
113 IV (*Fill)(PerlIO *f);
114 IV (*Eof)(PerlIO *f);
115 IV (*Error)(PerlIO *f);
116 void (*Clearerr)(PerlIO *f);
117 void (*Setlinebuf)(PerlIO *f);
118 /* Perl's snooping functions */
119 STDCHAR * (*Get_base)(PerlIO *f);
120 Size_t (*Get_bufsiz)(PerlIO *f);
121 STDCHAR * (*Get_ptr)(PerlIO *f);
122 SSize_t (*Get_cnt)(PerlIO *f);
123 void (*Set_ptrcnt)(PerlIO *f,STDCHAR *ptr,SSize_t cnt);
124 };
125
126
50b80e25 127
9d799145
NIS
128The first few members of the struct give a "name" for the layer, the
129size to C<malloc> for the per-instance data, and some flags which are
130attributes of the class as whole (such as whether it is a buffering
131layer), then follow the functions which fall into four basic groups:
50b80e25
NIS
132
133=over 4
134
aa500c9e 135=item 1.
50b80e25 136
aa500c9e 137Opening and setup functions
50b80e25 138
aa500c9e 139=item 2.
50b80e25 140
aa500c9e
RB
141Basic IO operations
142
143=item 3.
144
145Stdio class buffering options.
146
147=item 4.
148
149Functions to support Perl's traditional "fast" access to the buffer.
50b80e25
NIS
150
151=back
152
153A layer does not have to implement all the functions, but the whole table has
da75cd15 154to be present. Unimplemented slots can be NULL (which will result in an error
50b80e25
NIS
155when called) or can be filled in with stubs to "inherit" behaviour from
156a "base class". This "inheritance" is fixed for all instances of the layer,
157but as the layer chooses which stubs to populate the table, limited
158"multiple inheritance" is possible.
159
160=head2 Per-instance Data
161
162The per-instance data are held in memory beyond the basic PerlIOl struct,
163by making a PerlIOl the first member of the layer's struct thus:
164
165 typedef struct
166 {
167 struct _PerlIO base; /* Base "class" info */
168 STDCHAR * buf; /* Start of buffer */
169 STDCHAR * end; /* End of valid part of buffer */
170 STDCHAR * ptr; /* Current position in buffer */
171 Off_t posn; /* Offset of buf into the file */
172 Size_t bufsiz; /* Real size of buffer */
173 IV oneword; /* Emergency buffer */
174 } PerlIOBuf;
175
176In this way (as for perl's scalars) a pointer to a PerlIOBuf can be treated
177as a pointer to a PerlIOl.
178
179=head2 Layers in action.
180
181 table perlio unix
182 | |
183 +-----------+ +----------+ +--------+
184 PerlIO ->| |--->| next |--->| NULL |
185 +-----------+ +----------+ +--------+
186 | | | buffer | | fd |
187 +-----------+ | | +--------+
188 | | +----------+
189
190
191The above attempts to show how the layer scheme works in a simple case.
9d799145
NIS
192The application's C<PerlIO *> points to an entry in the table(s)
193representing open (allocated) handles. For example the first three slots
194in the table correspond to C<stdin>,C<stdout> and C<stderr>. The table
195in turn points to the current "top" layer for the handle - in this case
196an instance of the generic buffering layer "perlio". That layer in turn
197points to the next layer down - in this case the lowlevel "unix" layer.
50b80e25 198
9d799145
NIS
199The above is roughly equivalent to a "stdio" buffered stream, but with
200much more flexibility:
50b80e25
NIS
201
202=over 4
203
204=item *
205
9d799145
NIS
206If Unix level C<read>/C<write>/C<lseek> is not appropriate for (say)
207sockets then the "unix" layer can be replaced (at open time or even
208dynamically) with a "socket" layer.
50b80e25
NIS
209
210=item *
211
212Different handles can have different buffering schemes. The "top" layer
213could be the "mmap" layer if reading disk files was quicker using C<mmap>
214than C<read>. An "unbuffered" stream can be implemented simply by
215not having a buffer layer.
216
217=item *
218
219Extra layers can be inserted to process the data as it flows through.
9d799145 220This was the driving need for including the scheme in perl 5.7.0+ - we
d1be9408 221needed a mechanism to allow data to be translated between perl's
9d799145
NIS
222internal encoding (conceptually at least Unicode as UTF-8), and the
223"native" format used by the system. This is provided by the
224":encoding(xxxx)" layer which typically sits above the buffering layer.
50b80e25
NIS
225
226=item *
227
228A layer can be added that does "\n" to CRLF translation. This layer can be used
229on any platform, not just those that normally do such things.
230
231=back
232
233=head2 Per-instance flag bits
234
9d799145
NIS
235The generic flag bits are a hybrid of C<O_XXXXX> style flags deduced from
236the mode string passed to C<PerlIO_open()>, and state bits for typical buffer
50b80e25
NIS
237layers.
238
9d799145 239=over 4
50b80e25
NIS
240
241=item PERLIO_F_EOF
242
243End of file.
244
245=item PERLIO_F_CANWRITE
246
3039a93d 247Writes are permitted, i.e. opened as "w" or "r+" or "a", etc.
50b80e25
NIS
248
249=item PERLIO_F_CANREAD
250
3039a93d 251Reads are permitted i.e. opened "r" or "w+" (or even "a+" - ick).
50b80e25
NIS
252
253=item PERLIO_F_ERROR
254
d1be9408 255An error has occurred (for C<PerlIO_error()>)
50b80e25
NIS
256
257=item PERLIO_F_TRUNCATE
258
259Truncate file suggested by open mode.
260
261=item PERLIO_F_APPEND
262
263All writes should be appends.
264
265=item PERLIO_F_CRLF
266
11e1c8f2
PP
267Layer is performing Win32-like "\n" mapped to CR,LF for output and CR,LF
268mapped to "\n" for input. Normally the provided "crlf" layer is the only
269layer that need bother about this. C<PerlIO_binmode()> will mess with this
9d799145
NIS
270flag rather than add/remove layers if the C<PERLIO_K_CANCRLF> bit is set
271for the layers class.
50b80e25
NIS
272
273=item PERLIO_F_UTF8
274
3039a93d 275Data written to this layer should be UTF-8 encoded; data provided
50b80e25
NIS
276by this layer should be considered UTF-8 encoded. Can be set on any layer
277by ":utf8" dummy layer. Also set on ":encoding" layer.
278
279=item PERLIO_F_UNBUF
280
281Layer is unbuffered - i.e. write to next layer down should occur for
282each write to this layer.
283
284=item PERLIO_F_WRBUF
285
286The buffer for this layer currently holds data written to it but not sent
287to next layer.
288
289=item PERLIO_F_RDBUF
290
291The buffer for this layer currently holds unconsumed data read from
292layer below.
293
294=item PERLIO_F_LINEBUF
295
9d799145
NIS
296Layer is line buffered. Write data should be passed to next layer down
297whenever a "\n" is seen. Any data beyond the "\n" should then be
298processed.
50b80e25
NIS
299
300=item PERLIO_F_TEMP
301
9d799145 302File has been C<unlink()>ed, or should be deleted on C<close()>.
50b80e25
NIS
303
304=item PERLIO_F_OPEN
305
306Handle is open.
307
308=item PERLIO_F_FASTGETS
309
9d799145
NIS
310This instance of this layer supports the "fast C<gets>" interface.
311Normally set based on C<PERLIO_K_FASTGETS> for the class and by the
d1be9408 312existence of the function(s) in the table. However a class that
50b80e25
NIS
313normally provides that interface may need to avoid it on a
314particular instance. The "pending" layer needs to do this when
d1be9408 315it is pushed above a layer which does not support the interface.
9d799145 316(Perl's C<sv_gets()> does not expect the streams fast C<gets> behaviour
50b80e25
NIS
317to change during one "get".)
318
319=back
320
321=head2 Methods in Detail
322
323=over 4
324
b76cc8ba 325=item IV (*Pushed)(PerlIO *f,const char *mode, SV *arg);
50b80e25 326
d1be9408 327The only absolutely mandatory method. Called when the layer is pushed onto the stack.
b76cc8ba 328The C<mode> argument may be NULL if this occurs post-open. The C<arg> will be non-C<NULL>
9d799145
NIS
329if an argument string was passed. In most cases this should call
330C<PerlIOBase_pushed()> to convert C<mode> into the appropriate
331C<PERLIO_F_XXXXX> flags in addition to any actions the layer itself takes.
b76cc8ba
NIS
332If a layer is not expecting an argument it need neither save the one passed to it, nor
333provide C<Getarg()> (it could perhaps C<Perl_warn> that the argument was un-expected).
50b80e25
NIS
334
335=item IV (*Popped)(PerlIO *f);
336
9d799145
NIS
337Called when the layer is popped from the stack. A layer will normally be
338popped after C<Close()> is called. But a layer can be popped without being
339closed if the program is dynamically managing layers on the stream. In
340such cases C<Popped()> should free any resources (buffers, translation
341tables, ...) not held directly in the layer's struct.
b76cc8ba
NIS
342It should also C<Unread()> any unconsumed data that has been read and buffered
343from the layer below back to that layer, so that it can be re-provided to what
344ever is now above.
345
346=item PerlIO * (*Open)(...);
347
348The C<Open()> method has lots of arguments because it combines the functions
349of perl's C<open>, C<PerlIO_open>, perl's C<sysopen>, C<PerlIO_fdopen> and C<PerlIO_reopen>.
350The full prototype is as follows:
351
352 PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab,
353 AV *layers, IV n,
354 const char *mode,
355 int fd, int imode, int perm,
356 PerlIO *old,
357 int narg, SV **args);
358
359Open should (perhaps indirectly) call C<PerlIO_allocate()> to allocate a slot in the table and
360associate it with the layers information for the opened file, by calling C<PerlIO_push>.
361The I<layers> AV is an array of all the layers destined for the C<PerlIO *>,
362and any arguments passed to them, I<n> is the index into that array of the
363layer being called. The macro C<PerlIOArg> will return a (possibly C<NULL>) SV *
364for the argument passed to the layer.
365
366The I<mode> string is an "C<fopen()>-like" string which would match the regular
367expression C</^[I#]?[rwa]\+?[bt]?$/>.
368
369The C<'I'> prefix is used during creation of C<stdin>..C<stderr> via special
370C<PerlIO_fdopen> calls; the C<'#'> prefix means that this is C<sysopen> and that I<imode> and
371I<perm> should be passed to C<PerlLIO_open3>; C<'r'> means B<r>ead, C<'w'> means B<w>rite
372and C<'a'> means B<a>ppend. The C<'+'> suffix means that both reading and writing/appending
d1be9408 373are permitted. The C<'b'> suffix means file should be binary, and C<'t'> means it
b76cc8ba
NIS
374is text. (Binary/Text should be ignored by almost all layers and binary IO done,
375with PerlIO. The C<:crlf> layer should be pushed to handle the distinction.)
376
d1be9408 377If I<old> is not C<NULL> then this is a C<PerlIO_reopen>. Perl itself does not use
b76cc8ba
NIS
378this (yet?) and semantics are a little vague.
379
380If I<fd> not negative then it is the numeric file descriptor I<fd>, which will
d1be9408 381be open in a manner compatible with the supplied mode string, the call is
b76cc8ba
NIS
382thus equivalent to C<PerlIO_fdopen>. In this case I<nargs> will be zero.
383
384If I<nargs> is greater than zero then it gives the number of arguments passed
385to C<open>, otherwise it will be 1 if for example C<PerlIO_open> was called.
b42349cd 386In simple cases SvPV_nolen(*args) is the pathname to open.
b76cc8ba
NIS
387
388Having said all that translation-only layers do not need to provide C<Open()> at all,
389but rather leave the opening to a lower level layer and wait to be "pushed".
d1be9408 390If a layer does provide C<Open()> it should normally call the C<Open()> method
b76cc8ba
NIS
391of next layer down (if any) and then push itself on top if that succeeds.
392
393=item SV * (*Getarg)(PerlIO *f);
394
395Optional. If present should return an SV * representing the string argument
396passed to the layer when it was pushed. e.g. ":encoding(ascii)" would
397return an SvPV with value "ascii".
398
399=item IV (*Fileno)(PerlIO *f);
400
d1be9408 401Returns the Unix/Posix numeric file descriptor for the handle. Normally
b76cc8ba
NIS
402C<PerlIOBase_fileno()> (which just asks next layer down) will suffice
403for this.
50b80e25
NIS
404
405=item SSize_t (*Read)(PerlIO *f, void *vbuf, Size_t count);
406
407Basic read operation. Returns actual bytes read, or -1 on an error.
408Typically will call Fill and manipulate pointers (possibly via the API).
9d799145
NIS
409C<PerlIOBuf_read()> may be suitable for derived classes which provide
410"fast gets" methods.
50b80e25
NIS
411
412=item SSize_t (*Unread)(PerlIO *f, const void *vbuf, Size_t count);
413
9d799145
NIS
414A superset of stdio's C<ungetc()>. Should arrange for future reads to
415see the bytes in C<vbuf>. If there is no obviously better implementation
416then C<PerlIOBase_unread()> provides the function by pushing a "fake"
417"pending" layer above the calling layer.
50b80e25
NIS
418
419=item SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);
420
421Basic write operation. Returns bytes written or -1 on an error.
422
423=item IV (*Seek)(PerlIO *f, Off_t offset, int whence);
424
9d799145
NIS
425Position the file pointer. Should normally call its own C<Flush> method and
426then the C<Seek> method of next layer down.
50b80e25
NIS
427
428=item Off_t (*Tell)(PerlIO *f);
429
9d799145
NIS
430Return the file pointer. May be based on layers cached concept of
431position to avoid overhead.
50b80e25
NIS
432
433=item IV (*Close)(PerlIO *f);
434
9d799145
NIS
435Close the stream. Should normally call C<PerlIOBase_close()> to flush
436itself and close layers below, and then deallocate any data structures
437(buffers, translation tables, ...) not held directly in the data
438structure.
50b80e25
NIS
439
440=item IV (*Flush)(PerlIO *f);
441
9d799145
NIS
442Should make stream's state consistent with layers below. That is, any
443buffered write data should be written, and file position of lower layers
d1be9408 444adjusted for data read from below but not actually consumed.
b76cc8ba 445(Should perhaps C<Unread()> such data to the lower layer.)
50b80e25
NIS
446
447=item IV (*Fill)(PerlIO *f);
448
449The buffer for this layer should be filled (for read) from layer below.
450
451=item IV (*Eof)(PerlIO *f);
452
9d799145 453Return end-of-file indicator. C<PerlIOBase_eof()> is normally sufficient.
50b80e25
NIS
454
455=item IV (*Error)(PerlIO *f);
456
9d799145 457Return error indicator. C<PerlIOBase_error()> is normally sufficient.
50b80e25
NIS
458
459=item void (*Clearerr)(PerlIO *f);
460
9d799145
NIS
461Clear end-of-file and error indicators. Should call C<PerlIOBase_clearerr()>
462to set the C<PERLIO_F_XXXXX> flags, which may suffice.
50b80e25
NIS
463
464=item void (*Setlinebuf)(PerlIO *f);
465
b76cc8ba
NIS
466Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the
467PERLIO_F_LINEBUF flag and is normally sufficient.
50b80e25
NIS
468
469=item STDCHAR * (*Get_base)(PerlIO *f);
470
471Allocate (if not already done so) the read buffer for this layer and
472return pointer to it.
473
474=item Size_t (*Get_bufsiz)(PerlIO *f);
475
9d799145 476Return the number of bytes that last C<Fill()> put in the buffer.
50b80e25
NIS
477
478=item STDCHAR * (*Get_ptr)(PerlIO *f);
479
3039a93d 480Return the current read pointer relative to this layer's buffer.
50b80e25
NIS
481
482=item SSize_t (*Get_cnt)(PerlIO *f);
483
484Return the number of bytes left to be read in the current buffer.
485
486=item void (*Set_ptrcnt)(PerlIO *f,STDCHAR *ptr,SSize_t cnt);
487
488Adjust the read pointer and count of bytes to match C<ptr> and/or C<cnt>.
489The application (or layer above) must ensure they are consistent.
490(Checking is allowed by the paranoid.)
491
492=back
493
494
495=head2 Core Layers
496
497The file C<perlio.c> provides the following layers:
498
499=over 4
500
501=item "unix"
502
9d799145
NIS
503A basic non-buffered layer which calls Unix/POSIX C<read()>, C<write()>,
504C<lseek()>, C<close()>. No buffering. Even on platforms that distinguish
505between O_TEXT and O_BINARY this layer is always O_BINARY.
50b80e25
NIS
506
507=item "perlio"
508
9d799145
NIS
509A very complete generic buffering layer which provides the whole of
510PerlIO API. It is also intended to be used as a "base class" for other
511layers. (For example its C<Read()> method is implemented in terms of the
512C<Get_cnt()>/C<Get_ptr()>/C<Set_ptrcnt()> methods).
50b80e25 513
9d799145
NIS
514"perlio" over "unix" provides a complete replacement for stdio as seen
515via PerlIO API. This is the default for USE_PERLIO when system's stdio
516does not permit perl's "fast gets" access, and which do not distinguish
517between C<O_TEXT> and C<O_BINARY>.
50b80e25
NIS
518
519=item "stdio"
520
9d799145
NIS
521A layer which provides the PerlIO API via the layer scheme, but
522implements it by calling system's stdio. This is (currently) the default
523if system's stdio provides sufficient access to allow perl's "fast gets"
524access and which do not distinguish between C<O_TEXT> and C<O_BINARY>.
50b80e25
NIS
525
526=item "crlf"
527
9d799145
NIS
528A layer derived using "perlio" as a base class. It provides Win32-like
529"\n" to CR,LF translation. Can either be applied above "perlio" or serve
530as the buffer layer itself. "crlf" over "unix" is the default if system
531distinguishes between C<O_TEXT> and C<O_BINARY> opens. (At some point
532"unix" will be replaced by a "native" Win32 IO layer on that platform,
533as Win32's read/write layer has various drawbacks.) The "crlf" layer is
534a reasonable model for a layer which transforms data in some way.
50b80e25
NIS
535
536=item "mmap"
537
9d799145
NIS
538If Configure detects C<mmap()> functions this layer is provided (with
539"perlio" as a "base") which does "read" operations by mmap()ing the
540file. Performance improvement is marginal on modern systems, so it is
541mainly there as a proof of concept. It is likely to be unbundled from
542the core at some point. The "mmap" layer is a reasonable model for a
543minimalist "derived" layer.
50b80e25
NIS
544
545=item "pending"
546
9d799145
NIS
547An "internal" derivative of "perlio" which can be used to provide
548Unread() function for layers which have no buffer or cannot be bothered.
549(Basically this layer's C<Fill()> pops itself off the stack and so resumes
550reading from layer below.)
50b80e25
NIS
551
552=item "raw"
553
9d799145
NIS
554A dummy layer which never exists on the layer stack. Instead when
555"pushed" it actually pops the stack(!), removing itself, and any other
556layers until it reaches a layer with the class C<PERLIO_K_RAW> bit set.
50b80e25
NIS
557
558=item "utf8"
559
9d799145
NIS
560Another dummy layer. When pushed it pops itself and sets the
561C<PERLIO_F_UTF8> flag on the layer which was (and now is once more) the top
562of the stack.
50b80e25
NIS
563
564=back
565
9d799145
NIS
566In addition F<perlio.c> also provides a number of C<PerlIOBase_xxxx()>
567functions which are intended to be used in the table slots of classes
568which do not need to do anything special for a particular method.
50b80e25
NIS
569
570=head2 Extension Layers
571
b76cc8ba
NIS
572Layers can made available by extension modules. When an unknown layer is encountered
573the PerlIO code will perform the equivalent of :
574
575 use PerlIO 'layer';
576
577Where I<layer> is the unknown layer. F<PerlIO.pm> will then attempt to :
578
579 require PerlIO::layer;
580
581If after that process the layer is still not defined then the C<open> will fail.
582
583The following extension layers are bundled with perl:
50b80e25
NIS
584
585=over 4
586
b76cc8ba 587=item ":encoding"
50b80e25
NIS
588
589 use Encoding;
590
b76cc8ba
NIS
591makes this layer available, although F<PerlIO.pm> "knows" where to find it.
592It is an example of a layer which takes an argument as it is called thus:
50b80e25
NIS
593
594 open($fh,"<:encoding(iso-8859-7)",$pathname)
595
b76cc8ba
NIS
596=item ":Scalar"
597
598Provides support for
599
600 open($fh,"...",\$scalar)
50b80e25 601
b76cc8ba
NIS
602When a handle is so opened, then reads get bytes from the string value of I<$scalar>,
603and writes change the value. In both cases the position in I<$scalar> starts as zero
604but can be altered via C<seek>, and determined via C<tell>.
605
606=item ":Object" or ":Perl"
607
608May be provided to allow layers to be implemented as perl code - implementation
609is being investigated.
610
611=back
50b80e25
NIS
612
613=cut
614
615
616