This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Integrate mainline
[perl5.git] / pod / perliol.pod
CommitLineData
50b80e25
NIS
1=head1 NAME
2
3perliol - C API for Perl's implementation of IO in Layers.
4
5=head1 SYNOPSIS
6
7 /* Defining a layer ... */
8 #include <perliol.h>
9
50b80e25
NIS
10=head1 DESCRIPTION
11
9d799145
NIS
12This document describes the behavior and implementation of the PerlIO
13abstraction described in L<perlapio> when C<USE_PERLIO> is defined (and
14C<USE_SFIO> is not).
50b80e25
NIS
15
16=head2 History and Background
17
9d799145
NIS
18The PerlIO abstraction was introduced in perl5.003_02 but languished as
19just an abstraction until perl5.7.0. However during that time a number
d1be9408 20of perl extensions switched to using it, so the API is mostly fixed to
9d799145 21maintain (source) compatibility.
50b80e25 22
9d799145
NIS
23The aim of the implementation is to provide the PerlIO API in a flexible
24and platform neutral manner. It is also a trial of an "Object Oriented
25C, with vtables" approach which may be applied to perl6.
50b80e25
NIS
26
27=head2 Layers vs Disciplines
28
9d799145
NIS
29Initial discussion of the ability to modify IO streams behaviour used
30the term "discipline" for the entities which were added. This came (I
31believe) from the use of the term in "sfio", which in turn borrowed it
32from "line disciplines" on Unix terminals. However, this document (and
33the C code) uses the term "layer".
34
1d11c889
JH
35This is, I hope, a natural term given the implementation, and should
36avoid connotations that are inherent in earlier uses of "discipline"
37for things which are rather different.
50b80e25
NIS
38
39=head2 Data Structures
40
41The basic data structure is a PerlIOl:
42
43 typedef struct _PerlIO PerlIOl;
44 typedef struct _PerlIO_funcs PerlIO_funcs;
45 typedef PerlIOl *PerlIO;
46
47 struct _PerlIO
48 {
49 PerlIOl * next; /* Lower layer */
50 PerlIO_funcs * tab; /* Functions for this layer */
51 IV flags; /* Various flags for state */
52 };
53
1d11c889
JH
54A C<PerlIOl *> is a pointer to the struct, and the I<application>
55level C<PerlIO *> is a pointer to a C<PerlIOl *> - i.e. a pointer
56to a pointer to the struct. This allows the application level C<PerlIO *>
57to remain constant while the actual C<PerlIOl *> underneath
58changes. (Compare perl's C<SV *> which remains constant while its
59C<sv_any> field changes as the scalar's type changes.) An IO stream is
60then in general represented as a pointer to this linked-list of
61"layers".
50b80e25 62
9d799145 63It should be noted that because of the double indirection in a C<PerlIO *>,
d4165bde 64a C<< &(perlio->next) >> "is" a C<PerlIO *>, and so to some degree
11e1c8f2 65at least one layer can use the "standard" API on the next layer down.
50b80e25
NIS
66
67A "layer" is composed of two parts:
68
69=over 4
70
210b36aa 71=item 1.
50b80e25 72
210b36aa
AMS
73The functions and attributes of the "layer class".
74
75=item 2.
76
77The per-instance data for a particular handle.
50b80e25
NIS
78
79=back
80
81=head2 Functions and Attributes
82
9d799145
NIS
83The functions and attributes are accessed via the "tab" (for table)
84member of C<PerlIOl>. The functions (methods of the layer "class") are
85fixed, and are defined by the C<PerlIO_funcs> type. They are broadly the
86same as the public C<PerlIO_xxxxx> functions:
50b80e25 87
b76cc8ba
NIS
88 struct _PerlIO_funcs
89 {
90 char * name;
91 Size_t size;
92 IV kind;
d4165bde
SB
93 IV (*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg);
94 IV (*Popped)(pTHX_ PerlIO *f);
b76cc8ba
NIS
95 PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab,
96 AV *layers, IV n,
97 const char *mode,
98 int fd, int imode, int perm,
99 PerlIO *old,
100 int narg, SV **args);
d4165bde
SB
101 SV * (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags)
102 IV (*Fileno)(pTHX_ PerlIO *f);
103 PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flags)
b76cc8ba 104 /* Unix-like functions - cf sfio line disciplines */
d4165bde
SB
105 SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
106 SSize_t (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
107 SSize_t (*Write)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
108 IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
109 Off_t (*Tell)(pTHX_ PerlIO *f);
110 IV (*Close)(pTHX_ PerlIO *f);
b76cc8ba 111 /* Stdio-like buffered IO functions */
d4165bde
SB
112 IV (*Flush)(pTHX_ PerlIO *f);
113 IV (*Fill)(pTHX_ PerlIO *f);
114 IV (*Eof)(pTHX_ PerlIO *f);
115 IV (*Error)(pTHX_ PerlIO *f);
116 void (*Clearerr)(pTHX_ PerlIO *f);
117 void (*Setlinebuf)(pTHX_ PerlIO *f);
b76cc8ba 118 /* Perl's snooping functions */
d4165bde
SB
119 STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
120 Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
121 STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);
122 SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
123 void (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt);
b76cc8ba
NIS
124 };
125
9d799145
NIS
126The first few members of the struct give a "name" for the layer, the
127size to C<malloc> for the per-instance data, and some flags which are
128attributes of the class as whole (such as whether it is a buffering
129layer), then follow the functions which fall into four basic groups:
50b80e25
NIS
130
131=over 4
132
aa500c9e 133=item 1.
50b80e25 134
aa500c9e 135Opening and setup functions
50b80e25 136
aa500c9e 137=item 2.
50b80e25 138
aa500c9e
RB
139Basic IO operations
140
141=item 3.
142
143Stdio class buffering options.
144
145=item 4.
146
147Functions to support Perl's traditional "fast" access to the buffer.
50b80e25
NIS
148
149=back
150
1d11c889
JH
151A layer does not have to implement all the functions, but the whole
152table has to be present. Unimplemented slots can be NULL (which will
153result in an error when called) or can be filled in with stubs to
154"inherit" behaviour from a "base class". This "inheritance" is fixed
155for all instances of the layer, but as the layer chooses which stubs
156to populate the table, limited "multiple inheritance" is possible.
50b80e25
NIS
157
158=head2 Per-instance Data
159
1d11c889
JH
160The per-instance data are held in memory beyond the basic PerlIOl
161struct, by making a PerlIOl the first member of the layer's struct
162thus:
50b80e25
NIS
163
164 typedef struct
165 {
166 struct _PerlIO base; /* Base "class" info */
167 STDCHAR * buf; /* Start of buffer */
168 STDCHAR * end; /* End of valid part of buffer */
169 STDCHAR * ptr; /* Current position in buffer */
170 Off_t posn; /* Offset of buf into the file */
171 Size_t bufsiz; /* Real size of buffer */
172 IV oneword; /* Emergency buffer */
173 } PerlIOBuf;
174
1d11c889
JH
175In this way (as for perl's scalars) a pointer to a PerlIOBuf can be
176treated as a pointer to a PerlIOl.
50b80e25
NIS
177
178=head2 Layers in action.
179
180 table perlio unix
181 | |
182 +-----------+ +----------+ +--------+
183 PerlIO ->| |--->| next |--->| NULL |
184 +-----------+ +----------+ +--------+
185 | | | buffer | | fd |
186 +-----------+ | | +--------+
187 | | +----------+
188
189
190The above attempts to show how the layer scheme works in a simple case.
9d799145
NIS
191The application's C<PerlIO *> points to an entry in the table(s)
192representing open (allocated) handles. For example the first three slots
193in the table correspond to C<stdin>,C<stdout> and C<stderr>. The table
194in turn points to the current "top" layer for the handle - in this case
195an instance of the generic buffering layer "perlio". That layer in turn
196points to the next layer down - in this case the lowlevel "unix" layer.
50b80e25 197
9d799145
NIS
198The above is roughly equivalent to a "stdio" buffered stream, but with
199much more flexibility:
50b80e25
NIS
200
201=over 4
202
203=item *
204
9d799145
NIS
205If Unix level C<read>/C<write>/C<lseek> is not appropriate for (say)
206sockets then the "unix" layer can be replaced (at open time or even
207dynamically) with a "socket" layer.
50b80e25
NIS
208
209=item *
210
1d11c889
JH
211Different handles can have different buffering schemes. The "top"
212layer could be the "mmap" layer if reading disk files was quicker
213using C<mmap> than C<read>. An "unbuffered" stream can be implemented
214simply by not having a buffer layer.
50b80e25
NIS
215
216=item *
217
218Extra layers can be inserted to process the data as it flows through.
9d799145 219This was the driving need for including the scheme in perl 5.7.0+ - we
d1be9408 220needed a mechanism to allow data to be translated between perl's
9d799145
NIS
221internal encoding (conceptually at least Unicode as UTF-8), and the
222"native" format used by the system. This is provided by the
223":encoding(xxxx)" layer which typically sits above the buffering layer.
50b80e25
NIS
224
225=item *
226
1d11c889
JH
227A layer can be added that does "\n" to CRLF translation. This layer
228can be used on any platform, not just those that normally do such
229things.
50b80e25
NIS
230
231=back
232
233=head2 Per-instance flag bits
234
1d11c889
JH
235The generic flag bits are a hybrid of C<O_XXXXX> style flags deduced
236from the mode string passed to C<PerlIO_open()>, and state bits for
237typical buffer layers.
50b80e25 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
d4165bde 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
5cb3728c
RB
325=item name
326
327 char * name;
d4165bde
SB
328
329The name of the layer whose open() method Perl should invoke on
330open(). For example if the layer is called APR, you will call:
331
332 open $fh, ">:APR", ...
333
334and Perl knows that it has to invoke the PerlIOAPR_open() method
335implemented by the APR layer.
336
5cb3728c
RB
337=item size
338
339 Size_t size;
d4165bde
SB
340
341The size of the per-instance data structure, e.g.:
342
343 sizeof(PerlIOAPR)
344
5cb3728c
RB
345=item kind
346
347 IV kind;
d4165bde
SB
348
349 XXX: explain all the available flags here
350
351=over 4
352
353=item * PERLIO_K_BUFFERED
354
355=item * PERLIO_K_CANCRLF
356
357=item * PERLIO_K_FASTGETS
358
359=item * PERLIO_K_MULTIARG
360
361Used when the layer's open() accepts more arguments than usual. The
362extra arguments should come not before the C<MODE> argument. When this
363flag is used it's up to the layer to validate the args.
364
365=item * PERLIO_K_RAW
366
367=back
368
5cb3728c
RB
369=item Pushed
370
371 IV (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg);
50b80e25 372
1d11c889
JH
373The only absolutely mandatory method. Called when the layer is pushed
374onto the stack. The C<mode> argument may be NULL if this occurs
375post-open. The C<arg> will be non-C<NULL> if an argument string was
376passed. In most cases this should call C<PerlIOBase_pushed()> to
377convert C<mode> into the appropriate C<PERLIO_F_XXXXX> flags in
378addition to any actions the layer itself takes. If a layer is not
379expecting an argument it need neither save the one passed to it, nor
380provide C<Getarg()> (it could perhaps C<Perl_warn> that the argument
381was un-expected).
50b80e25 382
d4165bde
SB
383Returns 0 on success. On failure returns -1 and should set errno.
384
5cb3728c
RB
385=item Popped
386
387 IV (*Popped)(pTHX_ PerlIO *f);
50b80e25 388
1d11c889
JH
389Called when the layer is popped from the stack. A layer will normally
390be popped after C<Close()> is called. But a layer can be popped
391without being closed if the program is dynamically managing layers on
392the stream. In such cases C<Popped()> should free any resources
393(buffers, translation tables, ...) not held directly in the layer's
394struct. It should also C<Unread()> any unconsumed data that has been
395read and buffered from the layer below back to that layer, so that it
396can be re-provided to what ever is now above.
b76cc8ba 397
d4165bde
SB
398Returns 0 on success and failure.
399
5cb3728c
RB
400=item Open
401
402 PerlIO * (*Open)(...);
b76cc8ba 403
1d11c889
JH
404The C<Open()> method has lots of arguments because it combines the
405functions of perl's C<open>, C<PerlIO_open>, perl's C<sysopen>,
406C<PerlIO_fdopen> and C<PerlIO_reopen>. The full prototype is as
407follows:
b76cc8ba
NIS
408
409 PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab,
410 AV *layers, IV n,
411 const char *mode,
412 int fd, int imode, int perm,
413 PerlIO *old,
414 int narg, SV **args);
415
1d11c889
JH
416Open should (perhaps indirectly) call C<PerlIO_allocate()> to allocate
417a slot in the table and associate it with the layers information for
418the opened file, by calling C<PerlIO_push>. The I<layers> AV is an
419array of all the layers destined for the C<PerlIO *>, and any
420arguments passed to them, I<n> is the index into that array of the
421layer being called. The macro C<PerlIOArg> will return a (possibly
422C<NULL>) SV * for the argument passed to the layer.
423
424The I<mode> string is an "C<fopen()>-like" string which would match
425the regular expression C</^[I#]?[rwa]\+?[bt]?$/>.
426
427The C<'I'> prefix is used during creation of C<stdin>..C<stderr> via
428special C<PerlIO_fdopen> calls; the C<'#'> prefix means that this is
429C<sysopen> and that I<imode> and I<perm> should be passed to
430C<PerlLIO_open3>; C<'r'> means B<r>ead, C<'w'> means B<w>rite and
431C<'a'> means B<a>ppend. The C<'+'> suffix means that both reading and
432writing/appending are permitted. The C<'b'> suffix means file should
433be binary, and C<'t'> means it is text. (Binary/Text should be ignored
434by almost all layers and binary IO done, with PerlIO. The C<:crlf>
435layer should be pushed to handle the distinction.)
436
437If I<old> is not C<NULL> then this is a C<PerlIO_reopen>. Perl itself
438does not use this (yet?) and semantics are a little vague.
439
440If I<fd> not negative then it is the numeric file descriptor I<fd>,
441which will be open in a manner compatible with the supplied mode
442string, the call is thus equivalent to C<PerlIO_fdopen>. In this case
443I<nargs> will be zero.
444
445If I<nargs> is greater than zero then it gives the number of arguments
446passed to C<open>, otherwise it will be 1 if for example
447C<PerlIO_open> was called. In simple cases SvPV_nolen(*args) is the
448pathname to open.
449
450Having said all that translation-only layers do not need to provide
451C<Open()> at all, but rather leave the opening to a lower level layer
452and wait to be "pushed". If a layer does provide C<Open()> it should
453normally call the C<Open()> method of next layer down (if any) and
454then push itself on top if that succeeds.
b76cc8ba 455
d4165bde
SB
456Returns C<NULL> on failure.
457
5cb3728c
RB
458=item Getarg
459
460 SV * (*Getarg)(pTHX_ PerlIO *f,
461 CLONE_PARAMS *param, int flags);
b76cc8ba 462
d4165bde
SB
463Optional. If present should return an SV * representing the string
464argument passed to the layer when it was
465pushed. e.g. ":encoding(ascii)" would return an SvPV with value
466"ascii". (I<param> and I<flags> arguments can be ignored in most
467cases)
b76cc8ba 468
5cb3728c
RB
469=item Fileno
470
471 IV (*Fileno)(pTHX_ PerlIO *f);
b76cc8ba 472
d1be9408 473Returns the Unix/Posix numeric file descriptor for the handle. Normally
b76cc8ba
NIS
474C<PerlIOBase_fileno()> (which just asks next layer down) will suffice
475for this.
50b80e25 476
d4165bde
SB
477Returns -1 if the layer cannot provide such a file descriptor, or in
478the case of the error.
479
480XXX: two possible results end up in -1, one is an error the other is
481not.
482
5cb3728c
RB
483=item Dup
484
485 PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o,
486 CLONE_PARAMS *param, int flags);
d4165bde
SB
487
488XXX: not documented
489
490Similar to C<Open>, returns PerlIO* on success, C<NULL> on failure.
491
5cb3728c
RB
492=item Read
493
494 SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
d4165bde
SB
495
496Basic read operation.
50b80e25 497
d4165bde
SB
498Typically will call C<Fill> and manipulate pointers (possibly via the
499API). C<PerlIOBuf_read()> may be suitable for derived classes which
500provide "fast gets" methods.
50b80e25 501
d4165bde
SB
502Returns actual bytes read, or -1 on an error.
503
5cb3728c
RB
504=item Unread
505
506 SSize_t (*Unread)(pTHX_ PerlIO *f,
507 const void *vbuf, Size_t count);
50b80e25 508
9d799145
NIS
509A superset of stdio's C<ungetc()>. Should arrange for future reads to
510see the bytes in C<vbuf>. If there is no obviously better implementation
511then C<PerlIOBase_unread()> provides the function by pushing a "fake"
512"pending" layer above the calling layer.
50b80e25 513
d4165bde
SB
514Returns the number of unread chars.
515
5cb3728c
RB
516=item Write
517
518 SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);
50b80e25 519
d4165bde 520Basic write operation.
50b80e25 521
d4165bde
SB
522Returns bytes written or -1 on an error.
523
5cb3728c
RB
524=item Seek
525
526 IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
50b80e25 527
1d11c889
JH
528Position the file pointer. Should normally call its own C<Flush>
529method and then the C<Seek> method of next layer down.
50b80e25 530
d4165bde
SB
531Returns 0 on success, -1 on failure.
532
5cb3728c
RB
533=item Tell
534
535 Off_t (*Tell)(pTHX_ PerlIO *f);
50b80e25 536
9d799145
NIS
537Return the file pointer. May be based on layers cached concept of
538position to avoid overhead.
50b80e25 539
d4165bde
SB
540Returns -1 on failure to get the file pointer.
541
5cb3728c
RB
542=item Close
543
544 IV (*Close)(pTHX_ PerlIO *f);
50b80e25 545
9d799145
NIS
546Close the stream. Should normally call C<PerlIOBase_close()> to flush
547itself and close layers below, and then deallocate any data structures
548(buffers, translation tables, ...) not held directly in the data
549structure.
50b80e25 550
d4165bde
SB
551Returns 0 on success, -1 on failure.
552
5cb3728c
RB
553=item Flush
554
555 IV (*Flush)(pTHX_ PerlIO *f);
50b80e25 556
9d799145
NIS
557Should make stream's state consistent with layers below. That is, any
558buffered write data should be written, and file position of lower layers
d1be9408 559adjusted for data read from below but not actually consumed.
b76cc8ba 560(Should perhaps C<Unread()> such data to the lower layer.)
50b80e25 561
d4165bde
SB
562Returns 0 on success, -1 on failure.
563
5cb3728c
RB
564=item Fill
565
566 IV (*Fill)(pTHX_ PerlIO *f);
d4165bde
SB
567
568The buffer for this layer should be filled (for read) from layer
569below. When you "subclass" PerlIOBuf layer, you want to use its
570I<_read> method and to supply your own fill method, which fills the
571PerlIOBuf's buffer.
50b80e25 572
d4165bde 573Returns 0 on success, -1 on failure.
50b80e25 574
5cb3728c
RB
575=item Eof
576
577 IV (*Eof)(pTHX_ PerlIO *f);
50b80e25 578
9d799145 579Return end-of-file indicator. C<PerlIOBase_eof()> is normally sufficient.
50b80e25 580
d4165bde
SB
581Returns 0 on end-of-file, 1 if not end-of-file, -1 on error.
582
5cb3728c
RB
583=item Error
584
585 IV (*Error)(pTHX_ PerlIO *f);
50b80e25 586
9d799145 587Return error indicator. C<PerlIOBase_error()> is normally sufficient.
50b80e25 588
d4165bde
SB
589Returns 1 if there is an error (usually when C<PERLIO_F_ERROR> is set,
5900 otherwise.
591
5cb3728c
RB
592=item Clearerr
593
594 void (*Clearerr)(pTHX_ PerlIO *f);
50b80e25 595
9d799145
NIS
596Clear end-of-file and error indicators. Should call C<PerlIOBase_clearerr()>
597to set the C<PERLIO_F_XXXXX> flags, which may suffice.
50b80e25 598
5cb3728c
RB
599=item Setlinebuf
600
601 void (*Setlinebuf)(pTHX_ PerlIO *f);
50b80e25 602
b76cc8ba
NIS
603Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the
604PERLIO_F_LINEBUF flag and is normally sufficient.
50b80e25 605
5cb3728c
RB
606=item Get_base
607
608 STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
50b80e25
NIS
609
610Allocate (if not already done so) the read buffer for this layer and
d4165bde 611return pointer to it. Return NULL on failure.
50b80e25 612
5cb3728c
RB
613=item Get_bufsiz
614
615 Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
50b80e25 616
9d799145 617Return the number of bytes that last C<Fill()> put in the buffer.
50b80e25 618
5cb3728c
RB
619=item Get_ptr
620
621 STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);
50b80e25 622
3039a93d 623Return the current read pointer relative to this layer's buffer.
50b80e25 624
5cb3728c
RB
625=item Get_cnt
626
627 SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
50b80e25
NIS
628
629Return the number of bytes left to be read in the current buffer.
630
5cb3728c
RB
631=item Set_ptrcnt
632
633 void (*Set_ptrcnt)(pTHX_ PerlIO *f,
634 STDCHAR *ptr, SSize_t cnt);
50b80e25
NIS
635
636Adjust the read pointer and count of bytes to match C<ptr> and/or C<cnt>.
637The application (or layer above) must ensure they are consistent.
638(Checking is allowed by the paranoid.)
639
640=back
641
642
643=head2 Core Layers
644
645The file C<perlio.c> provides the following layers:
646
647=over 4
648
649=item "unix"
650
9d799145
NIS
651A basic non-buffered layer which calls Unix/POSIX C<read()>, C<write()>,
652C<lseek()>, C<close()>. No buffering. Even on platforms that distinguish
653between O_TEXT and O_BINARY this layer is always O_BINARY.
50b80e25
NIS
654
655=item "perlio"
656
9d799145
NIS
657A very complete generic buffering layer which provides the whole of
658PerlIO API. It is also intended to be used as a "base class" for other
1d11c889
JH
659layers. (For example its C<Read()> method is implemented in terms of
660the C<Get_cnt()>/C<Get_ptr()>/C<Set_ptrcnt()> methods).
50b80e25 661
9d799145
NIS
662"perlio" over "unix" provides a complete replacement for stdio as seen
663via PerlIO API. This is the default for USE_PERLIO when system's stdio
1d11c889
JH
664does not permit perl's "fast gets" access, and which do not
665distinguish between C<O_TEXT> and C<O_BINARY>.
50b80e25
NIS
666
667=item "stdio"
668
9d799145
NIS
669A layer which provides the PerlIO API via the layer scheme, but
670implements it by calling system's stdio. This is (currently) the default
671if system's stdio provides sufficient access to allow perl's "fast gets"
672access and which do not distinguish between C<O_TEXT> and C<O_BINARY>.
50b80e25
NIS
673
674=item "crlf"
675
9d799145
NIS
676A layer derived using "perlio" as a base class. It provides Win32-like
677"\n" to CR,LF translation. Can either be applied above "perlio" or serve
678as the buffer layer itself. "crlf" over "unix" is the default if system
679distinguishes between C<O_TEXT> and C<O_BINARY> opens. (At some point
680"unix" will be replaced by a "native" Win32 IO layer on that platform,
681as Win32's read/write layer has various drawbacks.) The "crlf" layer is
682a reasonable model for a layer which transforms data in some way.
50b80e25
NIS
683
684=item "mmap"
685
9d799145
NIS
686If Configure detects C<mmap()> functions this layer is provided (with
687"perlio" as a "base") which does "read" operations by mmap()ing the
688file. Performance improvement is marginal on modern systems, so it is
689mainly there as a proof of concept. It is likely to be unbundled from
690the core at some point. The "mmap" layer is a reasonable model for a
691minimalist "derived" layer.
50b80e25
NIS
692
693=item "pending"
694
9d799145 695An "internal" derivative of "perlio" which can be used to provide
1d11c889
JH
696Unread() function for layers which have no buffer or cannot be
697bothered. (Basically this layer's C<Fill()> pops itself off the stack
698and so resumes reading from layer below.)
50b80e25
NIS
699
700=item "raw"
701
9d799145
NIS
702A dummy layer which never exists on the layer stack. Instead when
703"pushed" it actually pops the stack(!), removing itself, and any other
704layers until it reaches a layer with the class C<PERLIO_K_RAW> bit set.
50b80e25
NIS
705
706=item "utf8"
707
9d799145 708Another dummy layer. When pushed it pops itself and sets the
1d11c889
JH
709C<PERLIO_F_UTF8> flag on the layer which was (and now is once more)
710the top of the stack.
50b80e25
NIS
711
712=back
713
9d799145
NIS
714In addition F<perlio.c> also provides a number of C<PerlIOBase_xxxx()>
715functions which are intended to be used in the table slots of classes
716which do not need to do anything special for a particular method.
50b80e25
NIS
717
718=head2 Extension Layers
719
1d11c889
JH
720Layers can made available by extension modules. When an unknown layer
721is encountered the PerlIO code will perform the equivalent of :
b76cc8ba
NIS
722
723 use PerlIO 'layer';
724
1d11c889 725Where I<layer> is the unknown layer. F<PerlIO.pm> will then attempt to:
b76cc8ba
NIS
726
727 require PerlIO::layer;
728
1d11c889
JH
729If after that process the layer is still not defined then the C<open>
730will fail.
b76cc8ba
NIS
731
732The following extension layers are bundled with perl:
50b80e25
NIS
733
734=over 4
735
b76cc8ba 736=item ":encoding"
50b80e25
NIS
737
738 use Encoding;
739
1d11c889
JH
740makes this layer available, although F<PerlIO.pm> "knows" where to
741find it. It is an example of a layer which takes an argument as it is
742called thus:
50b80e25
NIS
743
744 open($fh,"<:encoding(iso-8859-7)",$pathname)
745
b76cc8ba
NIS
746=item ":Scalar"
747
748Provides support for
749
750 open($fh,"...",\$scalar)
50b80e25 751
1d11c889
JH
752When a handle is so opened, then reads get bytes from the string value
753of I<$scalar>, and writes change the value. In both cases the position
754in I<$scalar> starts as zero but can be altered via C<seek>, and
755determined via C<tell>.
b76cc8ba 756
4f7853f4 757=item ":Via"
b76cc8ba 758
4f7853f4
GA
759Provided to allow layers to be implemented as Perl code. For instance:
760
761 use MIME::QuotedPrint;
762 open(my $fh, ">Via(MIME::QuotedPrint)", "qp");
763
764See L<PerlIO::Via> for details.
b76cc8ba
NIS
765
766=back
50b80e25 767
d4165bde
SB
768=head1 TODO
769
770Things that need to be done to improve this document.
771
772=over
773
774=item *
775
776Explain how to make a valid fh without going through open()(i.e. apply
777a layer). For example if the file is not opened through perl, but we
778want to get back a fh, like it was opened by Perl.
779
780How PerlIO_apply_layera fits in, where its docs, was it made public?
781
782Currently the example could be something like this:
783
784 PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...)
785 {
786 char *mode; /* "w", "r", etc */
787 const char *layers = ":APR"; /* the layer name */
788 PerlIO *f = PerlIO_allocate(aTHX);
789 if (!f) {
790 return NULL;
791 }
792
793 PerlIO_apply_layers(aTHX_ f, mode, layers);
794
795 if (f) {
796 PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR);
797 /* fill in the st struct, as in _open() */
798 st->file = file;
799 PerlIOBase(f)->flags |= PERLIO_F_OPEN;
800
801 return f;
802 }
803 return NULL;
804 }
805
806=item *
807
808fix/add the documentation in places marked as XXX.
809
810=item *
811
812The handling of errors by the layer is not specified. e.g. when $!
813should be set explicitly, when the error handling should be just
814delegated to the top layer.
815
816Probably give some hints on using SETERRNO() or pointers to where they
817can be found.
818
819=item *
820
821I think it would help to give some concrete examples to make it easier
822to understand the API. Of course I agree that the API has to be
823concise, but since there is no second document that is more of a
824guide, I think that it'd make it easier to start with the doc which is
825an API, but has examples in it in places where things are unclear, to
826a person who is not a PerlIO guru (yet).
827
828=back
829
50b80e25
NIS
830=cut
831
832
833