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