Apache2::RequestIO(3pm)

1docs::api::Apache2::ReqUuseesrtICOo(n3t)ributed Perl Docduomcesn:t:aatpiio:n:Apache2::RequestIO(3)
2
3
4

NAME

6       Apache2::RequestIO - Perl API for Apache request record IO
7

Synopsis

9         use Apache2::RequestIO ();
10
11         $rc = $r->discard_request_body();
12
13         $r->print("foo", "bar");
14         $r->puts("foo", "bar"); # same as print, but no flushing
15         $r->printf("%s $d", "foo", 5);
16
17         $r->read($buffer, $len);
18
19         $r->rflush();
20
21         $r->sendfile($filename);
22
23         $r->write("foobartarcar", 3, 5);
24

Description

26       "Apache2::RequestIO" provides the API to perform IO on the Apache
27       request object.
28

API

30       "Apache2::RequestIO" provides the following functions and/or methods:
31
32   "discard_request_body"
33       In HTTP/1.1, any method can have a body.  However, most GET handlers
34       wouldn't know what to do with a request body if they received one.
35       This helper routine tests for and reads any message body in the
36       request, simply discarding whatever it receives.  We need to do this
37       because failing to read the request body would cause it to be
38       interpreted as the next request on a persistent connection.
39
40         $rc = $r->discard_request_body();
41
42       obj: $r ( "Apache2::RequestRec object" )
43           The current request
44
45       ret: $rc ( integer )
46           "APR::Const status constant" if request is malformed,
47           "Apache2::Const::OK" otherwise.
48
49       since: 2.0.00
50
51       Since we return an error status if the request is malformed, this
52       routine should be called at the beginning of a no-body handler, e.g.,
53
54          use Apache2::Const -compile => qw(OK);
55          $rc = $r->discard_request_body;
56          return $rc if $rc != Apache2::Const::OK;
57
58   "print"
59       Send data to the client.
60
61         $cnt = $r->print(@msg);
62
63       obj: $r ( "Apache2::RequestRec object" )
64       arg1: @msg ( ARRAY )
65           Data to send
66
67       ret: $cnt ( number )
68           How many bytes were sent (or buffered).  If zero bytes were sent,
69           "print" will return 0E0, or "zero but true," which will still
70           evaluate to 0 in a numerical context.
71
72       excpt: "APR::Error"
73       since: 2.0.00
74
75       The data is flushed only if STDOUT stream's $| is true. Otherwise it's
76       buffered up to the size of the buffer, flushing only excessive data.
77
78   "printf"
79       Format and send data to the client (same as "printf").
80
81         $cnt = $r->printf($format, @args);
82
83       obj: $r ( "Apache2::RequestRec object" )
84       arg1: $format ( string )
85           Format string, as in the Perl core "printf" function.
86
87       arg2: @args ( ARRAY )
88           Arguments to be formatted, as in the Perl core "printf" function.
89
90       ret: $cnt ( number )
91           How many bytes were sent (or buffered)
92
93       excpt: "APR::Error"
94       since: 2.0.00
95
96       The data is flushed only if STDOUT stream's $| is true. Otherwise it's
97       buffered up to the size of the buffer, flushing only excessive data.
98
99   "puts"
100       Send data to the client
101
102         $cnt = $r->puts(@msg);
103
104       obj: $r ( "Apache2::RequestRec object" )
105       arg1: @msg ( ARRAY )
106           Data to send
107
108       ret: $cnt ( number )
109           How many bytes were sent (or buffered)
110
111       excpt: "APR::Error"
112       since: 2.0.00
113
114       "puts()" is similar to "print()", but it won't attempt to flush data,
115       no matter what the value of STDOUT stream's $| is. Therefore assuming
116       that STDOUT stream's $| is true, this method should be a tiny bit
117       faster than "print()", especially if small strings are printed.
118
119   "read"
120       Read data from the client.
121
122         $cnt = $r->read($buffer, $len);
123         $cnt = $r->read($buffer, $len, $offset);
124
125       obj: $r ( "Apache2::RequestRec object" )
126       arg1: $buffer ( SCALAR )
127           The buffer to populate with the read data
128
129       arg2: $len ( number )
130           How many bytes to attempt to read
131
132       opt arg3: $offset ( number )
133           If a non-zero $offset is specified, the read data will be placed at
134           that offset in the $buffer.
135
136           META: negative offset and \0 padding are not supported at the
137           moment
138
139       ret: $cnt ( number )
140           How many characters were actually read
141
142       excpt: "APR::Error"
143       since: 2.0.00
144
145       This method shares a lot of similarities with the Perl core "read()"
146       function. The main difference in the error handling, which is done via
147       "APR::Error exceptions"
148
149   "rflush"
150       Flush any buffered data to the client.
151
152         $r->rflush();
153
154       obj: $r ( "Apache2::RequestRec object" )
155       ret: no return value
156       since: 2.0.00
157
158       Unless STDOUT stream's $| is false, data sent via "$r->print()" is
159       buffered. This method flushes that data to the client.
160
161   "sendfile"
162       Send a file or a part of it
163
164         $rc = $r->sendfile($filename);
165         $rc = $r->sendfile($filename, $offset);
166         $rc = $r->sendfile($filename, $offset, $len);
167
168       obj: $r ( "Apache2::RequestRec object" )
169       arg1: $filename ( string )
170           The full path to the file (using "/" on all systems)
171
172       opt arg2: $offset ( integer )
173           Offset into the file to start sending.
174
175           No offset is used if $offset is not specified.
176
177       opt arg3: $len ( integer )
178           How many bytes to send.
179
180           If not specified the whole file is sent (or a part of it, if
181           $offset if specified)
182
183       ret: $rc ( "APR::Const status constant" )
184           On success, "APR::Const::SUCCESS" is returned.
185
186           In case of a failure -- a failure code is returned, in which case
187           normally it should be returned to the caller.
188
189       excpt: "APR::Error"
190           Exceptions are thrown only when this function is called in the VOID
191           context. So if you don't want to handle the errors, just don't ask
192           for a return value and the function will handle all the errors on
193           its own.
194
195       since: 2.0.00
196
197   "write"
198       Send partial string to the client
199
200         $cnt = $r->write($buffer);
201         $cnt = $r->write($buffer, $len);
202         $cnt = $r->write($buffer, $len, $offset);
203
204       obj: $r ( "Apache2::RequestRec object" )
205       arg1: $buffer ( SCALAR )
206           The string with data
207
208       opt arg2: $len ( SCALAR )
209           How many bytes to send. If not specified, or -1 is specified, all
210           the data in $buffer (or starting from $offset) will be sent.
211
212       opt arg3: $offset ( number )
213           Offset into the $buffer string.
214
215       ret: $cnt ( number )
216           How many bytes were sent (or buffered)
217
218       excpt: "APR::Error"
219       since: 2.0.00
220
221       Examples:
222
223       Assuming that we have a string:
224
225         $string = "123456789";
226
227       Then:
228
229         $r->write($string);
230
231       sends:
232
233         123456789
234
235       Whereas:
236
237         $r->write($string, 3);
238
239       sends:
240
241         123
242
243       And:
244
245         $r->write($string, 3, 5);
246
247       sends:
248
249         678
250
251       Finally:
252
253         $r->write($string, -1, 5);
254
255       sends:
256
257         6789
258

