directoryList

List the contents of a directory. Returns either an array, or a query. NOTE: Ensure that you have the required permissions to run this function.

directoryList(path [, recurse] [, listInfo] [, filter] [, sort] [, type]) → returns any

  1. CFDocs
  2. Functions
  3. ColdFusion 9 New Functions and Tags
  4. directoryList
  5. CF9+
  6. Lucee
  7. BL 1.0.0+
  8. 0 Issue
  9. Edit
See Also:   cfdirectory

Argument Reference

path string
Required

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 boolean
Default: false

If true directoryList traverses the directory tree.
Values:
  • true
  • false

listInfo string
Default: path

Sets the return type. name returns an array with only the file names, path returns an array with the full path names and query returns a query containing the following fields: Attributes, DateLastModified, Directory, Link, Mode, Name, Size, Type.
Values:
  • name
  • path
  • query

filter string

File extension filter applied to the listed files, for example, *.jpg. Multiple filters can be applied by using a pipe delimiter. For example: *.doc|*.xls. You can also pass a function. The arguments of the passed function must have: path :the file path, type: The values (file or dir), extension: The file extension, if any, otherwise and empty string. This argument can also accept the instances of Java FileFilter Objects. In Lucee 4.5+ it can be a closure as well.

sort string

Columns by which to sort. e.g. Directory, Size DESC, DateLastModified. To qualify a column, use asc (ascending sort a-z) or desc (descending sort z-a).

type string
Default: all

CF 11+ Lucee 5+ Filter the result to only include files, directories, or both.
Values:
  • file
  • dir
  • all

Compatibility

ColdFusion:

Version 9+ Only CF11+ supports the type argument.

Lucee:

In Lucee the filter param can be a closure as well where the path is passed in. The sort argument only works when listInfo="query".

Railo:

If a directory returns false in recursive mode the contained files are processed anyways

Links more information about directoryList

Examples
Sample code invoking the directoryList function 

arrayOfLocalFiles = directoryList( expandPath( "./" ), false, "name" );

queryOfFiles = directoryList( expandPath( "./" ), false, "query", "", "DateLastModified DESC" );

Including sub-directories and as an array containing full paths

arrayOfTempFiles = directoryList( "./", true );

Lucee 4.5+ Pass a closure instead of a string as filter param

arrayOfFilteredFiles = directoryList(".", false, "name", function(path) {
	return ListFindNoCase("Application.cfc,robots.txt,server.json,favicon.ico,.htaccess,README.md", path);
});

Signup for cfbreak to stay updated on the latest news from the ColdFusion / CFML community. One email, every friday.

Fork me on GitHub