Don't count on 'trap 0' inside () in shell script
[perl.git] / 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 *);
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,
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(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
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 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
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