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

Category

System functions

Function Syntax

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

See Also

DirectoryCreate, DirectoryDelete, DirectoryExists, DirectoryRename

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>