CFFILE ACTION = "UPLOAD" |
Description
Copies a file to a directory on the server.
Syntax
    <cffile
       action = "upload"
       fileField = "formfield"
       destination = "full_path_name"
       nameConflict = "behavior"
       accept = "mime_type/file_type"
       mode = "permission"
       attributes = "file_attribute_or_list">
See also
cfdirectory
History
See the History section of the main cffile tag page.
Usage
After a file upload is completed, you can get status information using file upload parameters. The status parameters use the cffile prefix; for example, cffile.clientDirectory. Status parameters can be used anywhere other ColdFusion parameters can be used.
Note: | The file prefix is deprecated, in favor of the cffile prefix. Do not use the file prefix in new applications.
Tip: | If your page is uploading a file that was selected on a form or was otherwise sent to your page via a multipart/form-data HTTP message, you can determine the approximate size of the file by checking the value of the CGI.content_length variable. This variable includes the file length plus the length of any other request content.
The following file upload status parameters are available after an upload.
Parameter | Description
--- | ---
attemptedServerFile | Initial name ColdFusion used when attempting to save a file
clientDirectory | Directory location of the file uploaded from the client's system
clientFile | Name of the file uploaded from the client's system
clientFileExt | Extension of the uploaded file on the client system (without a period)
clientFileName | Name of the uploaded file on the client system (without an extension)
contentSubType | MIME content subtype of the saved file
contentType | MIME content type of the saved file
dateLastAccessed | Date and time the uploaded file was last accessed
fileExisted | Whether the file already existed with the same path (Yes or No)
fileSize | Size of the uploaded file
fileWasAppended | Whether ColdFusion appended uploaded file to a file (Yes or No)
fileWasOverwritten | Whether ColdFusion overwrote a file (Yes or No)
fileWasRenamed | Whether uploaded file renamed to avoid a name conflict (Yes or No)
fileWasSaved | Whether ColdFusion saves a file (Yes or No)
oldFileSize | Size of a file that was overwritten in the file upload operation
serverDirectory | Directory of the file saved on the server
serverFile | Filename of the file saved on the server
serverFileExt | Extension of the uploaded file on the server (without a period)
serverFileName | Name of the uploaded file on the server (without an extension)
timeCreated | Time the uploaded file was created
timeLastModified | Date and time of the last modification to the uploaded file
Tip: | To refer to parameters, use the cffile prefix: for example, #cffile.fileExisted#.
Note: | File status parameters are read-only. They are set to the results of the most recent cffile operation. (If two cffile tags execute, the results of the second overwrite the first.)
Example The following example creates a unique filename, if there is a name conflict when the file is uploaded on Windows:
    <cffile action = "upload"
       fileField = "FileContents"
       destination = "c:\web\uploads\"
       accept = "text/html"
       nameConflict = "MakeUnique">
The following examples show the use of the mode attribute. The first example creates the file /tmp/foo with permissions defined as: owner=read/write, group=read, other=read.
    <cffile action = "write"
    file = "/tmp/foo"
    mode = 644
    output = "some text">
This example appends to a file and sets permissions to read/write (rw) for all.
    <cffile action = "append"
    destination = "/home/tomj/testing.txt"
    mode = 666
    output = "Is this a test?">
This example uploads a file and sets permissions to owner/group/other = read/write/execute.
    <cffile action = "upload"
    fileField = "fieldname"
    destination = "/tmp/program.exe"
    mode = 777>

ACTION |
| Required
Type of file manipulation that the tag performs.

FILEFIELD |
| Required
Name of form field used to select the file. Do not use pound signs (#) to specify the field name.

DESTINATION |
| Required
Pathname of directory in which to upload the file. If not an absolute path (starting a with a drive letter and a colon, or a forward or backward slash), it is relative to the ColdFusion temporary directory, which is returned by the GetTempDirectory function.

NAMECONFLICT |
| Optional
Default value: "Error" Action to take if filename is the same as that of a file in the directory. Error: file is not saved. ColdFusion stops processing the page and returns an error. Skip: file is not saved. This option permits custom behavior based on file properties. Overwrite: replaces file. MakeUnique: forms a unique filename for the upload; name is stored in the file object variable serverFile.

ACCEPT |
| Optional
Limits the MIME types to accept. Comma-delimited list. For example, to permit JPG and Microsoft Word file uploads: accept = "image/jpg, application/msword" The browser uses file extension to determine file type.

MODE |
| Optional
Applies only to UNIX and Linux. Permissions. Octal values of chmod command. Assigned to owner, group, and other, respectively. For example: 644: Assigns read/write permission to owner; read permission to group and other 777: Assigns read/write/execute permission to all

ATTRIBUTES |
| Optional
Applies to Windows. A comma-delimited list of attributes to set on the file. If omitted, the file's attributes are maintained. Each value must be specified explicitly. For example, if you specify attributes = "readOnly", all other attributes are overwritten. readOnly hidden normal (if you use this option with other attributes, it is overridden by them)