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)