TIE Interface

260       The TIE interface implementation. This interface is used for HTTP
261       request handlers, when running under "SetHandler perl-script" and Perl
262       doesn't have perlio enabled.
263
264       See the perltie manpage for more information.
265
266   "BINMODE"
267       since: 2.0.00
268
269       NoOP
270
271       See the binmode Perl entry in the perlfunc manpage
272
273   "CLOSE"
274       since: 2.0.00
275
276       NoOP
277
278       See the close Perl entry in the perlfunc manpage
279
280   "FILENO"
281       since: 2.0.00
282
283       See the fileno Perl entry in the perlfunc manpage
284
285   "GETC"
286       since: 2.0.00
287
288       See the getc Perl entry in the perlfunc manpage
289
290   "OPEN"
291       since: 2.0.00
292
293       See the open Perl entry in the perlfunc manpage
294
295   "PRINT"
296       since: 2.0.00
297
298       See the print Perl entry in the perlfunc manpage
299
300   "PRINTF"
301       since: 2.0.00
302
303       See the printf Perl entry in the perlfunc manpage
304
305   "READ"
306       since: 2.0.00
307
308       See the read Perl entry in the perlfunc manpage
309
310   "TIEHANDLE"
311       since: 2.0.00
312
313       See the tie Perl entry in the perlfunc manpage
314
315   "UNTIE"
316       since: 2.0.00
317
318       NoOP
319
320       See the untie Perl entry in the perlfunc manpage
321
322   "WRITE"
323       since: 2.0.00
324
325       See the write Perl entry in the perlfunc manpage
326

Deprecated API

328       The following methods are deprecated, Apache plans to remove those in
329       the future, therefore avoid using them.
330
331   "get_client_block"
332       This method is deprecated since the C implementation is buggy and we
333       don't want you to use it at all. Instead use the plain "$r->read()".
334
335   "setup_client_block"
336       This method is deprecated since "$r->get_client_block" is deprecated.
337
338   "should_client_block"
339       This method is deprecated since "$r->get_client_block" is deprecated.
340

Copyright

345       mod_perl 2.0 and its core modules are copyrighted under The Apache
346       Software License, Version 2.0.
347

Authors

349       The mod_perl development team and numerous contributors.
350
351
352
353perl v5.12.0                      2007-11-12  docs::api::Apache2::RequestIO(3)