DirectoryList

Description

Lists the contents of on-disk or in-memory directory. Also lists the contents of the sub-directories if recurse is set to true.

Returns

Contents of the directory based on the parameter listInfo:
  • If listInfo="query", query object

  • If listInfo="name", array of names

  • If listInfo="path", array of path

Function Syntax

DirectoryList(path [,recurse] [,listInfo] [,filter] [,sort])

Parameters

Parameter

Description

path

The absolute path of the directory for which to list the contents. Alternatively, you can specify IP address as in the following example: DirectoryList("//12.3.123.123/c_drive/test");.

recurse

Whether ColdFusion performs the action on subdirectories:

If true, contents of all subdirectories are also listed.

listInfo

  • name: returns an array of names of files and directories.

  • path: returns an array of paths of files and directories.

  • query: returns a query.

filter

File extension filter applied to returned names, for example, *.cfm. One filter can be applied.

sort

Query columns by which to sort a directory listing. Delimited list of columns from query output.

To qualify a column, use one of the following values:

  • asc: ascending (a to z) sort order.

  • dec: descending (z to a) sort order.

For example:

sort = "directory ASC, size DESC, datelastmodified"

Usage

Ensure that you have the required permissions to run this function.

Example

The following code dumps the contents of a directory:

<h2>DirectoryList Example</h2> 
<h3>Enter a directory for Listing.</h3> 
 <cfform action = "directoryList.cfm" method="post" preservedata="true" > 
     <label for="listDirectory">Directory Path: </label><cfinput type = "text" id="listDirectory" name = "listDirectory"> 
     <br /> 
    <label for="recurse">Recurse: </label><cfinput id="recurse" type="checkbox" value="recurse" name="recurse"> 
    <br /> 
    <label for="listInfo">List Info: </label> 
    <cfselect name="listInfo" id="listInfo"> 
      <option value="name">name</option> 
      <option value="path">path</option> 
      <option value="query">query</option> 
    </cfselect> 
    <br /> 
    <label for="filter">Filter: </label><cfinput id="filter" type="text" value="" name="filter"> 
    <br/> 
     <input type = "submit" value="submit" name = "submit"> 
 </cfform> 
 
 <cfif IsDefined("FORM.listDirectory")> 
     <cfif FORM.listDirectory is not ""> 
     <cfset listDirectory = FORM.listDirectory> 
    <cfset recurse = false> 
    <cfif isDefined("FORM.recurse")> 
        <cfset recurse = true> 
    </cfif> 
    <cfset listInfo = FORM.listInfo> 
    <cfset filter = FORM.filter> 
         <cftry> 
            <cfset res=  DirectoryList(listDirectory,recurse,listInfo,filter)> 
            <cfoutput><b>Content of Directory #listDirectory#: </b></cfoutput> 
            <cfdump var="#res#"> 
         <cfcatch> 
             <b>Error Message:</b><cfoutput>#cfcatch.message#</cfoutput><br/> 
            <b>Error Detail:</b><cfoutput>#cfcatch.Detail#</cfoutput> 
         </cfcatch> 
        </cftry> 
     </cfif> 
 </cfif>