GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CGI::UPLOAD (3)

.ds Aq ’

NAME

CGI::Upload - CGI class for handling browser file uploads

CONTENTS

SYNOPSIS



 use CGI::Upload;

 my $upload = CGI::Upload->new;

 my $file_name = $upload->file_name(field);
 my $file_type = $upload->file_type(field);

 $upload->mime_magic(/path/to/mime.types);
 my $mime_type = $upload->mime_type(field);

 my $file_handle = $upload->file_handle(field);



DESCRIPTION

This module has been written to provide a simple and secure manner by which to handle files uploaded in multipart/form-data requests through a web browser. The primary advantage which this module offers over existing modules is the single interface which it provides for the most often required information regarding files uploaded in this manner.

This module builds upon primarily the <B>CGIB> and <B>File::MMagicB> modules and offers some tidy and succinct methods for the handling of files uploaded via multipart/form-data requests.

METHODS

The following methods are available through this module for use in CGI scripts and can be exported into the calling namespace upon request.
<B>newB> This object constructor method creates and returns a new <B>CGI::UploadB> object. In previously versions of <B>CGI::UploadB>, a mandatory argument of the <B>CGIB> object to be used was required. This is no longer necessary due to the singleton nature of <B>CGIB> objects.

As an experiment, you can now use any kind of CGI.pm like module. The requirements are that it has to support the ->param method and the ->upload method returning a file handle. You can use this feature in two ways, either providing the name of the module or an already existing object. In the former case, CGI::Upload will try to require the correct module and will croak if cannot load that module. It has been tested with CGI.pm and CGI::Simple.

We tested it with CGI::Simple 0.075.

It is known to break with version 0.071 of CGI::Simple so we issue our own die in such case.

Examples:



 use CGI::Upload;
 CGI::Upload->new({ query => "CGI::Simple"});



or



 use CGI::Upload;
 use CGI::Simple;
 $CGI::Simple::DISABLE_UPLOADS = 0;   # you have to set this before creating the instance
 my $q = new CGI::Simple;
 CGI::Upload->new({ query => $q});



<B>queryB> Returns the <B>CGIB> object used within the <B>CGI::UploadB> class.
<B>file_handle(’field’)B> This method returns the file handle to the temporary file containing the file uploaded through the form input field named ’field’. This temporary file is generated using the <B>new_tmpfileB> method of <B>IO::FileB> and is anonymous in nature, where possible.
<B>file_name(’field’)B> This method returns the file name of the file uploaded through the form input field named ’field’ - This file name does not reflect the local temporary filename of the uploaded file, but that for the file supplied by the client web browser.
<B>file_type(’field’)B> This method returns the file type of the file uploaded as specified by the filename extension - Please note that this does not necessarily reflect the nature of the file uploaded, but allows CGI scripts to perform cursory validation of the file type of the uploaded file.
<B>mime_magic(’/path/to/mime.types’)B> This method sets and/or returns the external magic mime types file to be used for the identification of files via the <B>mime_typeB> method. By default, MIME identification is based upon internal mime types defined within the <B>File::MMagicB> module.

See File::MMagic for further details.

<B>mime_type(’field’)B> This method returns the MIME type of the file uploaded through the form input field named ’field’ as determined by file magic numbers. This is the best means by which to validate the nature of the uploaded file.

See File::MMagic for further details.

BUGS

Please report bugs on RT: <http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI-Upload>

TODO

Explain why there is no 100% tests coverage...

Give inteligent error message when user forgets to add enctype=multipart/form-data in the upload form.

Add better MIME magic support (see request on RT)

Test if multiple file uploads are supported and fix this if they are not.

Apache::Request support

CGI::Minimal support

Example code from Mark Stosberg (CGI::Uploader):



  if ($q->isa(CGI::Simple) ) {
           $fh = $q->upload($filename);
           $mt = $q->upload_info($filename, mime );

           if (!$fh && $q->cgi_error) {
                   warn $q->cgi_error && return undef;
           }
   }
   elsif ( $q->isa(Apache::Request) ) {
            my $upload = $q->upload($file_field);
                $fh = $upload->fh;
                $mt = $upload->type;
   }
   # default to CGI.pm behavior
   else {
           $fh = $q->upload($file_field);
           $mt = $q->uploadInfo($fh)->{Content-Type} if $q->uploadInfo($fh);

           if (!$fh && $q->cgi_error) {
                   warn $q->cgi_error && return undef;
           }
   }



SEE ALSO

CGI, File::MMagic, HTTP::File

COPYRIGHT

Copyright 2002-2004, Rob Casey, rob.casey@bluebottle.com

AUTHOR

Original author: Rob Casey, rob.casey@bluebottle.com

Current mainainer: Gabor Szabo, gabor@pti.co.il

Thanks to

Mark Stosberg for suggestions.

and to the CPAN Testers for testing.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 CGI::UPLOAD (3) 2008-03-07

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.