contrib/perl5/pod/perlapio.pod

   1 =head1 NAME
   2
   3 perlapio - perl's IO abstraction interface.
   4
   5 =head1 SYNOPSIS
   6
   7     PerlIO *PerlIO_stdin(void);
   8     PerlIO *PerlIO_stdout(void);
   9     PerlIO *PerlIO_stderr(void);
  10
  11     PerlIO *PerlIO_open(const char *,const char *);
  12     int     PerlIO_close(PerlIO *);
  13
  14     int     PerlIO_stdoutf(const char *,...)
  15     int     PerlIO_puts(PerlIO *,const char *);
  16     int     PerlIO_putc(PerlIO *,int);
  17     int     PerlIO_write(PerlIO *,const void *,size_t);
  18     int     PerlIO_printf(PerlIO *, const char *,...);
  19     int     PerlIO_vprintf(PerlIO *, const char *, va_list);
  20     int     PerlIO_flush(PerlIO *);
  21
  22     int     PerlIO_eof(PerlIO *);
  23     int     PerlIO_error(PerlIO *);
  24     void    PerlIO_clearerr(PerlIO *);
  25
  26     int     PerlIO_getc(PerlIO *);
  27     int     PerlIO_ungetc(PerlIO *,int);
  28     int     PerlIO_read(PerlIO *,void *,size_t);
  29
  30     int     PerlIO_fileno(PerlIO *);
  31     PerlIO *PerlIO_fdopen(int, const char *);
  32     PerlIO *PerlIO_importFILE(FILE *, int flags);
  33     FILE   *PerlIO_exportFILE(PerlIO *, int flags);
  34     FILE   *PerlIO_findFILE(PerlIO *);
  35     void    PerlIO_releaseFILE(PerlIO *,FILE *);
  36
  37     void    PerlIO_setlinebuf(PerlIO *);
  38
  39     long    PerlIO_tell(PerlIO *);
  40     int     PerlIO_seek(PerlIO *,off_t,int);
  41     int     PerlIO_getpos(PerlIO *,Fpos_t *)
  42     int     PerlIO_setpos(PerlIO *,Fpos_t *)
  43     void    PerlIO_rewind(PerlIO *);
  44
  45     int     PerlIO_has_base(PerlIO *);
  46     int     PerlIO_has_cntptr(PerlIO *);
  47     int     PerlIO_fast_gets(PerlIO *);
  48     int     PerlIO_canset_cnt(PerlIO *);
  49
  50     char   *PerlIO_get_ptr(PerlIO *);
  51     int     PerlIO_get_cnt(PerlIO *);
  52     void    PerlIO_set_cnt(PerlIO *,int);
  53     void    PerlIO_set_ptrcnt(PerlIO *,char *,int);
  54     char   *PerlIO_get_base(PerlIO *);
  55     int     PerlIO_get_bufsiz(PerlIO *);
  56
  57 =head1 DESCRIPTION
  58
  59 Perl's source code should use the above functions instead of those
  60 defined in ANSI C's I<stdio.h>.  The perl headers will C<#define> them to
  61 the I/O mechanism selected at Configure time.
  62
  63 The functions are modeled on those in I<stdio.h>, but parameter order
  64 has been "tidied up a little".
  65
  66 =over 4
  67
  68 =item B<PerlIO *>
  69
  70 This takes the place of FILE *. Like FILE * it should be treated as
  71 opaque (it is probably safe to assume it is a pointer to something).
  72
  73 =item B<PerlIO_stdin()>, B<PerlIO_stdout()>, B<PerlIO_stderr()>
  74
  75 Use these rather than C<stdin>, C<stdout>, C<stderr>. They are written
  76 to look like "function calls" rather than variables because this makes
  77 it easier to I<make them> function calls if platform cannot export data
  78 to loaded modules, or if (say) different "threads" might have different
  79 values.
  80
  81 =item B<PerlIO_open(path, mode)>, B<PerlIO_fdopen(fd,mode)>
  82
  83 These correspond to fopen()/fdopen() arguments are the same.
  84
  85 =item B<PerlIO_printf(f,fmt,...)>, B<PerlIO_vprintf(f,fmt,a)>
  86
  87 These are fprintf()/vfprintf() equivalents.
  88
  89 =item B<PerlIO_stdoutf(fmt,...)>
  90
  91 This is printf() equivalent. printf is #defined to this function,
  92 so it is (currently) legal to use C<printf(fmt,...)> in perl sources.
  93
  94 =item B<PerlIO_read(f,buf,count)>, B<PerlIO_write(f,buf,count)>
  95
  96 These correspond to fread() and fwrite(). Note that arguments
  97 are different, there is only one "count" and order has
  98 "file" first.
  99
 100 =item B<PerlIO_close(f)>
 101
 102 =item B<PerlIO_puts(f,s)>, B<PerlIO_putc(f,c)>
 103
 104 These correspond to fputs() and fputc().
 105 Note that arguments have been revised to have "file" first.
 106
 107 =item B<PerlIO_ungetc(f,c)>
 108
 109 This corresponds to ungetc().
 110 Note that arguments have been revised to have "file" first.
 111
 112 =item B<PerlIO_getc(f)>
 113
 114 This corresponds to getc().
 115
 116 =item B<PerlIO_eof(f)>
 117
 118 This corresponds to feof().
 119
 120 =item B<PerlIO_error(f)>
 121
 122 This corresponds to ferror().
 123
 124 =item B<PerlIO_fileno(f)>
 125
 126 This corresponds to fileno(), note that on some platforms,
 127 the meaning of "fileno" may not match Unix.
 128
 129 =item B<PerlIO_clearerr(f)>
 130
 131 This corresponds to clearerr(), i.e., clears 'eof' and 'error'
 132 flags for the "stream".
 133
 134 =item B<PerlIO_flush(f)>
 135
 136 This corresponds to fflush().
 137
 138 =item B<PerlIO_tell(f)>
 139
 140 This corresponds to ftell().
 141
 142 =item B<PerlIO_seek(f,o,w)>
 143
 144 This corresponds to fseek().
 145
 146 =item B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)>
 147
 148 These correspond to fgetpos() and fsetpos(). If platform does not
 149 have the stdio calls then they are implemented in terms of PerlIO_tell()
 150 and PerlIO_seek().
 151
 152 =item B<PerlIO_rewind(f)>
 153
 154 This corresponds to rewind(). Note may be redefined
 155 in terms of PerlIO_seek() at some point.
 156
 157 =item B<PerlIO_tmpfile()>
 158
 159 This corresponds to tmpfile(), i.e., returns an anonymous
 160 PerlIO which will automatically be deleted when closed.
 161
 162 =back
 163
 164 =head2 Co-existence with stdio
 165
 166 There is outline support for co-existence of PerlIO with stdio.
 167 Obviously if PerlIO is implemented in terms of stdio there is
 168 no problem. However if perlio is implemented on top of (say) sfio
 169 then mechanisms must exist to create a FILE * which can be passed
 170 to library code which is going to use stdio calls.
 171
 172 =over 4
 173
 174 =item B<PerlIO_importFILE(f,flags)>
 175
 176 Used to get a PerlIO * from a FILE *.
 177 May need additional arguments, interface under review.
 178
 179 =item B<PerlIO_exportFILE(f,flags)>
 180
 181 Given an PerlIO * return a 'native' FILE * suitable for
 182 passing to code expecting to be compiled and linked with
 183 ANSI C I<stdio.h>.
 184
 185 The fact that such a FILE * has been 'exported' is recorded,
 186 and may affect future PerlIO operations on the original
 187 PerlIO *.
 188
 189 =item B<PerlIO_findFILE(f)>
 190
 191 Returns previously 'exported' FILE * (if any).
 192 Place holder until interface is fully defined.
 193
 194 =item B<PerlIO_releaseFILE(p,f)>
 195
 196 Calling PerlIO_releaseFILE informs PerlIO that all use
 197 of FILE * is complete. It is removed from list of 'exported'
 198 FILE *s, and associated PerlIO * should revert to original
 199 behaviour.
 200
 201 =item B<PerlIO_setlinebuf(f)>
 202
 203 This corresponds to setlinebuf(). Use is deprecated pending
 204 further discussion. (Perl core uses it I<only> when "dumping";
 205 it has nothing to do with $| auto-flush.)
 206
 207 =back
 208
 209 In addition to user API above there is an "implementation" interface
 210 which allows perl to get at internals of PerlIO.
 211 The following calls correspond to the various FILE_xxx macros determined
 212 by Configure. This section is really of interest to only those
 213 concerned with detailed perl-core behaviour or implementing a
 214 PerlIO mapping.
 215
 216 =over 4
 217
 218 =item B<PerlIO_has_cntptr(f)>
 219
 220 Implementation can return pointer to current position in the "buffer" and
 221 a count of bytes available in the buffer.
 222
 223 =item B<PerlIO_get_ptr(f)>
 224
 225 Return pointer to next readable byte in buffer.
 226
 227 =item B<PerlIO_get_cnt(f)>
 228
 229 Return count of readable bytes in the buffer.
 230
 231 =item B<PerlIO_canset_cnt(f)>
 232
 233 Implementation can adjust its idea of number of
 234 bytes in the buffer.
 235
 236 =item B<PerlIO_fast_gets(f)>
 237
 238 Implementation has all the interfaces required to
 239 allow perl's fast code to handle <FILE> mechanism.
 240
 241   PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
 242                         PerlIO_canset_cnt(f) && \
 243                         `Can set pointer into buffer'
 244
 245 =item B<PerlIO_set_ptrcnt(f,p,c)>
 246
 247 Set pointer into buffer, and a count of bytes still in the
 248 buffer. Should be used only to set
 249 pointer to within range implied by previous calls
 250 to C<PerlIO_get_ptr> and C<PerlIO_get_cnt>.
 251
 252 =item B<PerlIO_set_cnt(f,c)>
 253
 254 Obscure - set count of bytes in the buffer. Deprecated.
 255 Currently used in only doio.c to force count < -1 to -1.
 256 Perhaps should be PerlIO_set_empty or similar.
 257 This call may actually do nothing if "count" is deduced from pointer
 258 and a "limit".
 259
 260 =item B<PerlIO_has_base(f)>
 261
 262 Implementation has a buffer, and can return pointer
 263 to whole buffer and its size. Used by perl for B<-T> / B<-B> tests.
 264 Other uses would be very obscure...
 265
 266 =item B<PerlIO_get_base(f)>
 267
 268 Return I<start> of buffer.
 269
 270 =item B<PerlIO_get_bufsiz(f)>
 271
 272 Return I<total size> of buffer.
 273
 274 =back