This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Only modify LD_LIBRARY_PATH in case there are directories.
[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
d4165bde
SB
325=item char * name;
326
327The name of the layer whose open() method Perl should invoke on
328open(). For example if the layer is called APR, you will call:
329
330 open $fh, ">:APR", ...
331
332and Perl knows that it has to invoke the PerlIOAPR_open() method
333implemented by the APR layer.
334
335=item Size_t size;
336
337The size of the per-instance data structure, e.g.:
338
339 sizeof(PerlIOAPR)
340
341=item IV kind;
342
343 XXX: explain all the available flags here
344
345=over 4
346
347=item * PERLIO_K_BUFFERED
348
349=item * PERLIO_K_CANCRLF
350
351=item * PERLIO_K_FASTGETS
352
353=item * PERLIO_K_MULTIARG
354
355Used when the layer's open() accepts more arguments than usual. The
356extra arguments should come not before the C<MODE> argument. When this
357flag is used it's up to the layer to validate the args.
358
359=item * PERLIO_K_RAW
360
361=back
362
363=item IV (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg);
50b80e25 364
1d11c889
JH
365The only absolutely mandatory method. Called when the layer is pushed
366onto the stack. The C<mode> argument may be NULL if this occurs
367post-open. The C<arg> will be non-C<NULL> if an argument string was
368passed. In most cases this should call C<PerlIOBase_pushed()> to
369convert C<mode> into the appropriate C<PERLIO_F_XXXXX> flags in
370addition to any actions the layer itself takes. If a layer is not
371expecting an argument it need neither save the one passed to it, nor
372provide C<Getarg()> (it could perhaps C<Perl_warn> that the argument
373was un-expected).
50b80e25 374
d4165bde
SB
375Returns 0 on success. On failure returns -1 and should set errno.
376
377=item IV (*Popped)(pTHX_ PerlIO *f);
50b80e25 378
1d11c889
JH
379Called when the layer is popped from the stack. A layer will normally
380be popped after C<Close()> is called. But a layer can be popped
381without being closed if the program is dynamically managing layers on
382the stream. In such cases C<Popped()> should free any resources
383(buffers, translation tables, ...) not held directly in the layer's
384struct. It should also C<Unread()> any unconsumed data that has been
385read and buffered from the layer below back to that layer, so that it
386can be re-provided to what ever is now above.
b76cc8ba 387
d4165bde
SB
388Returns 0 on success and failure.
389
b76cc8ba
NIS
390=item PerlIO * (*Open)(...);
391
1d11c889
JH
392The C<Open()> method has lots of arguments because it combines the
393functions of perl's C<open>, C<PerlIO_open>, perl's C<sysopen>,
394C<PerlIO_fdopen> and C<PerlIO_reopen>. The full prototype is as
395follows:
b76cc8ba
NIS
396
397 PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab,
398 AV *layers, IV n,
399 const char *mode,
400 int fd, int imode, int perm,
401 PerlIO *old,
402 int narg, SV **args);
403
1d11c889
JH
404Open should (perhaps indirectly) call C<PerlIO_allocate()> to allocate
405a slot in the table and associate it with the layers information for
406the opened file, by calling C<PerlIO_push>. The I<layers> AV is an
407array of all the layers destined for the C<PerlIO *>, and any
408arguments passed to them, I<n> is the index into that array of the
409layer being called. The macro C<PerlIOArg> will return a (possibly
410C<NULL>) SV * for the argument passed to the layer.
411
412The I<mode> string is an "C<fopen()>-like" string which would match
413the regular expression C</^[I#]?[rwa]\+?[bt]?$/>.
414
415The C<'I'> prefix is used during creation of C<stdin>..C<stderr> via
416special C<PerlIO_fdopen> calls; the C<'#'> prefix means that this is
417C<sysopen> and that I<imode> and I<perm> should be passed to
418C<PerlLIO_open3>; C<'r'> means B<r>ead, C<'w'> means B<w>rite and
419C<'a'> means B<a>ppend. The C<'+'> suffix means that both reading and
420writing/appending are permitted. The C<'b'> suffix means file should
421be binary, and C<'t'> means it is text. (Binary/Text should be ignored
422by almost all layers and binary IO done, with PerlIO. The C<:crlf>
423layer should be pushed to handle the distinction.)
424
425If I<old> is not C<NULL> then this is a C<PerlIO_reopen>. Perl itself
426does not use this (yet?) and semantics are a little vague.
427
428If I<fd> not negative then it is the numeric file descriptor I<fd>,
429which will be open in a manner compatible with the supplied mode
430string, the call is thus equivalent to C<PerlIO_fdopen>. In this case
431I<nargs> will be zero.
432
433If I<nargs> is greater than zero then it gives the number of arguments
434passed to C<open>, otherwise it will be 1 if for example
435C<PerlIO_open> was called. In simple cases SvPV_nolen(*args) is the
436pathname to open.
437
438Having said all that translation-only layers do not need to provide
439C<Open()> at all, but rather leave the opening to a lower level layer
440and wait to be "pushed". If a layer does provide C<Open()> it should
441normally call the C<Open()> method of next layer down (if any) and
442then push itself on top if that succeeds.
b76cc8ba 443
d4165bde
SB
444Returns C<NULL> on failure.
445
446=item SV * (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags)
b76cc8ba 447
d4165bde
SB
448Optional. If present should return an SV * representing the string
449argument passed to the layer when it was
450pushed. e.g. ":encoding(ascii)" would return an SvPV with value
451"ascii". (I<param> and I<flags> arguments can be ignored in most
452cases)
b76cc8ba 453
d4165bde 454=item IV (*Fileno)(pTHX_ PerlIO *f);
b76cc8ba 455
d1be9408 456Returns the Unix/Posix numeric file descriptor for the handle. Normally
b76cc8ba
NIS
457C<PerlIOBase_fileno()> (which just asks next layer down) will suffice
458for this.
50b80e25 459
d4165bde
SB
460Returns -1 if the layer cannot provide such a file descriptor, or in
461the case of the error.
462
463XXX: two possible results end up in -1, one is an error the other is
464not.
465
466=item PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flags)
467
468XXX: not documented
469
470Similar to C<Open>, returns PerlIO* on success, C<NULL> on failure.
471
472=item SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
473
474Basic read operation.
50b80e25 475
d4165bde
SB
476Typically will call C<Fill> and manipulate pointers (possibly via the
477API). C<PerlIOBuf_read()> may be suitable for derived classes which
478provide "fast gets" methods.
50b80e25 479
d4165bde
SB
480Returns actual bytes read, or -1 on an error.
481
482=item SSize_t (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
50b80e25 483
9d799145
NIS
484A superset of stdio's C<ungetc()>. Should arrange for future reads to
485see the bytes in C<vbuf>. If there is no obviously better implementation
486then C<PerlIOBase_unread()> provides the function by pushing a "fake"
487"pending" layer above the calling layer.
50b80e25 488
d4165bde
SB
489Returns the number of unread chars.
490
50b80e25
NIS
491=item SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);
492
d4165bde 493Basic write operation.
50b80e25 494
d4165bde
SB
495Returns bytes written or -1 on an error.
496
497=item IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
50b80e25 498
1d11c889
JH
499Position the file pointer. Should normally call its own C<Flush>
500method and then the C<Seek> method of next layer down.
50b80e25 501
d4165bde
SB
502Returns 0 on success, -1 on failure.
503
504=item Off_t (*Tell)(pTHX_ PerlIO *f);
50b80e25 505
9d799145
NIS
506Return the file pointer. May be based on layers cached concept of
507position to avoid overhead.
50b80e25 508
d4165bde
SB
509Returns -1 on failure to get the file pointer.
510
511=item IV (*Close)(pTHX_ PerlIO *f);
50b80e25 512
9d799145
NIS
513Close the stream. Should normally call C<PerlIOBase_close()> to flush
514itself and close layers below, and then deallocate any data structures
515(buffers, translation tables, ...) not held directly in the data
516structure.
50b80e25 517
d4165bde
SB
518Returns 0 on success, -1 on failure.
519
520=item IV (*Flush)(pTHX_ PerlIO *f);
50b80e25 521
9d799145
NIS
522Should make stream's state consistent with layers below. That is, any
523buffered write data should be written, and file position of lower layers
d1be9408 524adjusted for data read from below but not actually consumed.
b76cc8ba 525(Should perhaps C<Unread()> such data to the lower layer.)
50b80e25 526
d4165bde
SB
527Returns 0 on success, -1 on failure.
528
529=item IV (*Fill)(pTHX_ PerlIO *f);
530
531The buffer for this layer should be filled (for read) from layer
532below. When you "subclass" PerlIOBuf layer, you want to use its
533I<_read> method and to supply your own fill method, which fills the
534PerlIOBuf's buffer.
50b80e25 535
d4165bde 536Returns 0 on success, -1 on failure.
50b80e25 537
d4165bde 538=item IV (*Eof)(pTHX_ PerlIO *f);
50b80e25 539
9d799145 540Return end-of-file indicator. C<PerlIOBase_eof()> is normally sufficient.
50b80e25 541
d4165bde
SB
542Returns 0 on end-of-file, 1 if not end-of-file, -1 on error.
543
544=item IV (*Error)(pTHX_ PerlIO *f);
50b80e25 545
9d799145 546Return error indicator. C<PerlIOBase_error()> is normally sufficient.
50b80e25 547
d4165bde
SB
548Returns 1 if there is an error (usually when C<PERLIO_F_ERROR> is set,
5490 otherwise.
550
551=item void (*Clearerr)(pTHX_ PerlIO *f);
50b80e25 552
9d799145
NIS
553Clear end-of-file and error indicators. Should call C<PerlIOBase_clearerr()>
554to set the C<PERLIO_F_XXXXX> flags, which may suffice.
50b80e25 555
d4165bde 556=item void (*Setlinebuf)(pTHX_ PerlIO *f);
50b80e25 557
b76cc8ba
NIS
558Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the
559PERLIO_F_LINEBUF flag and is normally sufficient.
50b80e25 560
d4165bde 561=item STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
50b80e25
NIS
562
563Allocate (if not already done so) the read buffer for this layer and
d4165bde 564return pointer to it. Return NULL on failure.
50b80e25 565
d4165bde 566=item Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
50b80e25 567
9d799145 568Return the number of bytes that last C<Fill()> put in the buffer.
50b80e25 569
d4165bde 570=item STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);
50b80e25 571
3039a93d 572Return the current read pointer relative to this layer's buffer.
50b80e25 573
d4165bde 574=item SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
50b80e25
NIS
575
576Return the number of bytes left to be read in the current buffer.
577
d4165bde 578=item void (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt);
50b80e25
NIS
579
580Adjust the read pointer and count of bytes to match C<ptr> and/or C<cnt>.
581The application (or layer above) must ensure they are consistent.
582(Checking is allowed by the paranoid.)
583
584=back
585
586
587=head2 Core Layers
588
589The file C<perlio.c> provides the following layers:
590
591=over 4
592
593=item "unix"
594
9d799145
NIS
595A basic non-buffered layer which calls Unix/POSIX C<read()>, C<write()>,
596C<lseek()>, C<close()>. No buffering. Even on platforms that distinguish
597between O_TEXT and O_BINARY this layer is always O_BINARY.
50b80e25
NIS
598
599=item "perlio"
600
9d799145
NIS
601A very complete generic buffering layer which provides the whole of
602PerlIO API. It is also intended to be used as a "base class" for other
1d11c889
JH
603layers. (For example its C<Read()> method is implemented in terms of
604the C<Get_cnt()>/C<Get_ptr()>/C<Set_ptrcnt()> methods).
50b80e25 605
9d799145
NIS
606"perlio" over "unix" provides a complete replacement for stdio as seen
607via PerlIO API. This is the default for USE_PERLIO when system's stdio
1d11c889
JH
608does not permit perl's "fast gets" access, and which do not
609distinguish between C<O_TEXT> and C<O_BINARY>.
50b80e25
NIS
610
611=item "stdio"
612
9d799145
NIS
613A layer which provides the PerlIO API via the layer scheme, but
614implements it by calling system's stdio. This is (currently) the default
615if system's stdio provides sufficient access to allow perl's "fast gets"
616access and which do not distinguish between C<O_TEXT> and C<O_BINARY>.
50b80e25
NIS
617
618=item "crlf"
619
9d799145
NIS
620A layer derived using "perlio" as a base class. It provides Win32-like
621"\n" to CR,LF translation. Can either be applied above "perlio" or serve
622as the buffer layer itself. "crlf" over "unix" is the default if system
623distinguishes between C<O_TEXT> and C<O_BINARY> opens. (At some point
624"unix" will be replaced by a "native" Win32 IO layer on that platform,
625as Win32's read/write layer has various drawbacks.) The "crlf" layer is
626a reasonable model for a layer which transforms data in some way.
50b80e25
NIS
627
628=item "mmap"
629
9d799145
NIS
630If Configure detects C<mmap()> functions this layer is provided (with
631"perlio" as a "base") which does "read" operations by mmap()ing the
632file. Performance improvement is marginal on modern systems, so it is
633mainly there as a proof of concept. It is likely to be unbundled from
634the core at some point. The "mmap" layer is a reasonable model for a
635minimalist "derived" layer.
50b80e25
NIS
636
637=item "pending"
638
9d799145 639An "internal" derivative of "perlio" which can be used to provide
1d11c889
JH
640Unread() function for layers which have no buffer or cannot be
641bothered. (Basically this layer's C<Fill()> pops itself off the stack
642and so resumes reading from layer below.)
50b80e25
NIS
643
644=item "raw"
645
9d799145
NIS
646A dummy layer which never exists on the layer stack. Instead when
647"pushed" it actually pops the stack(!), removing itself, and any other
648layers until it reaches a layer with the class C<PERLIO_K_RAW> bit set.
50b80e25
NIS
649
650=item "utf8"
651
9d799145 652Another dummy layer. When pushed it pops itself and sets the
1d11c889
JH
653C<PERLIO_F_UTF8> flag on the layer which was (and now is once more)
654the top of the stack.
50b80e25
NIS
655
656=back
657
9d799145
NIS
658In addition F<perlio.c> also provides a number of C<PerlIOBase_xxxx()>
659functions which are intended to be used in the table slots of classes
660which do not need to do anything special for a particular method.
50b80e25
NIS
661
662=head2 Extension Layers
663
1d11c889
JH
664Layers can made available by extension modules. When an unknown layer
665is encountered the PerlIO code will perform the equivalent of :
b76cc8ba
NIS
666
667 use PerlIO 'layer';
668
1d11c889 669Where I<layer> is the unknown layer. F<PerlIO.pm> will then attempt to:
b76cc8ba
NIS
670
671 require PerlIO::layer;
672
1d11c889
JH
673If after that process the layer is still not defined then the C<open>
674will fail.
b76cc8ba
NIS
675
676The following extension layers are bundled with perl:
50b80e25
NIS
677
678=over 4
679
b76cc8ba 680=item ":encoding"
50b80e25
NIS
681
682 use Encoding;
683
1d11c889
JH
684makes this layer available, although F<PerlIO.pm> "knows" where to
685find it. It is an example of a layer which takes an argument as it is
686called thus:
50b80e25
NIS
687
688 open($fh,"<:encoding(iso-8859-7)",$pathname)
689
b76cc8ba
NIS
690=item ":Scalar"
691
692Provides support for
693
694 open($fh,"...",\$scalar)
50b80e25 695
1d11c889
JH
696When a handle is so opened, then reads get bytes from the string value
697of I<$scalar>, and writes change the value. In both cases the position
698in I<$scalar> starts as zero but can be altered via C<seek>, and
699determined via C<tell>.
b76cc8ba
NIS
700
701=item ":Object" or ":Perl"
702
1d11c889
JH
703May be provided to allow layers to be implemented as perl code -
704implementation is being investigated.
b76cc8ba
NIS
705
706=back
50b80e25 707
d4165bde
SB
708=head1 TODO
709
710Things that need to be done to improve this document.
711
712=over
713
714=item *
715
716Explain how to make a valid fh without going through open()(i.e. apply
717a layer). For example if the file is not opened through perl, but we
718want to get back a fh, like it was opened by Perl.
719
720How PerlIO_apply_layera fits in, where its docs, was it made public?
721
722Currently the example could be something like this:
723
724 PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...)
725 {
726 char *mode; /* "w", "r", etc */
727 const char *layers = ":APR"; /* the layer name */
728 PerlIO *f = PerlIO_allocate(aTHX);
729 if (!f) {
730 return NULL;
731 }
732
733 PerlIO_apply_layers(aTHX_ f, mode, layers);
734
735 if (f) {
736 PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR);
737 /* fill in the st struct, as in _open() */
738 st->file = file;
739 PerlIOBase(f)->flags |= PERLIO_F_OPEN;
740
741 return f;
742 }
743 return NULL;
744 }
745
746=item *
747
748fix/add the documentation in places marked as XXX.
749
750=item *
751
752The handling of errors by the layer is not specified. e.g. when $!
753should be set explicitly, when the error handling should be just
754delegated to the top layer.
755
756Probably give some hints on using SETERRNO() or pointers to where they
757can be found.
758
759=item *
760
761I think it would help to give some concrete examples to make it easier
762to understand the API. Of course I agree that the API has to be
763concise, but since there is no second document that is more of a
764guide, I think that it'd make it easier to start with the doc which is
765an API, but has examples in it in places where things are unclear, to
766a person who is not a PerlIO guru (yet).
767
768=back
769
50b80e25
NIS
770=cut
771
772
773