1PERLAPIO(1)            Perl Programmers Reference Guide            PERLAPIO(1)
2
3
4

NAME

6       perlapio - perl's IO abstraction interface.
7

SYNOPSIS

9         #define PERLIO_NOT_STDIO 0    /* For co-existence with stdio only */
10         #include <perlio.h>           /* Usually via #include <perl.h> */
11
12         PerlIO *PerlIO_stdin(void);
13         PerlIO *PerlIO_stdout(void);
14         PerlIO *PerlIO_stderr(void);
15
16         PerlIO *PerlIO_open(const char *path,const char *mode);
17         PerlIO *PerlIO_fdopen(int fd, const char *mode);
18         PerlIO *PerlIO_reopen(const char *path, /* deprecated */
19                 const char *mode, PerlIO *old);
20         int     PerlIO_close(PerlIO *f);
21
22         int     PerlIO_stdoutf(const char *fmt,...)
23         int     PerlIO_puts(PerlIO *f,const char *string);
24         int     PerlIO_putc(PerlIO *f,int ch);
25         SSize_t PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
26         int     PerlIO_printf(PerlIO *f, const char *fmt,...);
27         int     PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
28         int     PerlIO_flush(PerlIO *f);
29
30         int     PerlIO_eof(PerlIO *f);
31         int     PerlIO_error(PerlIO *f);
32         void    PerlIO_clearerr(PerlIO *f);
33
34         int     PerlIO_getc(PerlIO *d);
35         int     PerlIO_ungetc(PerlIO *f,int ch);
36         SSize_t PerlIO_read(PerlIO *f, void *buf, size_t numbytes);
37
38         int     PerlIO_fileno(PerlIO *f);
39
40         void    PerlIO_setlinebuf(PerlIO *f);
41
42         Off_t   PerlIO_tell(PerlIO *f);
43         int     PerlIO_seek(PerlIO *f, Off_t offset, int whence);
44         void    PerlIO_rewind(PerlIO *f);
45
46         int     PerlIO_getpos(PerlIO *f, SV *save);    /* prototype changed */
47         int     PerlIO_setpos(PerlIO *f, SV *saved);   /* prototype changed */
48
49         int     PerlIO_fast_gets(PerlIO *f);
50         int     PerlIO_has_cntptr(PerlIO *f);
51         SSize_t PerlIO_get_cnt(PerlIO *f);
52         char   *PerlIO_get_ptr(PerlIO *f);
53         void    PerlIO_set_ptrcnt(PerlIO *f, char *ptr, SSize_t count);
54
55         int     PerlIO_canset_cnt(PerlIO *f);              /* deprecated */
56         void    PerlIO_set_cnt(PerlIO *f, int count);      /* deprecated */
57
58         int     PerlIO_has_base(PerlIO *f);
59         char   *PerlIO_get_base(PerlIO *f);
60         SSize_t PerlIO_get_bufsiz(PerlIO *f);
61
62         PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
63         FILE   *PerlIO_exportFILE(PerlIO *f, const char *mode);
64         FILE   *PerlIO_findFILE(PerlIO *f);
65         void    PerlIO_releaseFILE(PerlIO *f,FILE *stdio);
66
67         int     PerlIO_apply_layers(PerlIO *f, const char *mode,
68                                                           const char *layers);
69         int     PerlIO_binmode(PerlIO *f, int ptype, int imode,
70                                                           const char *layers);
71         void    PerlIO_debug(const char *fmt,...);
72

DESCRIPTION

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