Commit | Line | Data |
760ac839 |
1 | =head1 NAME |
2 | |
28757baa |
3 | perlapio - perl's IO abstraction interface. |
760ac839 |
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 *); |
33 | FILE *PerlIO_exportFILE(PerlIO *); |
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>, I<perlio.h> will the 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 *. Unlike 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 is fprintf()/vfprintf equivalents. |
88 | |
89 | =item B<PerlIO_stdoutf(fmt,...)> |
90 | |
91 | This is printf() equivalent. printf is #defined to this function, |
84dc3c4d |
92 | so it is (currently) legal to use C<printf(fmt,...)> in perl sources. |
760ac839 |
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(s,f)>, B<PerlIO_putc(c,f)> |
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(c,f)> |
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 | |
5f05dabc |
131 | This corresponds to clearerr(), i.e., clears 'eof' and 'error' |
760ac839 |
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 |
510d21e9 |
149 | have the stdio calls then they are implemented in terms of PerlIO_tell() |
760ac839 |
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 | |
5f05dabc |
159 | This corresponds to tmpfile(), i.e., returns an anonymous |
760ac839 |
160 | PerlIO which will automatically be deleted when closed. |
161 | |
162 | =back |
163 | |
510d21e9 |
164 | =head2 Co-existence with stdio |
760ac839 |
165 | |
510d21e9 |
166 | There is outline support for co-existence of PerlIO with stdio. |
760ac839 |
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 |
5f05dabc |
204 | further discussion. (Perl core uses it I<only> when "dumping" |
760ac839 |
205 | is 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 |
5f05dabc |
212 | by Configure. This section is really of interest to only those |
760ac839 |
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 |
5f05dabc |
239 | allow perl's fast code to handle <FILE> mechanism. |
760ac839 |
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 |
5f05dabc |
248 | buffer. Should be used only to set |
760ac839 |
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. |
5f05dabc |
255 | Currently used in only doio.c to force count < -1 to -1. |
760ac839 |
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 |