Apache2::Upload(3pm)

1Apache2::Upload(3)    User Contributed Perl Documentation   Apache2::Upload(3)
2
3
4

NAME

6       Apache2::Upload - Methods for dealing with file uploads.
7

SYNOPSIS

9           use Apache2::Upload;
10
11           $req = Apache2::Request->new($r);
12           $upload = $req->upload("foo");
13           $size = $upload->size;
14
15           # three methods to get at the upload's contents ... slurp, fh, io
16
17           $upload->slurp($slurp_data);
18
19           read $upload->fh, $fh_data, $size;
20           ok $slurp_data eq $fh_data;
21
22           my $io = $upload->io;
23           print while <$io>;
24

DESCRIPTION

26       Apache2::Upload is a new module based on the original package included
27       in Apache2::Request 1.X.  Users requiring the upload API must now "use
28       Apache2::Upload", which adds the "upload" method to Apache2::Request.
29       Apache2::Upload is largely backwards-compatible with the original 1.X
30       API.  See the "PORTING from 1.X" section below for a list of known
31       issues.
32
33       This manpage documents the Apache2::Upload package.
34

Apache2::Upload

36   name
37           $upload->name()
38
39       The name of the HTML form element which generated the upload.
40
41   filename
42           $upload->filename()
43
44       The (client-side) filename as submitted in the HTML form.  Note: some
45       agents will submit the file's full pathname, while others may submit
46       just the basename.
47
48   fh
49           $upload->fh()
50
51       Creates filehandle reference to the upload's spooled tempfile, which
52       contains the full contents of the upload.
53
54   io
55           $upload->io()
56
57       Creates a tied IO handle.  This method is a more efficient version of
58       "fh", but with "io" the handle ref returned is not seekable.  It is
59       tied to an APR::Request::Brigade object, so you may use the brigade API
60       on the tied object if you want to manipulate the IO stream (beyond
61       simply reading from it).
62
63       The returned reference is actually an object which has "read" and
64       "readline" methods available.  However these methods are just syntactic
65       sugar for the underlying "READ" and "READLINE" methods from
66       APR::Request::Brigade.
67
68           $io = $upload->io;
69           print while $io->read($_); # equivalent to: tied(*$io)->READ($_)
70
71       See READ and READLINE below for additional notes on their usage.
72
73   bb
74           $upload->bb()
75           $upload->bb($set)
76
77       Get/set the APR::Brigade which represents the upload's contents.
78
79   size
80           $upload->size()
81
82       Returns the size of the upload in bytes.
83
84   info
85           $upload->info()
86           $upload->info($set)
87
88       Get/set the additional header information table for the uploaded file.
89       Returns a hash reference tied to the APR::Table class.  An optional
90       $table argument can be passed to reassign the upload's internal
91       (apr_table_t) info table to the one $table represents.
92
93           my $info = $upload->info;
94           while (my($hdr_name, $hdr_value) = each %$info) {
95               # ...
96           }
97
98           # fetch upload's Content-Type header
99           my $type = $upload->info->{"Content-type"};
100
101   type
102           $upload->type()
103
104       Returns the MIME type of the given Apache2::Upload object.
105
106           my $type = $upload->type;
107
108           #same as
109           my $content_type = $upload->info->{"Content-Type"};
110           $content_type =~ s/;.*$//ms;
111
112   link
113           $upload->link()
114
115       To avoid recopying the upload's internal tempfile brigade on a
116       *nix-like system, link will create a hard link to it:
117
118         my $upload = $req->upload('foo');
119         $upload->link("/path/to/newfile") or
120             die sprintf "link from '%s' failed: $!", $upload->tempname;
121
122       Typically the new name must lie on the same device and partition as the
123       brigade's tempfile.  If this or any other reason prevents the OS from
124       linking the files, link() will instead copy the temporary file to the
125       specified location.
126
127   slurp
128           $upload->slurp($contents)
129
130       Reads the full contents of a file upload into the scalar argument.  The
131       return value is the length of the file.
132
133           my $size = $upload->slurp($contents);
134
135   tempname
136           $upload->tempname()
137
138       Provides the name of the spool file.
139
140           my $tempname = $upload->tempname;
141

APR::Request::Brigade

143       This class is derived from APR::Brigade, providing additional methods
144       for TIEHANDLE, READ and READLINE.  To be memory efficient, these
145       methods delete buckets from the brigade as soon as their data is
146       actually read, so you cannot "seek" on handles tied to this class.
147       Such handles have semantics similar to that of a read-only socket.
148
149   TIEHANDLE
150           APR::Request::Brigade->TIEHANDLE($bb)
151
152       Creates a copy of the bucket brigade represented by $bb, and blesses
153       that copy into the APR::Request::Brigade class.  This provides
154       syntactic sugar for using perl's builtin "read", "readline", and "<>"
155       operations on handles tied to this package:
156
157           use Symbol;
158           $fh = gensym;
159           tie *$fh, "APR::Request:Brigade", $bb;
160           print while <$fh>;
161
162   READ
163           $bb->READ($contents)
164           $bb->READ($contents, $length)
165           $bb->READ($contents, $length, $offset)
166
167       Reads data from the brigade $bb into $contents.  When omitted $length
168       defaults to -1, which reads the first bucket into $contents.  A
169       positive $length will read in $length bytes, or the remainder of the
170       brigade, whichever is greater. $offset represents the index in $context
171       to read the new data.
172
173   READLINE
174           $bb->READLINE()
175
176       Returns the first line of data from the bride. Lines are terminated by
177       linefeeds (the '\012' character), but we may eventually use $/ instead.
178

PORTING from 1.X

180       •   "$upload->next()" is no longer available;  please use the
181           "APR::Request::Param::Table" API when iterating over upload
182           entries.
183
184       •   info($header_name) is replaced by info($set).
185
186       •   type() returns only the MIME-type portion of the Content-Type
187           header.
188

COPYRIGHT

194         Licensed to the Apache Software Foundation (ASF) under one or more
195         contributor license agreements.  See the NOTICE file distributed with
196         this work for additional information regarding copyright ownership.
197         The ASF licenses this file to You under the Apache License, Version 2.0
198         (the "License"); you may not use this file except in compliance with
199         the License.  You may obtain a copy of the License at
200
201             http://www.apache.org/licenses/LICENSE-2.0
202
203         Unless required by applicable law or agreed to in writing, software
204         distributed under the License is distributed on an "AS IS" BASIS,
205         WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
206         See the License for the specific language governing permissions and
207         limitations under the License.
208
209
210
211perl v5.38.0                      2023-07-20                Apache2::Upload(3)