Penguin
Recent Changes
Annotated edit history of perlapio(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 PERLAPIO
2 !!!PERLAPIO
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 ----
7 !!NAME
8
9
10 perlapio - perl's IO abstraction interface.
11 !!SYNOPSIS
12
13
14 PerlIO *PerlIO_stdin(void);
15 PerlIO *PerlIO_stdout(void);
16 PerlIO *PerlIO_stderr(void);
17 PerlIO *PerlIO_open(const char *,const char *);
18 int PerlIO_close(PerlIO *);
19 int PerlIO_stdoutf(const char *,...)
20 int PerlIO_puts(PerlIO *,const char *);
21 int PerlIO_putc(PerlIO *,int);
22 int PerlIO_write(PerlIO *,const void *,size_t);
23 int PerlIO_printf(PerlIO *, const char *,...);
24 int PerlIO_vprintf(PerlIO *, const char *, va_list);
25 int PerlIO_flush(PerlIO *);
26 int PerlIO_eof(PerlIO *);
27 int PerlIO_error(PerlIO *);
28 void PerlIO_clearerr(PerlIO *);
29 int PerlIO_getc(PerlIO *);
30 int PerlIO_ungetc(PerlIO *,int);
31 int PerlIO_read(PerlIO *,void *,size_t);
32 int PerlIO_fileno(PerlIO *);
33 PerlIO *PerlIO_fdopen(int, const char *);
34 PerlIO *PerlIO_importFILE(FILE *, int flags);
35 FILE *PerlIO_exportFILE(PerlIO *, int flags);
36 FILE *PerlIO_findFILE(PerlIO *);
37 void PerlIO_releaseFILE(PerlIO *,FILE *);
38 void PerlIO_setlinebuf(PerlIO *);
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 int PerlIO_has_base(PerlIO *);
45 int PerlIO_has_cntptr(PerlIO *);
46 int PerlIO_fast_gets(PerlIO *);
47 int PerlIO_canset_cnt(PerlIO *);
48 char *PerlIO_get_ptr(PerlIO *);
49 int PerlIO_get_cnt(PerlIO *);
50 void PerlIO_set_cnt(PerlIO *,int);
51 void PerlIO_set_ptrcnt(PerlIO *,char *,int);
52 char *PerlIO_get_base(PerlIO *);
53 int PerlIO_get_bufsiz(PerlIO *);
54 !!DESCRIPTION
55
56
57 Perl's source code should use the above functions instead of
58 those defined in ANSI C's ''stdio.h''. The
59 perl headers will #define them to the I/O mechanism
60 selected at Configure time.
61
62
63 The functions are modeled on those in ''stdio.h'', but
64 parameter order has been ``tidied up a
65 little''.
66
67
68 __PerlIO *__
69
70
71 This takes the place of FILE *. Like
72 FILE * it should be treated as opaque (it is
73 probably safe to assume it is a pointer to
74 something).
75
76
77 ''PerlIO_stdin()'', ''PerlIO_stdout()'',
78 ''PerlIO_stderr()''
79
80
81 Use these rather than stdin, stdout,
82 stderr. They are written to look like ``function
83 calls'' rather than variables because this makes it easier
84 to ''make them'' function calls if platform cannot export
85 data to loaded modules, or if (say) different ``threads''
86 might have different values.
87
88
89 __PerlIO_open(path, mode)__,
90 __PerlIO_fdopen(fd,mode)__
91
92
93 These correspond to ''fopen()''/''fdopen()'' arguments
94 are the same.
95
96
97 __PerlIO_printf(f,fmt,...)__,
98 __PerlIO_vprintf(f,fmt,a)__
99
100
101 These are ''fprintf()''/''vfprintf()''
102 equivalents.
103
104
105 __PerlIO_stdoutf(fmt,...)__
106
107
108 This is ''printf()'' equivalent. printf is #defined to
109 this function, so it is (currently) legal to use
110 printf(fmt,...) in perl sources.
111
112
113 __PerlIO_read(f,buf,count)__,
114 __PerlIO_write(f,buf,count)__
115
116
117 These correspond to ''fread()'' and ''fwrite()''. Note
118 that arguments are different, there is only one ``count''
119 and order has ``file'' first.
120
121
122 __PerlIO_close(f)__
123
124
125 __PerlIO_puts(f,s)__,
126 __PerlIO_putc(f,c)__
127
128
129 These correspond to ''fputs()'' and ''fputc()''. Note
130 that arguments have been revised to have ``file''
131 first.
132
133
134 __PerlIO_ungetc(f,c)__
135
136
137 This corresponds to ''ungetc()''. Note that arguments
138 have been revised to have ``file'' first.
139
140
141 __PerlIO_getc(f)__
142
143
144 This corresponds to ''getc()''.
145
146
147 __PerlIO_eof(f)__
148
149
150 This corresponds to ''feof()''.
151
152
153 __PerlIO_error(f)__
154
155
156 This corresponds to ''ferror()''.
157
158
159 __PerlIO_fileno(f)__
160
161
162 This corresponds to ''fileno()'', note that on some
163 platforms, the meaning of ``fileno'' may not match
164 Unix.
165
166
167 __PerlIO_clearerr(f)__
168
169
170 This corresponds to ''clearerr()'', i.e., clears 'eof'
171 and 'error' flags for the ``stream''.
172
173
174 __PerlIO_flush(f)__
175
176
177 This corresponds to ''fflush()''.
178
179
180 __PerlIO_tell(f)__
181
182
183 This corresponds to ''ftell()''.
184
185
186 __PerlIO_seek(f,o,w)__
187
188
189 This corresponds to ''fseek()''.
190
191
192 __PerlIO_getpos(f,p)__,
193 __PerlIO_setpos(f,p)__
194
195
196 These correspond to ''fgetpos()'' and ''fsetpos()''.
197 If platform does not have the stdio calls then they are
198 implemented in terms of ''PerlIO_tell()'' and
199 ''PerlIO_seek()''.
200
201
202 __PerlIO_rewind(f)__
203
204
205 This corresponds to ''rewind()''. Note may be redefined
206 in terms of ''PerlIO_seek()'' at some point.
207
208
209 ''PerlIO_tmpfile()''
210
211
212 This corresponds to ''tmpfile()'', i.e., returns an
213 anonymous PerlIO which will automatically be deleted when
214 closed.
215
216
217 __Co-existence with stdio__
218
219
220 There is outline support for co-existence of PerlIO with
221 stdio. Obviously if PerlIO is implemented in terms of stdio
222 there is no problem. However if perlio is implemented on top
223 of (say) sfio then mechanisms must exist to create a
224 FILE * which can be passed to library code
225 which is going to use stdio calls.
226
227
228 __PerlIO_importFILE(f,flags)__
229
230
231 Used to get a PerlIO * from a FILE *. May
232 need additional arguments, interface under
233 review.
234
235
236 __PerlIO_exportFILE(f,flags)__
237
238
239 Given an PerlIO * return a 'native' FILE *
240 suitable for passing to code expecting to be compiled and
241 linked with ANSI C
242 ''stdio.h''.
243
244
245 The fact that such a FILE * has been
246 'exported' is recorded, and may affect future PerlIO
247 operations on the original PerlIO *.
248
249
250 __PerlIO_findFILE(f)__
251
252
253 Returns previously 'exported' FILE * (if
254 any). Place holder until interface is fully
255 defined.
256
257
258 __PerlIO_releaseFILE(p,f)__
259
260
261 Calling PerlIO_releaseFILE informs PerlIO that all use of
262 FILE * is complete. It is removed from list
263 of 'exported' FILE *s, and associated PerlIO
264 * should revert to original behaviour.
265
266
267 __PerlIO_setlinebuf(f)__
268
269
270 This corresponds to ''setlinebuf()''. Use is deprecated
271 pending further discussion. (Perl core uses it ''only''
272 when ``dumping''; it has nothing to do with $
273 auto-flush.)
274
275
276 In addition to user API above there is an
277 ``implementation'' interface which allows perl to get at
278 internals of PerlIO. The following calls correspond to the
279 various FILE_xxx macros determined by Configure. This
280 section is really of interest to only those concerned with
281 detailed perl-core behaviour or implementing a PerlIO
282 mapping.
283
284
285 __PerlIO_has_cntptr(f)__
286
287
288 Implementation can return pointer to current position in the
289 ``buffer'' and a count of bytes available in the
290 buffer.
291
292
293 __PerlIO_get_ptr(f)__
294
295
296 Return pointer to next readable byte in buffer.
297
298
299 __PerlIO_get_cnt(f)__
300
301
302 Return count of readable bytes in the buffer.
303
304
305 __PerlIO_canset_cnt(f)__
306
307
308 Implementation can adjust its idea of number of bytes in the
309 buffer.
310
311
312 __PerlIO_fast_gets(f)__
313
314
315 Implementation has all the interfaces required to allow
316 perl's fast code to handle FILE
317
318
319 PerlIO_fast_gets(f) = PerlIO_has_cntptr(f)
320
321
322 __PerlIO_set_ptrcnt(f,p,c)__
323
324
325 Set pointer into buffer, and a count of bytes still in the
326 buffer. Should be used only to set pointer to within range
327 implied by previous calls to PerlIO_get_ptr and
328 PerlIO_get_cnt.
329
330
331 __PerlIO_set_cnt(f,c)__
332
333
334 Obscure - set count of bytes in the buffer. Deprecated.
335 Currently used in only doio.c to force count
336
337
338 __PerlIO_has_base(f)__
339
340
341 Implementation has a buffer, and can return pointer to whole
342 buffer and its size. Used by perl for __-T__ / __-B__
343 tests. Other uses would be very obscure...
344
345
346 __PerlIO_get_base(f)__
347
348
349 Return ''start'' of buffer.
350
351
352 __PerlIO_get_bufsiz(f)__
353
354
355 Return ''total size'' of buffer.
356 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.