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

TIE Interface

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

Deprecated API

347       The following methods are deprecated, Apache plans to remove those in
348       the future, therefore avoid using them.
349
350       "get_client_block"
351
352       This method is deprecated since the C implementation is buggy and we
353       don't want you to use it at all. Instead use the plain "$r->read()".
354
355       "setup_client_block"
356
357       This method is deprecated since "$r->get_client_block" is deprecated.
358
359       "should_client_block"
360
361       This method is deprecated since "$r->get_client_block" is deprecated.
362

Copyright

367       mod_perl 2.0 and its core modules are copyrighted under The Apache
368       Software License, Version 2.0.
369

Authors

371       The mod_perl development team and numerous contributors.
372
373
374
375perl v5.8.8                       2006-11-19  docs::api::Apache2::RequestIO(3)