Commit | Line | Data |
---|---|---|
760ac839 LW |
1 | =head1 NAME |
2 | ||
3 | perlio - 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 *); | |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 LW |
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 |