This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
PerlIO doc tweaks from Craig A. Berry <craig.berry@psinetcs.com>
[perl5.git] / pod / perlapio.pod
CommitLineData
760ac839
LW
1=head1 NAME
2
28757baa 3perlapio - perl's IO abstraction interface.
760ac839
LW
4
5=head1 SYNOPSIS
6
3039a93d 7 #define PERLIO_NOT_STDIO 0 /* For co-existence with stdio only */
50b80e25
NIS
8 #include <perlio.h> /* Usually via #include <perl.h> */
9
760ac839
LW
10 PerlIO *PerlIO_stdin(void);
11 PerlIO *PerlIO_stdout(void);
12 PerlIO *PerlIO_stderr(void);
54310121 13
50b80e25
NIS
14 PerlIO *PerlIO_open(const char *path,const char *mode);
15 PerlIO *PerlIO_fdopen(int fd, const char *mode);
16 PerlIO *PerlIO_reopen(const char *path, const char *mode, PerlIO *old); /* deprecated */
17 int PerlIO_close(PerlIO *f);
18
19 int PerlIO_stdoutf(const char *fmt,...)
20 int PerlIO_puts(PerlIO *f,const char *string);
21 int PerlIO_putc(PerlIO *f,int ch);
22 int PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
23 int PerlIO_printf(PerlIO *f, const char *fmt,...);
24 int PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
25 int PerlIO_flush(PerlIO *f);
26
27 int PerlIO_eof(PerlIO *f);
28 int PerlIO_error(PerlIO *f);
29 void PerlIO_clearerr(PerlIO *f);
30
31 int PerlIO_getc(PerlIO *d);
32 int PerlIO_ungetc(PerlIO *f,int ch);
33 int PerlIO_read(PerlIO *f, void *buf, size_t numbytes);
34
35 int PerlIO_fileno(PerlIO *f);
36
37 void PerlIO_setlinebuf(PerlIO *f);
38
39 Off_t PerlIO_tell(PerlIO *f);
40 int PerlIO_seek(PerlIO *f, Off_t offset, int whence);
41 void PerlIO_rewind(PerlIO *f);
42
43 int PerlIO_getpos(PerlIO *f, SV *save); /* prototype changed */
44 int PerlIO_setpos(PerlIO *f, SV *saved); /* prototype changed */
45
46 int PerlIO_fast_gets(PerlIO *f);
47 int PerlIO_has_cntptr(PerlIO *f);
48 int PerlIO_get_cnt(PerlIO *f);
49 char *PerlIO_get_ptr(PerlIO *f);
50 void PerlIO_set_ptrcnt(PerlIO *f, char *ptr, int count);
51
52 int PerlIO_canset_cnt(PerlIO *f); /* deprecated */
53 void PerlIO_set_cnt(PerlIO *f, int count); /* deprecated */
54
55 int PerlIO_has_base(PerlIO *f);
56 char *PerlIO_get_base(PerlIO *f);
57 int PerlIO_get_bufsiz(PerlIO *f);
58
59 PerlIO *PerlIO_importFILE(FILE *stdio, int flags);
60 FILE *PerlIO_exportFILE(PerlIO *f, int flags);
61 FILE *PerlIO_findFILE(PerlIO *f);
62 void PerlIO_releaseFILE(PerlIO *f,FILE *stdio);
63
64 int PerlIO_apply_layers(PerlIO *f, const char *mode, const char *layers);
65 int PerlIO_binmode(PerlIO *f, int ptype, int imode, const char *layers);
66 void PerlIO_debug(const char *fmt,...)
760ac839
LW
67
68=head1 DESCRIPTION
69
50b80e25
NIS
70Perl's source code, and extensions that want maximum portability, should use the above
71functions instead of those defined in ANSI C's I<stdio.h>. The perl headers (in
72particular "perlio.h") will C<#define> them to the I/O mechanism selected at Configure time.
760ac839
LW
73
74The functions are modeled on those in I<stdio.h>, but parameter order
75has been "tidied up a little".
76
50b80e25
NIS
77C<PerlIO *> takes the place of FILE *. Like FILE * it should be treated as
78opaque (it is probably safe to assume it is a pointer to something).
79
80There are currently three implementations:
81
760ac839
LW
82=over 4
83
50b80e25 84=item 1. USE_STDIO
760ac839 85
50b80e25
NIS
86All above are #define'd to stdio functions or are trivial wrapper functions which
87call stdio. In this case I<only> PerlIO * is a FILE *.
88This has been the default implementation since the abstraction was introduced
89in perl5.003_02.
90
91=item 2. USE_SFIO
92
93A "legacy" implementation in terms of the "sfio" library. Used for some specialist
94applications on Unix machines ("sfio" is not widely ported away from Unix).
95Most of above are #define'd to the sfio functions. PerlIO * is in this case Sfio_t *.
96
97=item 3. USE_PERLIO
98
99Introduced just after perl5.7.0 this is a re-implementation of the above abstraction
100which allows perl more control over how IO is done as it decouples IO from the
101way the operating system and C library choose to do things. For USE_PERLIO
102PerlIO * has an extra layer of indirection - it is a pointer-to-a-pointer.
103This allows the PerlIO * to remain with a known value while swapping the
104implementation arround underneath I<at run time>. In this case all the
105above are true (but very simple) functions which call the underlying implementation.
106
107This is the only implementation for which C<PerlIO_apply_layers()> does anything
108"interesting".
109
110The USE_PERLIO implementation is described in L<perliol>.
111
112=back
113
114Because "perlio.h" is a thing layer (for efficiency) the semantics of these functions are
3039a93d 115somewhat dependent on the the underlying implementation. Where these variations are
50b80e25
NIS
116understood they are noted below.
117
3039a93d 118Unless otherwise noted, functions return 0 on success, or a negative value (usually
50b80e25
NIS
119C<EOF> which is usually -1) and set C<errno> on error.
120
121=over 4
760ac839
LW
122
123=item B<PerlIO_stdin()>, B<PerlIO_stdout()>, B<PerlIO_stderr()>
124
125Use these rather than C<stdin>, C<stdout>, C<stderr>. They are written
126to look like "function calls" rather than variables because this makes
54310121
PP
127it easier to I<make them> function calls if platform cannot export data
128to loaded modules, or if (say) different "threads" might have different
760ac839
LW
129values.
130
131=item B<PerlIO_open(path, mode)>, B<PerlIO_fdopen(fd,mode)>
132
3039a93d
NIS
133These correspond to fopen()/fdopen() and the arguments are the same.
134Return C<NULL> and set C<errno> if there is an error.
135There may be an implementation limit on the number of open handles, which may
50b80e25 136be lower than the limit on the number of open files - C<errno> may
3039a93d 137not be set when C<NULL> is returned if this limnit is exceeded.
50b80e25
NIS
138
139=item B<PerlIO_reopen(path,mode,f)
140
141While this currently exists in all three implementations perl itself
142does not use it. I<As perl does not use it, it is not well tested.>
143
144Perl prefers to C<dup> the new low-level descriptor to the descriptor used
145by the existing PerlIO. This may become the behaviour of this function
146in the future.
760ac839
LW
147
148=item B<PerlIO_printf(f,fmt,...)>, B<PerlIO_vprintf(f,fmt,a)>
149
7b8d334a 150These are fprintf()/vfprintf() equivalents.
760ac839
LW
151
152=item B<PerlIO_stdoutf(fmt,...)>
153
154This is printf() equivalent. printf is #defined to this function,
84dc3c4d 155so it is (currently) legal to use C<printf(fmt,...)> in perl sources.
760ac839
LW
156
157=item B<PerlIO_read(f,buf,count)>, B<PerlIO_write(f,buf,count)>
158
54310121 159These correspond to fread() and fwrite(). Note that arguments
760ac839 160are different, there is only one "count" and order has
50b80e25
NIS
161"file" first. Returns a byte count if successful (which may be zero),
162returns negative value and sets C<errno> on error.
163Depending on implementation C<errno> may be C<EINTR> if operation
164was interrupted by a signal.
760ac839
LW
165
166=item B<PerlIO_close(f)>
167
50b80e25
NIS
168Depending on implementation C<errno> may be C<EINTR> if operation
169was interrupted by a signal.
170
21917246 171=item B<PerlIO_puts(f,s)>, B<PerlIO_putc(f,c)>
760ac839 172
54310121 173These correspond to fputs() and fputc().
760ac839
LW
174Note that arguments have been revised to have "file" first.
175
21917246 176=item B<PerlIO_ungetc(f,c)>
760ac839
LW
177
178This corresponds to ungetc().
179Note that arguments have been revised to have "file" first.
50b80e25
NIS
180Arranges that next read operation will return the byte B<c>.
181Despite the implied "character" in the name only values in the
182range 0..0xFF are defined. Returns the byte B<c> on success or -1 (C<EOF>) on error.
183The number of bytes that can be "pushed back" may vary, only 1 character is
184certain, and then only if it is the last character that was read from the handle.
760ac839
LW
185
186=item B<PerlIO_getc(f)>
187
188This corresponds to getc().
50b80e25 189Despite the c in the name only byte range 0..0xFF is supported.
3039a93d 190Returns the character read or -1 (C<EOF>) on error.
760ac839
LW
191
192=item B<PerlIO_eof(f)>
193
194This corresponds to feof().
50b80e25
NIS
195Returns a true/false indication of whether the handle is at end of file.
196For terminal devices this may or may not be "sticky" depending on the implementation.
197The flag is cleared by PerlIO_seek(), or PerlIO_rewind().
760ac839
LW
198
199=item B<PerlIO_error(f)>
200
201This corresponds to ferror().
50b80e25 202Returns a true/false indication of whether there has been an IO error on the handle.
760ac839
LW
203
204=item B<PerlIO_fileno(f)>
205
54310121 206This corresponds to fileno(), note that on some platforms,
3039a93d 207the meaning of "fileno" may not match Unix. Returns -1 if the handle has no
50b80e25 208open descriptor associated with it.
760ac839
LW
209
210=item B<PerlIO_clearerr(f)>
211
50b80e25
NIS
212This corresponds to clearerr(), i.e., clears 'error' and (usually) 'eof'
213flags for the "stream". Does not return a value.
760ac839
LW
214
215=item B<PerlIO_flush(f)>
216
217This corresponds to fflush().
50b80e25
NIS
218Sends any buffered write data to the underlying file.
219If called with C<NULL> this may flush all open streams (or core dump).
220Calling on a handle open for read only, or on which last operation was a read of some kind
221may lead to undefined behaviour.
760ac839 222
50b80e25 223=item B<PerlIO_seek(f,offset,whence)>
760ac839 224
50b80e25
NIS
225This corresponds to fseek().
226Sends buffered write data to the underlying file, or discards any buffered
227read data, then positions the file desciptor as specified by B<offset> and B<whence> (sic).
228This is the correct thing to do when switching between read and write on the same
229handle (see issues with PerlIO_flush() above).
230Offset is of type C<Off_t> which is a perl Configure value which may not be same
231as stdio's C<off_t>.
760ac839 232
50b80e25 233=item B<PerlIO_tell(f)>
760ac839 234
50b80e25
NIS
235This corresponds to ftell().
236Returns the current file position, or (Off_t) -1 on error.
237May just return value system "knows" without making a system call or checking
3039a93d 238the underlying file descriptor (so use on shared file descriptors is not
50b80e25
NIS
239safe without a PerlIO_seek()). Return value is of type C<Off_t> which is a perl Configure
240value which may not be same as stdio's C<off_t>.
760ac839
LW
241
242=item B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)>
243
50b80e25
NIS
244These correspond (loosely) to fgetpos() and fsetpos(). Rather than stdio's Fpos_t
245they expect a "Perl Scalar Value" to be passed. What is stored there should
3039a93d 246be considered opaque. The layout of the data may vary from handle to handle.
50b80e25
NIS
247When not using stdio or if platform does not have the stdio calls then they are
248implemented in terms of PerlIO_tell() and PerlIO_seek().
760ac839
LW
249
250=item B<PerlIO_rewind(f)>
251
50b80e25
NIS
252This corresponds to rewind(). It is usually defined as being
253
254 PerlIO_seek(f,(Off_t)0L, SEEK_SET);
255 PerlIO_clearerr(f);
256
760ac839
LW
257
258=item B<PerlIO_tmpfile()>
259
5f05dabc 260This corresponds to tmpfile(), i.e., returns an anonymous
50b80e25 261PerlIO or NULL on error.
3039a93d 262The system will attempt to automatically delete the file when closed.
50b80e25
NIS
263On Unix the file is usually C<unlink>-ed just after
264it is created so it does not matter how it gets closed. On other systems the file may
265only be deleted if closed via PerlIO_close() and/or the program exits via C<exit>.
266Depending on the implementation there may be "race conditions" which allow other
267processes access to the file, though in general it will be safer in this regard
268than ad. hoc. schemes.
269
270=item B<PerlIO_setlinebuf(f)>
271
272This corresponds to setlinebuf().
273Does not return a value. What constitutes a "line" is implementation
3039a93d 274dependent but usually means that writing "\n" flushes the buffer.
50b80e25
NIS
275What happens with things like "this\nthat" is uncertain.
276(Perl core uses it I<only> when "dumping"; it has nothing to do with $| auto-flush.)
760ac839 277
54310121 278=back
760ac839 279
510d21e9 280=head2 Co-existence with stdio
760ac839 281
510d21e9 282There is outline support for co-existence of PerlIO with stdio.
54310121 283Obviously if PerlIO is implemented in terms of stdio there is
50b80e25
NIS
284no problem. However in other cases then mechanisms must exist to create a FILE *
285which can be passed to library code which is going to use stdio calls.
286
287The fisrt step is to add this line:
288
289 #define PERLIO_NOT_STDIO 0
290
291I<before> including any perl header files. (This will probably become the
292default at some point). That prevents "perlio.h" from attempting to
293#define stdio functions onto PerlIO functions.
294
295XS code is probably better using "typemap" if it expects FILE * arguments.
3039a93d 296The standard typemap will be adjusted to comprehend any changes in this area.
760ac839
LW
297
298=over 4
299
300=item B<PerlIO_importFILE(f,flags)>
301
302Used to get a PerlIO * from a FILE *.
303May need additional arguments, interface under review.
304
50b80e25
NIS
305The flags argument was meant to be used for read vs write vs read/write
306information. In hindsight it would have been better to make it a char *mode
307as in fopen/freopen.
308
760ac839
LW
309=item B<PerlIO_exportFILE(f,flags)>
310
3039a93d 311Given a PerlIO * return a 'native' FILE * suitable for
54310121 312passing to code expecting to be compiled and linked with
760ac839
LW
313ANSI C I<stdio.h>.
314
315The fact that such a FILE * has been 'exported' is recorded,
54310121
PP
316and may affect future PerlIO operations on the original
317PerlIO *.
760ac839
LW
318
319=item B<PerlIO_findFILE(f)>
320
321Returns previously 'exported' FILE * (if any).
322Place holder until interface is fully defined.
323
324=item B<PerlIO_releaseFILE(p,f)>
325
326Calling PerlIO_releaseFILE informs PerlIO that all use
327of FILE * is complete. It is removed from list of 'exported'
54310121 328FILE *s, and associated PerlIO * should revert to original
760ac839
LW
329behaviour.
330
760ac839
LW
331=back
332
50b80e25
NIS
333=head2 "Fast gets" Functions
334
335In addition to standard-like API defined so far above there is an "implementation" interface
760ac839
LW
336which allows perl to get at internals of PerlIO.
337The following calls correspond to the various FILE_xxx macros determined
50b80e25
NIS
338by Configure - or their equivalent in other implementations. This section is really of
339interest to only those concerned with detailed perl-core behaviour, implementing a
340PerlIO mapping or writing code which can make use of the "read ahead" that has been done by
341the IO system in the same way perl does. Note that any code that uses these interfaces
342must be prepared to do things the traditional way if a handle does not support
343them.
760ac839
LW
344
345=over 4
346
50b80e25 347=item B<PerlIO_fast_gets(f)>
760ac839 348
50b80e25
NIS
349Returns true if implementation has all the interfaces required to
350allow perl's C<sv_gets> to "bypass" normal IO mechanism.
351This can vary from handle to handle.
760ac839 352
50b80e25
NIS
353 PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
354 PerlIO_canset_cnt(f) && \
355 `Can set pointer into buffer'
760ac839 356
760ac839 357
50b80e25 358=item B<PerlIO_has_cntptr(f)>
760ac839 359
50b80e25
NIS
360Implementation can return pointer to current position in the "buffer" and
361a count of bytes available in the buffer.
362Do not use this - use PerlIO_fast_gets.
760ac839 363
50b80e25 364=item B<PerlIO_get_cnt(f)>
760ac839 365
50b80e25
NIS
366Return count of readable bytes in the buffer. Zero or negative return means
367no more bytes available.
760ac839 368
50b80e25 369=item B<PerlIO_get_ptr(f)>
760ac839 370
50b80e25
NIS
371Return pointer to next readable byte in buffer, accessing via the pointer
372(dereferencing) is only safe if PerlIO_get_cnt() has returned a positive value.
373Only positive offsets up to value returned by PerlIO_get_cnt() are allowed.
760ac839
LW
374
375=item B<PerlIO_set_ptrcnt(f,p,c)>
376
54310121 377Set pointer into buffer, and a count of bytes still in the
5f05dabc 378buffer. Should be used only to set
760ac839 379pointer to within range implied by previous calls
50b80e25 380to C<PerlIO_get_ptr> and C<PerlIO_get_cnt>. The two values I<must> be consistent
3039a93d 381with each other (implementation may only use one or the other or may require both).
50b80e25
NIS
382
383=item B<PerlIO_canset_cnt(f)>
384
385Implementation can adjust its idea of number of bytes in the buffer.
386Do not use this - use PerlIO_fast_gets.
760ac839
LW
387
388=item B<PerlIO_set_cnt(f,c)>
389
390Obscure - set count of bytes in the buffer. Deprecated.
50b80e25 391Only usable if PerlIO_canset_cnt() returns true.
5f05dabc 392Currently used in only doio.c to force count < -1 to -1.
760ac839
LW
393Perhaps should be PerlIO_set_empty or similar.
394This call may actually do nothing if "count" is deduced from pointer
54310121 395and a "limit".
50b80e25 396Do not use this - use PerlIO_set_ptrcnt().
760ac839
LW
397
398=item B<PerlIO_has_base(f)>
399
50b80e25 400Returns true if implementation has a buffer, and can return pointer
760ac839
LW
401to whole buffer and its size. Used by perl for B<-T> / B<-B> tests.
402Other uses would be very obscure...
403
404=item B<PerlIO_get_base(f)>
405
50b80e25
NIS
406Return I<start> of buffer. Access only positive offsets in the buffer
407up to the value returned by PerlIO_get_bufsiz().
760ac839
LW
408
409=item B<PerlIO_get_bufsiz(f)>
410
50b80e25
NIS
411Return the I<total number of bytes> in the buffer, this is neither the number
412that can be read, nor the amount of memory allocated to the buffer. Rather
413it is what the operating system and/or implementation happened to C<read()>
414(or whatever) last time IO was requested.
415
416=back
417
418=head2 Other Functions
419
420=over 4
421
422=item PerlIO_apply_layers(f,mode,layers)
423
424The new interface to the USE_PERLIO implementation. The layers ":crlf"
425and ":raw" are only ones allowed for other implementations and those
426are silently ignored. Use PerlIO_binmode() below for the portable
427case.
428
429=item PerlIO_binmode(f,ptype,imode,layers)
430
431The hook used by perl's C<binmode> operator.
432B<ptype> is perl's charcter for the kind of IO:
433
434=over 8
435
436=item '<' read
437
438=item '>' write
439
440=item '+' read/write
441
442=back
443
444B<imode> is C<O_BINARY> or C<O_TEXT>.
445
446B<layers> is a string of layers to apply, only ":raw" or :"crlf" make
447sense in the non USE_PERLIO case.
448
449Portable cases are:
450
451 PerlIO_binmode(f,ptype,O_BINARY,":raw");
452and
453 PerlIO_binmode(f,ptype,O_TEXT,":crlf");
454
3039a93d 455On Unix these calls probably have no effect whatsoever.
50b80e25
NIS
456Elsewhere they alter "\n" to CR,LF translation and possibly cause a special
457text "end of file" indicator to be written or honoured on read. The effect of
458making the call after doing any IO to the handle depends on the implementation. (It may be
459ignored, affect any data which is already buffered as well, or only apply
460to subsequent data.)
461
462=item PerlIO_debug(fmt,...)
463
464PerlIO_debug is a printf()-like function which can be used for debugging.
465No return value. Its main use is inside PerlIO where using real printf, warn() etc. would
466recursively call PerlIO and be a problem.
467
468PerlIO_debug writes to the file named by $ENV{'PERLIO_DEBUG'} typical use
469might be
470
471
472 Bourne shells:
473 PERLIO_DEBUG=/dev/tty ./perl somescript some args
474
475 Csh:
476 setenv PERLIO_DEBUG /dev/tty
477 ./perl somescript some args
478
479 Win32:
480 set PERLIO_DEBUG=CON
481 perl somescript some args
482
483If $ENV{'PERLIO_DEBUG'} is not set PerlIO_debug() is a no-op.
760ac839 484
54310121 485=back