Update Changes.
[p5sagit/p5-mst-13.2.git] / pod / perliol.pod
CommitLineData
50b80e25 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 10=head1 DESCRIPTION
11
9d799145 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 15
16=head2 History and Background
17
9d799145 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 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 26
27=head2 Layers vs Disciplines
28
9d799145 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 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 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 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 66
67A "layer" is composed of two parts:
68
69=over 4
70
210b36aa 71=item 1.
50b80e25 72
210b36aa 73The functions and attributes of the "layer class".
74
75=item 2.
76
77The per-instance data for a particular handle.
50b80e25 78
79=back
80
81=head2 Functions and Attributes
82
9d799145 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 88 struct _PerlIO_funcs
89 {
90 char * name;
91 Size_t size;
92 IV kind;
d4165bde 93 IV (*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg);
94 IV (*Popped)(pTHX_ PerlIO *f);
b76cc8ba 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 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 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 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 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 124 };
125
9d799145 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 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 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 148
149=back
150
1d11c889 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 157
158=head2 Per-instance Data
159
1d11c889 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 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 175In this way (as for perl's scalars) a pointer to a PerlIOBuf can be
176treated as a pointer to a PerlIOl.
50b80e25 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 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 198The above is roughly equivalent to a "stdio" buffered stream, but with
199much more flexibility:
50b80e25 200
201=over 4
202
203=item *
204
9d799145 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 208
209=item *
210
1d11c889 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 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 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 224
225=item *
226
1d11c889 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 230
231=back
232
233=head2 Per-instance flag bits
234
1d11c889 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 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 248
249=item PERLIO_F_CANREAD
250
3039a93d 251Reads are permitted i.e. opened "r" or "w+" (or even "a+" - ick).
50b80e25 252
253=item PERLIO_F_ERROR
254
d4165bde 255An error has occurred (for C<PerlIO_error()>).
50b80e25 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 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 270flag rather than add/remove layers if the C<PERLIO_K_CANCRLF> bit is set
271for the layers class.
50b80e25 272
273=item PERLIO_F_UTF8
274
3039a93d 275Data written to this layer should be UTF-8 encoded; data provided
50b80e25 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 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 299
300=item PERLIO_F_TEMP
301
9d799145 302File has been C<unlink()>ed, or should be deleted on C<close()>.
50b80e25 303
304=item PERLIO_F_OPEN
305
306Handle is open.
307
308=item PERLIO_F_FASTGETS
309
9d799145 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 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 317to change during one "get".)
318
319=back
320
321=head2 Methods in Detail
322
323=over 4
324
5cb3728c 325=item name
326
327 char * name;
d4165bde 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 337=item size
338
339 Size_t size;
d4165bde 340
341The size of the per-instance data structure, e.g.:
342
343 sizeof(PerlIOAPR)
344
5cb3728c 345=item kind
346
347 IV kind;
d4165bde 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 369=item Pushed
370
371 IV (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg);
50b80e25 372
1d11c889 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 383Returns 0 on success. On failure returns -1 and should set errno.
384
5cb3728c 385=item Popped
386
387 IV (*Popped)(pTHX_ PerlIO *f);
50b80e25 388
1d11c889 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 398Returns 0 on success and failure.
399
5cb3728c 400=item Open
401
402 PerlIO * (*Open)(...);
b76cc8ba 403
1d11c889 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 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 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 456Returns C<NULL> on failure.
457
5cb3728c 458=item Getarg
459
460 SV * (*Getarg)(pTHX_ PerlIO *f,
461 CLONE_PARAMS *param, int flags);
b76cc8ba 462
d4165bde 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 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 474C<PerlIOBase_fileno()> (which just asks next layer down) will suffice
475for this.
50b80e25 476
d4165bde 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 483=item Dup
484
485 PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o,
486 CLONE_PARAMS *param, int flags);
d4165bde 487
488XXX: not documented
489
490Similar to C<Open>, returns PerlIO* on success, C<NULL> on failure.
491
5cb3728c 492=item Read
493
494 SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
d4165bde 495
496Basic read operation.
50b80e25 497
d4165bde 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 502Returns actual bytes read, or -1 on an error.
503
5cb3728c 504=item Unread
505
506 SSize_t (*Unread)(pTHX_ PerlIO *f,
507 const void *vbuf, Size_t count);
50b80e25 508
9d799145 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 514Returns the number of unread chars.
515
5cb3728c 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 522Returns bytes written or -1 on an error.
523
5cb3728c 524=item Seek
525
526 IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
50b80e25 527
1d11c889 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 531Returns 0 on success, -1 on failure.
532
5cb3728c 533=item Tell
534
535 Off_t (*Tell)(pTHX_ PerlIO *f);
50b80e25 536
9d799145 537Return the file pointer. May be based on layers cached concept of
538position to avoid overhead.
50b80e25 539
d4165bde 540Returns -1 on failure to get the file pointer.
541
5cb3728c 542=item Close
543
544 IV (*Close)(pTHX_ PerlIO *f);
50b80e25 545
9d799145 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 551Returns 0 on success, -1 on failure.
552
5cb3728c 553=item Flush
554
555 IV (*Flush)(pTHX_ PerlIO *f);
50b80e25 556
9d799145 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 562Returns 0 on success, -1 on failure.
563
5cb3728c 564=item Fill
565
566 IV (*Fill)(pTHX_ PerlIO *f);
d4165bde 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 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 581Returns 0 on end-of-file, 1 if not end-of-file, -1 on error.
582
5cb3728c 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 589Returns 1 if there is an error (usually when C<PERLIO_F_ERROR> is set,
5900 otherwise.
591
5cb3728c 592=item Clearerr
593
594 void (*Clearerr)(pTHX_ PerlIO *f);
50b80e25 595
9d799145 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 599=item Setlinebuf
600
601 void (*Setlinebuf)(pTHX_ PerlIO *f);
50b80e25 602
b76cc8ba 603Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the
604PERLIO_F_LINEBUF flag and is normally sufficient.
50b80e25 605
5cb3728c 606=item Get_base
607
608 STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
50b80e25 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 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 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 625=item Get_cnt
626
627 SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
50b80e25 628
629Return the number of bytes left to be read in the current buffer.
630
5cb3728c 631=item Set_ptrcnt
632
633 void (*Set_ptrcnt)(pTHX_ PerlIO *f,
634 STDCHAR *ptr, SSize_t cnt);
50b80e25 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 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 654
655=item "perlio"
656
9d799145 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 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 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 664does not permit perl's "fast gets" access, and which do not
665distinguish between C<O_TEXT> and C<O_BINARY>.
50b80e25 666
667=item "stdio"
668
9d799145 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 673
674=item "crlf"
675
9d799145 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 683
684=item "mmap"
685
9d799145 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 692
693=item "pending"
694
9d799145 695An "internal" derivative of "perlio" which can be used to provide
1d11c889 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 699
700=item "raw"
701
9d799145 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 705
706=item "utf8"
707
9d799145 708Another dummy layer. When pushed it pops itself and sets the
1d11c889 709C<PERLIO_F_UTF8> flag on the layer which was (and now is once more)
710the top of the stack.
50b80e25 711
712=back
713
9d799145 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 717
718=head2 Extension Layers
719
1d11c889 720Layers can made available by extension modules. When an unknown layer
721is encountered the PerlIO code will perform the equivalent of :
b76cc8ba 722
723 use PerlIO 'layer';
724
1d11c889 725Where I<layer> is the unknown layer. F<PerlIO.pm> will then attempt to:
b76cc8ba 726
727 require PerlIO::layer;
728
1d11c889 729If after that process the layer is still not defined then the C<open>
730will fail.
b76cc8ba 731
732The following extension layers are bundled with perl:
50b80e25 733
734=over 4
735
b76cc8ba 736=item ":encoding"
50b80e25 737
738 use Encoding;
739
1d11c889 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 743
744 open($fh,"<:encoding(iso-8859-7)",$pathname)
745
b76cc8ba 746=item ":Scalar"
747
748Provides support for
749
750 open($fh,"...",\$scalar)
50b80e25 751
1d11c889 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
757=item ":Object" or ":Perl"
758
1d11c889 759May be provided to allow layers to be implemented as perl code -
760implementation is being investigated.
b76cc8ba 761
762=back
50b80e25 763
d4165bde 764=head1 TODO
765
766Things that need to be done to improve this document.
767
768=over
769
770=item *
771
772Explain how to make a valid fh without going through open()(i.e. apply
773a layer). For example if the file is not opened through perl, but we
774want to get back a fh, like it was opened by Perl.
775
776How PerlIO_apply_layera fits in, where its docs, was it made public?
777
778Currently the example could be something like this:
779
780 PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...)
781 {
782 char *mode; /* "w", "r", etc */
783 const char *layers = ":APR"; /* the layer name */
784 PerlIO *f = PerlIO_allocate(aTHX);
785 if (!f) {
786 return NULL;
787 }
788
789 PerlIO_apply_layers(aTHX_ f, mode, layers);
790
791 if (f) {
792 PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR);
793 /* fill in the st struct, as in _open() */
794 st->file = file;
795 PerlIOBase(f)->flags |= PERLIO_F_OPEN;
796
797 return f;
798 }
799 return NULL;
800 }
801
802=item *
803
804fix/add the documentation in places marked as XXX.
805
806=item *
807
808The handling of errors by the layer is not specified. e.g. when $!
809should be set explicitly, when the error handling should be just
810delegated to the top layer.
811
812Probably give some hints on using SETERRNO() or pointers to where they
813can be found.
814
815=item *
816
817I think it would help to give some concrete examples to make it easier
818to understand the API. Of course I agree that the API has to be
819concise, but since there is no second document that is more of a
820guide, I think that it'd make it easier to start with the doc which is
821an API, but has examples in it in places where things are unclear, to
822a person who is not a PerlIO guru (yet).
823
824=back
825
50b80e25 826=cut
827
828
829