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