CFML Reference
ColdFusion Tags

cffile action = "upload"

Description

Uploads upload a file specified in a form field to a directory on the Web server.

Category

File management tags

Syntax

<cffile action = "upload"

  fileField = "formfield"

  destination = "full_path_name"

  nameConflict = "behavior"

  accept = "mime_type/file_type"

  mode = "permission"

  attributes = "file_attributes"> 

See also

cfdirectory

Attributes

Attribute	Description
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 pathname of the destination directory or full pathname of the file on the Web server where the file is saved. A trailing slash must be included in the target directory. Use the backward slash (\) on Windows; use the forward slash (/) on UNIX. Note: The directory does not have to be below the root of the Web server document directory.
nameConflict	Optional. Default is Error. Determines how to handle the file if its name conflicts with the name of a file that already exists in the directory. Options are: Error    Default. The file is not saved, ColdFusion stops processing the page and returns an error. Skip    Neither saves the file nor throws an error. This setting allows custom behavior based on file properties. Overwrite    Replaces an existing file, if it has the same name as the cffile destination. MakeUnique    Generate a unique filename for the upload. The name is stored in the file object variable serverFile. You can use this variable to record the name used when the file was saved.
accept	Optional. Limit the file types accepted. Enter one or more comma-delimited MIME types that you want to accept. For example, to allow uploads of GIF and Microsoft Word files, enter: accept = "image/gif, application/msword" The browser uses the file extension to determine file type.
mode	Optional. Defines permissions for an uploaded file on UNIX and Linux platforms. Ignored in Windows. Option values 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 read/write permissions for the owner, and read permissions for the group and other. 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. Options are: readOnly temporary archive hidden system normal If attributes is not used, the file's attributes are maintained. If normal is specified with other attributes, normal is overridden by whatever other attribute is specified. Individual attributes must be specified explicitly. For example, if you specify only the readOnly attribute, all other existing attributes are overwritten.

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">

Usage

After a file upload is completed, you can retrieve status information using file upload parameters. The status information includes data about the file, such as the file's name and the directory where it was saved. File upload status parameters use the cffile prefix; for example, cffile.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.

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'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 ColdFusion appends the uploaded file to an existing file
fileWasOverwritten	Indicates (Yes or No) whether ColdFusion overwrites a file
fileWasRenamed	Indicates (Yes or No) whether the uploaded file is renamed to avoid a name conflict
fileWasSaved	Indicates (Yes or No) whether Cold Fusion saves a file
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	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

Example UNIX

The following three examples show the use of the mode attribute on UNIX. 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>

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?">

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>

Copyright © 2001, Macromedia Inc. All rights reserved.

---