# CFFILE ACTION="Upload"

Use CFFILE with the Upload action to upload a file specified in a form field to a directory on the Web server.

Note | The MODE attribute applies to ColdFusion on Solaris and HP-UX, only.

### Syntax

    <CFFILE ACTION="Upload"
        FILEFIELD="formfield"
        DESTINATION="full_path_name"
        NAMECONFLICT="behavior"
        ACCEPT="mime_type/file_type"
        MODE="permission"
        ATTRIBUTES="file_attributes">

#### FILEFIELD

Required. The name of the form field that was used to select the file.

Note: Do not use pound signs (#) to specify the field name.

#### DESTINATION

Required. The full path name of the destination directory on the Web server where the file should be saved. A trailing slash must be included in the target directory when uploading a file. Use the backward slash (\) on Windows ; use the forward slash (/) on UNIX.

Note: The directory does not need to be beneath the root of the Web server document directory.

#### NAMECONFLICT

Optional. Default is error. Determines how the file should be handled if its name conflicts with the name of a file that already exists in the directory. Valid entries are:

- Error -- Default. The file will not be saved, and ColdFusion will stop processing the page and return an error.
- Skip -- Neither saves the file nor throws an error. This setting is intended to allow custom behavior based on inspection of FILE properties.
- Overwrite -- Replaces an existing file if it shares the same name as the CFFILE destination.
- MakeUnique -- Automatically generates a unique filename for the upload. This name will be stored in the FILE object variable "ServerFile. " You can use this variable to record what name was used when the file was saved.

#### ACCEPT

Optional. Use to limit what types of files will be accepted. Enter one or more MIME types, each separated by comma, of the file types you want to accept. For example, to allow uploads of GIF and Microsoft Word files, enter:

    ACCEPT="image/gif, application/msword"

Note that the browser uses the file extension to determine file type.

#### MODE

Optional. Defines permissions for an uploaded file on Solaris or HP-UX. Ignored in Windows. Valid entries correspond to the octal values (not symbolic) of the UNIX chmod command. Permissions are assigned for owner, group, and other, respectively. For example:

    MODE=644

Assigns the owner read/write permissions and group/other read permission.

    MODE=666

Assigns read/write permissions for owner, group, and other.

    MODE=777

Assigns read, write, and execute permissions for all.

#### ATTRIBUTES

Optional. A comma-delimited list of file attributes to be set on the file being uploaded. The following file attributes are supported:

- ReadOnly
- Temporary
- Archive
- Hidden
- System
- Normal

If ATTRIBUTES is not used, the file's attributes are maintained. If Normal is specified as well as any other attributes, Normal is overridden by whatever other attribute is specified.

Individual attributes must be specified explicitly. For example, if you specify just the ReadOnly attribute, all other existing attributes are overwritten.

### Examples

The following example will create 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">

Note | On Windows, you must include the backward slash (\) after the destination directory name. On UNIX, you must include the forward slash (/) after the destination directory. In this example, the specified destination directory is "uploads. "

## Evaluating the results of a file upload

After a file upload is completed, you can retrieve status information using file upload parameters. This status information includes a wide range of data about the file, such as the file's name and the directory where it was saved. File upload status parameters use the "File " prefix, for example, File.ClientDirectory. The file status parameters can be used anywhere other ColdFusion parameters can be used.

The following file upload status parameters are available after an upload.

File Upload Parameters
Parameter | Description
--- | ---
AttemptedServerFile | Initial name ColdFusion used attempting to save a file, for example, myfile.txt.
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's system without a period, for example, txt not .txt.
ClientFileName | Filename without an extension of the uploaded file on the client's system.
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 | Indicates (Yes or No) whether or not the file already existed with the same path.
FileSize | Size of the uploaded file.
FileWasAppended | Indicates (Yes or No) whether or not ColdFusion appended the uploaded file to an existing file.
FileWasOverwritten | Indicates (Yes or No) whether or not ColdFusion overwrote a file.
FileWasRenamed | Indicates (Yes or No) whether or not the uploaded file was renamed to avoid a name conflict.
FileWasSaved | Indicates (Yes or No) whether or not Cold Fusion saved a file.
OldFileSize | Size of a file that was overwritten in the file upload operation.
ServerDirectory | Directory of the file actually saved on the server.
ServerFile | Filename of the file actually saved on the server.
ServerFileExt | Extension of the uploaded file on the server, without a period, for example, txt not .txt.
ServerFileName | Filename, without an extension, of the uploaded file on the server.
TimeCreated | Time the uploaded file was created.
TimeLastModified | Date and time of the last modification to the uploaded file.

Tip | Use the File prefix to refer to these parameters, for example, #File.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 first are overwritten by the subsequent CFFILE operation.)

### UNIX Examples

The following three examples show the use of the MODE attribute for UNIX. The first example creates the file `/tmp/foo` with permissions defined as `rw-r-r`-- (owner=read/write, group/other=read).

    <CFFILE ACTION="Write"
        FILE="/tmp/foo"
        MODE=644>

This example appends to the specified file and makes permissions read/write (rw) for all.

    <CFFILE ACTION="Append"
        DESTINATION="/home/tomj/testing.txt"
        MODE=666
        OUTPUT="Is this a test?">

The next example uploads a file and gives it `rwx-rw-rw` permissions (owner/group/other=read/write).

    CFFILE ACTION="Upload"
        FILEFIELD="fieldname"
        DESTINATION="/tmp/program.exe"
        MODE=755>