Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLAPIO 1" | |
132 | .TH PERLAPIO 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perlapio \- perl's IO abstraction interface. | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 2 | |
138 | \& #define PERLIO_NOT_STDIO 0 /* For co-existence with stdio only */ | |
139 | \& #include <perlio.h> /* Usually via #include <perl.h> */ | |
140 | .Ve | |
141 | .PP | |
142 | .Vb 3 | |
143 | \& PerlIO *PerlIO_stdin(void); | |
144 | \& PerlIO *PerlIO_stdout(void); | |
145 | \& PerlIO *PerlIO_stderr(void); | |
146 | .Ve | |
147 | .PP | |
148 | .Vb 4 | |
149 | \& PerlIO *PerlIO_open(const char *path,const char *mode); | |
150 | \& PerlIO *PerlIO_fdopen(int fd, const char *mode); | |
151 | \& PerlIO *PerlIO_reopen(const char *path, const char *mode, PerlIO *old); /* deprecated */ | |
152 | \& int PerlIO_close(PerlIO *f); | |
153 | .Ve | |
154 | .PP | |
155 | .Vb 7 | |
156 | \& int PerlIO_stdoutf(const char *fmt,...) | |
157 | \& int PerlIO_puts(PerlIO *f,const char *string); | |
158 | \& int PerlIO_putc(PerlIO *f,int ch); | |
159 | \& int PerlIO_write(PerlIO *f,const void *buf,size_t numbytes); | |
160 | \& int PerlIO_printf(PerlIO *f, const char *fmt,...); | |
161 | \& int PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args); | |
162 | \& int PerlIO_flush(PerlIO *f); | |
163 | .Ve | |
164 | .PP | |
165 | .Vb 3 | |
166 | \& int PerlIO_eof(PerlIO *f); | |
167 | \& int PerlIO_error(PerlIO *f); | |
168 | \& void PerlIO_clearerr(PerlIO *f); | |
169 | .Ve | |
170 | .PP | |
171 | .Vb 3 | |
172 | \& int PerlIO_getc(PerlIO *d); | |
173 | \& int PerlIO_ungetc(PerlIO *f,int ch); | |
174 | \& int PerlIO_read(PerlIO *f, void *buf, size_t numbytes); | |
175 | .Ve | |
176 | .PP | |
177 | .Vb 1 | |
178 | \& int PerlIO_fileno(PerlIO *f); | |
179 | .Ve | |
180 | .PP | |
181 | .Vb 1 | |
182 | \& void PerlIO_setlinebuf(PerlIO *f); | |
183 | .Ve | |
184 | .PP | |
185 | .Vb 3 | |
186 | \& Off_t PerlIO_tell(PerlIO *f); | |
187 | \& int PerlIO_seek(PerlIO *f, Off_t offset, int whence); | |
188 | \& void PerlIO_rewind(PerlIO *f); | |
189 | .Ve | |
190 | .PP | |
191 | .Vb 2 | |
192 | \& int PerlIO_getpos(PerlIO *f, SV *save); /* prototype changed */ | |
193 | \& int PerlIO_setpos(PerlIO *f, SV *saved); /* prototype changed */ | |
194 | .Ve | |
195 | .PP | |
196 | .Vb 5 | |
197 | \& int PerlIO_fast_gets(PerlIO *f); | |
198 | \& int PerlIO_has_cntptr(PerlIO *f); | |
199 | \& int PerlIO_get_cnt(PerlIO *f); | |
200 | \& char *PerlIO_get_ptr(PerlIO *f); | |
201 | \& void PerlIO_set_ptrcnt(PerlIO *f, char *ptr, int count); | |
202 | .Ve | |
203 | .PP | |
204 | .Vb 2 | |
205 | \& int PerlIO_canset_cnt(PerlIO *f); /* deprecated */ | |
206 | \& void PerlIO_set_cnt(PerlIO *f, int count); /* deprecated */ | |
207 | .Ve | |
208 | .PP | |
209 | .Vb 3 | |
210 | \& int PerlIO_has_base(PerlIO *f); | |
211 | \& char *PerlIO_get_base(PerlIO *f); | |
212 | \& int PerlIO_get_bufsiz(PerlIO *f); | |
213 | .Ve | |
214 | .PP | |
215 | .Vb 4 | |
216 | \& PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode); | |
217 | \& FILE *PerlIO_exportFILE(PerlIO *f, int flags); | |
218 | \& FILE *PerlIO_findFILE(PerlIO *f); | |
219 | \& void PerlIO_releaseFILE(PerlIO *f,FILE *stdio); | |
220 | .Ve | |
221 | .PP | |
222 | .Vb 3 | |
223 | \& int PerlIO_apply_layers(PerlIO *f, const char *mode, const char *layers); | |
224 | \& int PerlIO_binmode(PerlIO *f, int ptype, int imode, const char *layers); | |
225 | \& void PerlIO_debug(const char *fmt,...) | |
226 | .Ve | |
227 | .SH "DESCRIPTION" | |
228 | .IX Header "DESCRIPTION" | |
229 | Perl's source code, and extensions that want maximum portability, | |
230 | should use the above functions instead of those defined in \s-1ANSI\s0 C's | |
231 | \&\fIstdio.h\fR. The perl headers (in particular \*(L"perlio.h\*(R") will | |
232 | \&\f(CW\*(C`#define\*(C'\fR them to the I/O mechanism selected at Configure time. | |
233 | .PP | |
234 | The functions are modeled on those in \fIstdio.h\fR, but parameter order | |
235 | has been \*(L"tidied up a little\*(R". | |
236 | .PP | |
237 | \&\f(CW\*(C`PerlIO *\*(C'\fR takes the place of \s-1FILE\s0 *. Like \s-1FILE\s0 * it should be | |
238 | treated as opaque (it is probably safe to assume it is a pointer to | |
239 | something). | |
240 | .PP | |
241 | There are currently three implementations: | |
242 | .IP "1. \s-1USE_STDIO\s0" 4 | |
243 | .IX Item "1. USE_STDIO" | |
244 | All above are #define'd to stdio functions or are trivial wrapper | |
245 | functions which call stdio. In this case \fIonly\fR PerlIO * is a \s-1FILE\s0 *. | |
246 | This has been the default implementation since the abstraction was | |
247 | introduced in perl5.003_02. | |
248 | .IP "2. \s-1USE_SFIO\s0" 4 | |
249 | .IX Item "2. USE_SFIO" | |
250 | A \*(L"legacy\*(R" implementation in terms of the \*(L"sfio\*(R" library. Used for | |
251 | some specialist applications on Unix machines (\*(L"sfio\*(R" is not widely | |
252 | ported away from Unix). Most of above are #define'd to the sfio | |
253 | functions. PerlIO * is in this case Sfio_t *. | |
254 | .IP "3. \s-1USE_PERLIO\s0" 4 | |
255 | .IX Item "3. USE_PERLIO" | |
256 | Introduced just after perl5.7.0, this is a re-implementation of the | |
257 | above abstraction which allows perl more control over how \s-1IO\s0 is done | |
258 | as it decouples \s-1IO\s0 from the way the operating system and C library | |
259 | choose to do things. For \s-1USE_PERLIO\s0 PerlIO * has an extra layer of | |
260 | indirection \- it is a pointer\-to\-a\-pointer. This allows the PerlIO * | |
261 | to remain with a known value while swapping the implementation around | |
262 | underneath \fIat run time\fR. In this case all the above are true (but | |
263 | very simple) functions which call the underlying implementation. | |
264 | .Sp | |
265 | This is the only implementation for which \f(CW\*(C`PerlIO_apply_layers()\*(C'\fR | |
266 | does anything \*(L"interesting\*(R". | |
267 | .Sp | |
268 | The \s-1USE_PERLIO\s0 implementation is described in perliol. | |
269 | .PP | |
270 | Because \*(L"perlio.h\*(R" is a thin layer (for efficiency) the semantics of | |
271 | these functions are somewhat dependent on the underlying implementation. | |
272 | Where these variations are understood they are noted below. | |
273 | .PP | |
274 | Unless otherwise noted, functions return 0 on success, or a negative | |
275 | value (usually \f(CW\*(C`EOF\*(C'\fR which is usually \-1) and set \f(CW\*(C`errno\*(C'\fR on error. | |
276 | .IP "\fB\f(BIPerlIO_stdin()\fB\fR, \fB\f(BIPerlIO_stdout()\fB\fR, \fB\f(BIPerlIO_stderr()\fB\fR" 4 | |
277 | .IX Item "PerlIO_stdin(), PerlIO_stdout(), PerlIO_stderr()" | |
278 | Use these rather than \f(CW\*(C`stdin\*(C'\fR, \f(CW\*(C`stdout\*(C'\fR, \f(CW\*(C`stderr\*(C'\fR. They are written | |
279 | to look like \*(L"function calls\*(R" rather than variables because this makes | |
280 | it easier to \fImake them\fR function calls if platform cannot export data | |
281 | to loaded modules, or if (say) different \*(L"threads\*(R" might have different | |
282 | values. | |
283 | .IP "\fBPerlIO_open(path, mode)\fR, \fBPerlIO_fdopen(fd,mode)\fR" 4 | |
284 | .IX Item "PerlIO_open(path, mode), PerlIO_fdopen(fd,mode)" | |
285 | These correspond to \fIfopen()\fR/\fIfdopen()\fR and the arguments are the same. | |
286 | Return \f(CW\*(C`NULL\*(C'\fR and set \f(CW\*(C`errno\*(C'\fR if there is an error. There may be an | |
287 | implementation limit on the number of open handles, which may be lower | |
288 | than the limit on the number of open files \- \f(CW\*(C`errno\*(C'\fR may not be set | |
289 | when \f(CW\*(C`NULL\*(C'\fR is returned if this limit is exceeded. | |
290 | .IP "\fBPerlIO_reopen(path,mode,f)\fR" 4 | |
291 | .IX Item "PerlIO_reopen(path,mode,f)" | |
292 | While this currently exists in all three implementations perl itself | |
293 | does not use it. \fIAs perl does not use it, it is not well tested.\fR | |
294 | .Sp | |
295 | Perl prefers to \f(CW\*(C`dup\*(C'\fR the new low-level descriptor to the descriptor | |
296 | used by the existing PerlIO. This may become the behaviour of this | |
297 | function in the future. | |
298 | .IP "\fBPerlIO_printf(f,fmt,...)\fR, \fBPerlIO_vprintf(f,fmt,a)\fR" 4 | |
299 | .IX Item "PerlIO_printf(f,fmt,...), PerlIO_vprintf(f,fmt,a)" | |
300 | These are \fIfprintf()\fR/\fIvfprintf()\fR equivalents. | |
301 | .IP "\fBPerlIO_stdoutf(fmt,...)\fR" 4 | |
302 | .IX Item "PerlIO_stdoutf(fmt,...)" | |
303 | This is \fIprintf()\fR equivalent. printf is #defined to this function, | |
304 | so it is (currently) legal to use \f(CW\*(C`printf(fmt,...)\*(C'\fR in perl sources. | |
305 | .IP "\fBPerlIO_read(f,buf,count)\fR, \fBPerlIO_write(f,buf,count)\fR" 4 | |
306 | .IX Item "PerlIO_read(f,buf,count), PerlIO_write(f,buf,count)" | |
307 | These correspond functionally to \fIfread()\fR and \fIfwrite()\fR but the | |
308 | arguments and return values are different. The \fIPerlIO_read()\fR and | |
309 | \&\fIPerlIO_write()\fR signatures have been modeled on the more sane low level | |
310 | \&\fIread()\fR and \fIwrite()\fR functions instead: The \*(L"file\*(R" argument is passed | |
311 | first, there is only one \*(L"count\*(R", and the return value can distinguish | |
312 | between error and \f(CW\*(C`EOF\*(C'\fR. | |
313 | .Sp | |
314 | Returns a byte count if successful (which may be zero or | |
315 | positive), returns negative value and sets \f(CW\*(C`errno\*(C'\fR on error. | |
316 | Depending on implementation \f(CW\*(C`errno\*(C'\fR may be \f(CW\*(C`EINTR\*(C'\fR if operation was | |
317 | interrupted by a signal. | |
318 | .IP "\fBPerlIO_close(f)\fR" 4 | |
319 | .IX Item "PerlIO_close(f)" | |
320 | Depending on implementation \f(CW\*(C`errno\*(C'\fR may be \f(CW\*(C`EINTR\*(C'\fR if operation was | |
321 | interrupted by a signal. | |
322 | .IP "\fBPerlIO_puts(f,s)\fR, \fBPerlIO_putc(f,c)\fR" 4 | |
323 | .IX Item "PerlIO_puts(f,s), PerlIO_putc(f,c)" | |
324 | These correspond to \fIfputs()\fR and \fIfputc()\fR. | |
325 | Note that arguments have been revised to have \*(L"file\*(R" first. | |
326 | .IP "\fBPerlIO_ungetc(f,c)\fR" 4 | |
327 | .IX Item "PerlIO_ungetc(f,c)" | |
328 | This corresponds to \fIungetc()\fR. Note that arguments have been revised | |
329 | to have \*(L"file\*(R" first. Arranges that next read operation will return | |
330 | the byte \fBc\fR. Despite the implied \*(L"character\*(R" in the name only | |
331 | values in the range 0..0xFF are defined. Returns the byte \fBc\fR on | |
332 | success or \-1 (\f(CW\*(C`EOF\*(C'\fR) on error. The number of bytes that can be | |
333 | \&\*(L"pushed back\*(R" may vary, only 1 character is certain, and then only if | |
334 | it is the last character that was read from the handle. | |
335 | .IP "\fBPerlIO_getc(f)\fR" 4 | |
336 | .IX Item "PerlIO_getc(f)" | |
337 | This corresponds to \fIgetc()\fR. | |
338 | Despite the c in the name only byte range 0..0xFF is supported. | |
339 | Returns the character read or \-1 (\f(CW\*(C`EOF\*(C'\fR) on error. | |
340 | .IP "\fBPerlIO_eof(f)\fR" 4 | |
341 | .IX Item "PerlIO_eof(f)" | |
342 | This corresponds to \fIfeof()\fR. Returns a true/false indication of | |
343 | whether the handle is at end of file. For terminal devices this may | |
344 | or may not be \*(L"sticky\*(R" depending on the implementation. The flag is | |
345 | cleared by \fIPerlIO_seek()\fR, or \fIPerlIO_rewind()\fR. | |
346 | .IP "\fBPerlIO_error(f)\fR" 4 | |
347 | .IX Item "PerlIO_error(f)" | |
348 | This corresponds to \fIferror()\fR. Returns a true/false indication of | |
349 | whether there has been an \s-1IO\s0 error on the handle. | |
350 | .IP "\fBPerlIO_fileno(f)\fR" 4 | |
351 | .IX Item "PerlIO_fileno(f)" | |
352 | This corresponds to \fIfileno()\fR, note that on some platforms, the meaning | |
353 | of \*(L"fileno\*(R" may not match Unix. Returns \-1 if the handle has no open | |
354 | descriptor associated with it. | |
355 | .IP "\fBPerlIO_clearerr(f)\fR" 4 | |
356 | .IX Item "PerlIO_clearerr(f)" | |
357 | This corresponds to \fIclearerr()\fR, i.e., clears 'error' and (usually) | |
358 | \&'eof' flags for the \*(L"stream\*(R". Does not return a value. | |
359 | .IP "\fBPerlIO_flush(f)\fR" 4 | |
360 | .IX Item "PerlIO_flush(f)" | |
361 | This corresponds to \fIfflush()\fR. Sends any buffered write data to the | |
362 | underlying file. If called with \f(CW\*(C`NULL\*(C'\fR this may flush all open | |
363 | streams (or core dump with some \s-1USE_STDIO\s0 implementations). Calling | |
364 | on a handle open for read only, or on which last operation was a read | |
365 | of some kind may lead to undefined behaviour on some \s-1USE_STDIO\s0 | |
366 | implementations. The \s-1USE_PERLIO\s0 (layers) implementation tries to | |
367 | behave better: it flushes all open streams when passed \f(CW\*(C`NULL\*(C'\fR, and | |
368 | attempts to retain data on read streams either in the buffer or by | |
369 | seeking the handle to the current logical position. | |
370 | .IP "\fBPerlIO_seek(f,offset,whence)\fR" 4 | |
371 | .IX Item "PerlIO_seek(f,offset,whence)" | |
372 | This corresponds to \fIfseek()\fR. Sends buffered write data to the | |
373 | underlying file, or discards any buffered read data, then positions | |
374 | the file descriptor as specified by \fBoffset\fR and \fBwhence\fR (sic). | |
375 | This is the correct thing to do when switching between read and write | |
376 | on the same handle (see issues with \fIPerlIO_flush()\fR above). Offset is | |
377 | of type \f(CW\*(C`Off_t\*(C'\fR which is a perl Configure value which may not be same | |
378 | as stdio's \f(CW\*(C`off_t\*(C'\fR. | |
379 | .IP "\fBPerlIO_tell(f)\fR" 4 | |
380 | .IX Item "PerlIO_tell(f)" | |
381 | This corresponds to \fIftell()\fR. Returns the current file position, or | |
382 | (Off_t) \-1 on error. May just return value system \*(L"knows\*(R" without | |
383 | making a system call or checking the underlying file descriptor (so | |
384 | use on shared file descriptors is not safe without a | |
385 | \&\fIPerlIO_seek()\fR). Return value is of type \f(CW\*(C`Off_t\*(C'\fR which is a perl | |
386 | Configure value which may not be same as stdio's \f(CW\*(C`off_t\*(C'\fR. | |
387 | .IP "\fBPerlIO_getpos(f,p)\fR, \fBPerlIO_setpos(f,p)\fR" 4 | |
388 | .IX Item "PerlIO_getpos(f,p), PerlIO_setpos(f,p)" | |
389 | These correspond (loosely) to \fIfgetpos()\fR and \fIfsetpos()\fR. Rather than | |
390 | stdio's Fpos_t they expect a \*(L"Perl Scalar Value\*(R" to be passed. What is | |
391 | stored there should be considered opaque. The layout of the data may | |
392 | vary from handle to handle. When not using stdio or if platform does | |
393 | not have the stdio calls then they are implemented in terms of | |
394 | \&\fIPerlIO_tell()\fR and \fIPerlIO_seek()\fR. | |
395 | .IP "\fBPerlIO_rewind(f)\fR" 4 | |
396 | .IX Item "PerlIO_rewind(f)" | |
397 | This corresponds to \fIrewind()\fR. It is usually defined as being | |
398 | .Sp | |
399 | .Vb 2 | |
400 | \& PerlIO_seek(f,(Off_t)0L, SEEK_SET); | |
401 | \& PerlIO_clearerr(f); | |
402 | .Ve | |
403 | .IP "\fB\f(BIPerlIO_tmpfile()\fB\fR" 4 | |
404 | .IX Item "PerlIO_tmpfile()" | |
405 | This corresponds to \fItmpfile()\fR, i.e., returns an anonymous PerlIO or | |
406 | \&\s-1NULL\s0 on error. The system will attempt to automatically delete the | |
407 | file when closed. On Unix the file is usually \f(CW\*(C`unlink\*(C'\fR\-ed just after | |
408 | it is created so it does not matter how it gets closed. On other | |
409 | systems the file may only be deleted if closed via \fIPerlIO_close()\fR | |
410 | and/or the program exits via \f(CW\*(C`exit\*(C'\fR. Depending on the implementation | |
411 | there may be \*(L"race conditions\*(R" which allow other processes access to | |
412 | the file, though in general it will be safer in this regard than | |
413 | ad. hoc. schemes. | |
414 | .IP "\fBPerlIO_setlinebuf(f)\fR" 4 | |
415 | .IX Item "PerlIO_setlinebuf(f)" | |
416 | This corresponds to \fIsetlinebuf()\fR. Does not return a value. What | |
417 | constitutes a \*(L"line\*(R" is implementation dependent but usually means | |
418 | that writing \*(L"\en\*(R" flushes the buffer. What happens with things like | |
419 | \&\*(L"this\enthat\*(R" is uncertain. (Perl core uses it \fIonly\fR when \*(L"dumping\*(R"; | |
420 | it has nothing to do with $| auto\-flush.) | |
421 | .Sh "Co-existence with stdio" | |
422 | .IX Subsection "Co-existence with stdio" | |
423 | There is outline support for co-existence of PerlIO with stdio. | |
424 | Obviously if PerlIO is implemented in terms of stdio there is no | |
425 | problem. However in other cases then mechanisms must exist to create a | |
426 | \&\s-1FILE\s0 * which can be passed to library code which is going to use stdio | |
427 | calls. | |
428 | .PP | |
429 | The first step is to add this line: | |
430 | .PP | |
431 | .Vb 1 | |
432 | \& #define PERLIO_NOT_STDIO 0 | |
433 | .Ve | |
434 | .PP | |
435 | \&\fIbefore\fR including any perl header files. (This will probably become | |
436 | the default at some point). That prevents \*(L"perlio.h\*(R" from attempting | |
437 | to #define stdio functions onto PerlIO functions. | |
438 | .PP | |
439 | \&\s-1XS\s0 code is probably better using \*(L"typemap\*(R" if it expects \s-1FILE\s0 * | |
440 | arguments. The standard typemap will be adjusted to comprehend any | |
441 | changes in this area. | |
442 | .IP "\fBPerlIO_importFILE(f,mode)\fR" 4 | |
443 | .IX Item "PerlIO_importFILE(f,mode)" | |
444 | Used to get a PerlIO * from a \s-1FILE\s0 *. | |
445 | .Sp | |
446 | The mode argument should be a string as would be passed to | |
447 | fopen/PerlIO_open. If it is \s-1NULL\s0 then \- for legacy support \- the code | |
448 | will (depending upon the platform and the implementation) either | |
449 | attempt to empirically determine the mode in which \fIf\fR is open, or | |
450 | use \*(L"r+\*(R" to indicate a read/write stream. | |
451 | .Sp | |
452 | Once called the \s-1FILE\s0 * should \fI\s-1ONLY\s0\fR be closed by calling | |
453 | \&\f(CW\*(C`PerlIO_close()\*(C'\fR on the returned PerlIO *. | |
454 | .Sp | |
455 | The PerlIO is set to textmode. Use PerlIO_binmode if this is | |
456 | not the desired mode. | |
457 | .Sp | |
458 | This is \fBnot\fR the reverse of \fIPerlIO_exportFILE()\fR. | |
459 | .IP "\fBPerlIO_exportFILE(f,mode)\fR" 4 | |
460 | .IX Item "PerlIO_exportFILE(f,mode)" | |
461 | Given a PerlIO * create a 'native' \s-1FILE\s0 * suitable for passing to code | |
462 | expecting to be compiled and linked with \s-1ANSI\s0 C \fIstdio.h\fR. The mode | |
463 | argument should be a string as would be passed to fopen/PerlIO_open. | |
464 | If it is \s-1NULL\s0 then \- for legacy support \- the \s-1FILE\s0 * is opened in same | |
465 | mode as the PerlIO *. | |
466 | .Sp | |
467 | The fact that such a \s-1FILE\s0 * has been 'exported' is recorded, (normally | |
468 | by pushing a new :stdio \*(L"layer\*(R" onto the PerlIO *), which may affect | |
469 | future PerlIO operations on the original PerlIO *. You should not | |
470 | call \f(CW\*(C`fclose()\*(C'\fR on the file unless you call \f(CW\*(C`PerlIO_releaseFILE()\*(C'\fR | |
471 | to disassociate it from the PerlIO *. (Do not use \fIPerlIO_importFILE()\fR | |
472 | for doing the disassociation.) | |
473 | .Sp | |
474 | Calling this function repeatedly will create a \s-1FILE\s0 * on each call | |
475 | (and will push an :stdio layer each time as well). | |
476 | .IP "\fBPerlIO_releaseFILE(p,f)\fR" 4 | |
477 | .IX Item "PerlIO_releaseFILE(p,f)" | |
478 | Calling PerlIO_releaseFILE informs PerlIO that all use of \s-1FILE\s0 * is | |
479 | complete. It is removed from the list of 'exported' \s-1FILE\s0 *s, and the | |
480 | associated PerlIO * should revert to its original behaviour. | |
481 | .Sp | |
482 | Use this to disassociate a file from a PerlIO * that was associated | |
483 | using \fIPerlIO_exportFILE()\fR. | |
484 | .IP "\fBPerlIO_findFILE(f)\fR" 4 | |
485 | .IX Item "PerlIO_findFILE(f)" | |
486 | Returns a native \s-1FILE\s0 * used by a stdio layer. If there is none, it | |
487 | will create one with PerlIO_exportFILE. In either case the \s-1FILE\s0 * | |
488 | should be considered as belonging to PerlIO subsystem and should | |
489 | only be closed by calling \f(CW\*(C`PerlIO_close()\*(C'\fR. | |
490 | .ie n .Sh """Fast gets"" Functions" | |
491 | .el .Sh "``Fast gets'' Functions" | |
492 | .IX Subsection "Fast gets Functions" | |
493 | In addition to standard-like \s-1API\s0 defined so far above there is an | |
494 | \&\*(L"implementation\*(R" interface which allows perl to get at internals of | |
495 | PerlIO. The following calls correspond to the various FILE_xxx macros | |
496 | determined by Configure \- or their equivalent in other | |
497 | implementations. This section is really of interest to only those | |
498 | concerned with detailed perl-core behaviour, implementing a PerlIO | |
499 | mapping or writing code which can make use of the \*(L"read ahead\*(R" that | |
500 | has been done by the \s-1IO\s0 system in the same way perl does. Note that | |
501 | any code that uses these interfaces must be prepared to do things the | |
502 | traditional way if a handle does not support them. | |
503 | .IP "\fBPerlIO_fast_gets(f)\fR" 4 | |
504 | .IX Item "PerlIO_fast_gets(f)" | |
505 | Returns true if implementation has all the interfaces required to | |
506 | allow perl's \f(CW\*(C`sv_gets\*(C'\fR to \*(L"bypass\*(R" normal \s-1IO\s0 mechanism. This can | |
507 | vary from handle to handle. | |
508 | .Sp | |
509 | .Vb 3 | |
510 | \& PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \e | |
511 | \& PerlIO_canset_cnt(f) && \e | |
512 | \& `Can set pointer into buffer' | |
513 | .Ve | |
514 | .IP "\fBPerlIO_has_cntptr(f)\fR" 4 | |
515 | .IX Item "PerlIO_has_cntptr(f)" | |
516 | Implementation can return pointer to current position in the \*(L"buffer\*(R" | |
517 | and a count of bytes available in the buffer. Do not use this \- use | |
518 | PerlIO_fast_gets. | |
519 | .IP "\fBPerlIO_get_cnt(f)\fR" 4 | |
520 | .IX Item "PerlIO_get_cnt(f)" | |
521 | Return count of readable bytes in the buffer. Zero or negative return | |
522 | means no more bytes available. | |
523 | .IP "\fBPerlIO_get_ptr(f)\fR" 4 | |
524 | .IX Item "PerlIO_get_ptr(f)" | |
525 | Return pointer to next readable byte in buffer, accessing via the | |
526 | pointer (dereferencing) is only safe if \fIPerlIO_get_cnt()\fR has returned | |
527 | a positive value. Only positive offsets up to value returned by | |
528 | \&\fIPerlIO_get_cnt()\fR are allowed. | |
529 | .IP "\fBPerlIO_set_ptrcnt(f,p,c)\fR" 4 | |
530 | .IX Item "PerlIO_set_ptrcnt(f,p,c)" | |
531 | Set pointer into buffer, and a count of bytes still in the | |
532 | buffer. Should be used only to set pointer to within range implied by | |
533 | previous calls to \f(CW\*(C`PerlIO_get_ptr\*(C'\fR and \f(CW\*(C`PerlIO_get_cnt\*(C'\fR. The two | |
534 | values \fImust\fR be consistent with each other (implementation may only | |
535 | use one or the other or may require both). | |
536 | .IP "\fBPerlIO_canset_cnt(f)\fR" 4 | |
537 | .IX Item "PerlIO_canset_cnt(f)" | |
538 | Implementation can adjust its idea of number of bytes in the buffer. | |
539 | Do not use this \- use PerlIO_fast_gets. | |
540 | .IP "\fBPerlIO_set_cnt(f,c)\fR" 4 | |
541 | .IX Item "PerlIO_set_cnt(f,c)" | |
542 | Obscure \- set count of bytes in the buffer. Deprecated. Only usable | |
543 | if \fIPerlIO_canset_cnt()\fR returns true. Currently used in only doio.c to | |
544 | force count less than \-1 to \-1. Perhaps should be PerlIO_set_empty or | |
545 | similar. This call may actually do nothing if \*(L"count\*(R" is deduced from | |
546 | pointer and a \*(L"limit\*(R". Do not use this \- use \fIPerlIO_set_ptrcnt()\fR. | |
547 | .IP "\fBPerlIO_has_base(f)\fR" 4 | |
548 | .IX Item "PerlIO_has_base(f)" | |
549 | Returns true if implementation has a buffer, and can return pointer | |
550 | to whole buffer and its size. Used by perl for \fB\-T\fR / \fB\-B\fR tests. | |
551 | Other uses would be very obscure... | |
552 | .IP "\fBPerlIO_get_base(f)\fR" 4 | |
553 | .IX Item "PerlIO_get_base(f)" | |
554 | Return \fIstart\fR of buffer. Access only positive offsets in the buffer | |
555 | up to the value returned by \fIPerlIO_get_bufsiz()\fR. | |
556 | .IP "\fBPerlIO_get_bufsiz(f)\fR" 4 | |
557 | .IX Item "PerlIO_get_bufsiz(f)" | |
558 | Return the \fItotal number of bytes\fR in the buffer, this is neither the | |
559 | number that can be read, nor the amount of memory allocated to the | |
560 | buffer. Rather it is what the operating system and/or implementation | |
561 | happened to \f(CW\*(C`read()\*(C'\fR (or whatever) last time \s-1IO\s0 was requested. | |
562 | .Sh "Other Functions" | |
563 | .IX Subsection "Other Functions" | |
564 | .IP "PerlIO_apply_layers(f,mode,layers)" 4 | |
565 | .IX Item "PerlIO_apply_layers(f,mode,layers)" | |
566 | The new interface to the \s-1USE_PERLIO\s0 implementation. The layers \*(L":crlf\*(R" | |
567 | and \*(L":raw\*(R" are only ones allowed for other implementations and those | |
568 | are silently ignored. (As of perl5.8 \*(L":raw\*(R" is deprecated.) Use | |
569 | \&\fIPerlIO_binmode()\fR below for the portable case. | |
570 | .IP "PerlIO_binmode(f,ptype,imode,layers)" 4 | |
571 | .IX Item "PerlIO_binmode(f,ptype,imode,layers)" | |
572 | The hook used by perl's \f(CW\*(C`binmode\*(C'\fR operator. | |
573 | \&\fBptype\fR is perl's character for the kind of \s-1IO:\s0 | |
574 | .RS 4 | |
575 | .IP "'<' read" 8 | |
576 | .IX Item "'<' read" | |
577 | .PD 0 | |
578 | .IP "'>' write" 8 | |
579 | .IX Item "'>' write" | |
580 | .IP "'+' read/write" 8 | |
581 | .IX Item "'+' read/write" | |
582 | .RE | |
583 | .RS 4 | |
584 | .PD | |
585 | .Sp | |
586 | \&\fBimode\fR is \f(CW\*(C`O_BINARY\*(C'\fR or \f(CW\*(C`O_TEXT\*(C'\fR. | |
587 | .Sp | |
588 | \&\fBlayers\fR is a string of layers to apply, only \*(L":crlf\*(R" makes sense in | |
589 | the non \s-1USE_PERLIO\s0 case. (As of perl5.8 \*(L":raw\*(R" is deprecated in favour | |
590 | of passing \s-1NULL\s0.) | |
591 | .Sp | |
592 | Portable cases are: | |
593 | .Sp | |
594 | .Vb 3 | |
595 | \& PerlIO_binmode(f,ptype,O_BINARY,Nullch); | |
596 | \&and | |
597 | \& PerlIO_binmode(f,ptype,O_TEXT,":crlf"); | |
598 | .Ve | |
599 | .Sp | |
600 | On Unix these calls probably have no effect whatsoever. Elsewhere | |
601 | they alter \*(L"\en\*(R" to \s-1CR\s0,LF translation and possibly cause a special text | |
602 | \&\*(L"end of file\*(R" indicator to be written or honoured on read. The effect | |
603 | of making the call after doing any \s-1IO\s0 to the handle depends on the | |
604 | implementation. (It may be ignored, affect any data which is already | |
605 | buffered as well, or only apply to subsequent data.) | |
606 | .RE | |
607 | .IP "PerlIO_debug(fmt,...)" 4 | |
608 | .IX Item "PerlIO_debug(fmt,...)" | |
609 | PerlIO_debug is a \fIprintf()\fR\-like function which can be used for | |
610 | debugging. No return value. Its main use is inside PerlIO where using | |
611 | real printf, \fIwarn()\fR etc. would recursively call PerlIO and be a | |
612 | problem. | |
613 | .Sp | |
614 | PerlIO_debug writes to the file named by \f(CW$ENV\fR{'\s-1PERLIO_DEBUG\s0'} typical | |
615 | use might be | |
616 | .Sp | |
617 | .Vb 2 | |
618 | \& Bourne shells (sh, ksh, bash, zsh, ash, ...): | |
619 | \& PERLIO_DEBUG=/dev/tty ./perl somescript some args | |
620 | .Ve | |
621 | .Sp | |
622 | .Vb 3 | |
623 | \& Csh/Tcsh: | |
624 | \& setenv PERLIO_DEBUG /dev/tty | |
625 | \& ./perl somescript some args | |
626 | .Ve | |
627 | .Sp | |
628 | .Vb 2 | |
629 | \& If you have the "env" utility: | |
630 | \& env PERLIO_DEBUG=/dev/tty ./perl somescript some args | |
631 | .Ve | |
632 | .Sp | |
633 | .Vb 3 | |
634 | \& Win32: | |
635 | \& set PERLIO_DEBUG=CON | |
636 | \& perl somescript some args | |
637 | .Ve | |
638 | .Sp | |
639 | If \f(CW$ENV\fR{'\s-1PERLIO_DEBUG\s0'} is not set \fIPerlIO_debug()\fR is a no\-op. |