UAPI Functions - Fileman::list_files

In cPanel & WHM version 76 and later, when you disable the FileStorage role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Examples

cPanel or Webmail Session URL

https://hostname.example.com:2083/cpsess##########/execute/Fileman/list_files?dir=public_html&types=dir%7Cfile&limit_to_list=0&show%20hidden=1&check_for_leaf_directories=1&include_mime=1&include_hash=1&include_permissions=0

Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation.

LiveAPI PHP Class

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List files and directories for example.com.
$list_files = $cpanel->uapi(
    'Fileman', 'list_files',
		array(
		'dir'								=> 'public_html',
		'types'								=> 'dir|file',
		'limit_to_list'						=> '0',
		'show_hidden'						=> '1',
		'check_for_leaf_directories'		=> '1',
		'include_mime'						=> '1',
		'include_hash'						=> '0',
		'include_permissions'				=> '0',
   )
);

Note:

For more information, read our Guide to the LiveAPI System.

LiveAPI Perl Module

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# List files and directories for example.com
my $ list_files = $cpliveapi->uapi(
 'Fileman', 'list_files',
		{
		'dir'								=> 'public_html',
		'types'								=> 'dir|file',
		'limit_to_list'						=> '0',
		'show_hidden'						=> '1',
		'check_for_leaf_directories'		=> '1',
		'include_mime'						=> '1',
		'include_hash'						=> '0',
		'include_permissions'				=> '0',
		}
 );

Note:

For more information, read our Guide to the LiveAPI System.

cPanel Template Toolkit

<!-- Get a hash of all the data, then display the file value. -->
[% data = execute( 'Fileman', 'list_files' {'dir' => public_html', 'types' => 'dir|file', limit_to_list'    => '0', 'show_hidden' => '1', 'check_for_leaf_directories' => '1', 'include_mime' => '1', 'include_hash' => '0', 'include_permissions' => '0',} ); %]
[% FOREACH q = data.file %]
     <p>
         [% q %]
     </p>
[% END %]
 
<!-- Get only a hash of the data. -->
[% execute('Fileman', 'list_files' {'dir' => 'public_html', 'types' => 'dir|file', limit_to_list'    => '0', 'show_hidden' => '1', 'check_for_leaf_directories' => '1', 'include_mime' => '1', 'include_hash' => '0', 'include_permissions' => '0',}  ).data.file %]

Note:

For more information, read our Guide to Template Toolkit documentation.

Command Line

uapi --user=username Fileman list_files dir=public_html types=dir%7Cfile limit_to_list=0 show_hidden=1 check_for_leaf_directories=1 include_mime=1 include_hash=1 include_permissions=0

Notes:

You must URI-encode values.
username represents your account-level username.
For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command.
If you run CloudLinux™, you must use the full path of the uapi command:
```
/usr/local/cpanel/bin/uapi
```

Output (JSON)

{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": {
    "files": [
      {
        "ctime": 1371711650,
        "uid": 508,
        "mode": 33184,
        "mtime": 1371711650,
        "file": "cpbackup-exclude.conf",
        "path": "/home/example",
        "nicemode": "0640",
        "humansize": "1 byte",
        "size": "1",
        "fullpath": "/home/example/cpbackup-exclude.conf",
        "absdir": "/home/example",
        "type": "file",
        "exists": 1,
        "gid": 508
      }
    ],
    "dirs": [
      {
        "ctime": 1377179101,
        "uid": "",
        "mode": 16872,
        "mtime": 1371591601,
        "file": "access-logs",
        "path": "/home/example",
        "nicemode": "0750",
        "humansize": "4 KB",
        "size": "4096",
        "fullpath": "/home/example/access-logs",
        "absdir": "/home/example",
        "type": "dir",
        "exists": 1,
        "gid": 508
      },
      {
        "ctime": 1371752441,
        "uid": 508,
        "mode": 16877,
        "mtime": 1371752441,
        "file": "cpanel3-skel",
        "path": "/home/example",
        "nicemode": "0755",
        "humansize": "4 KB",
        "size": "4096",
        "fullpath": "/home/example/cpanel3-skel",
        "absdir": "/home/example",
        "type": "dir",
        "exists": 1,
        "gid": 508
      },
      {
        "ctime": 1372270682,
        "uid": 508,
        "mode": 16872,
        "mtime": 1372270682,
        "file": "etc",
        "path": "/home/example",
        "nicemode": "0750",
        "humansize": "4 KB",
        "size": "4096",
        "fullpath": "/home/example/etc",
        "absdir": "/home/example",
        "type": "dir",
        "exists": 1,
        "gid": 12
      },
      {
        "ctime": 1372192801,
        "uid": 508,
        "mode": 16873,
        "mtime": 1372192801,
        "file": "mail",
        "path": "/home/example",
        "nicemode": "0751",
        "humansize": "4 KB",
        "size": "4096",
        "fullpath": "/home/example/mail",
        "absdir": "/home/example",
        "type": "dir",
        "exists": 1,
        "gid": 508
      },
      {
        "ctime": 1371590824,
        "uid": 508,
        "mode": 16872,
        "mtime": 1371590824,
        "file": "public_ftp",
        "path": "/home/example",
        "nicemode": "0750",
        "humansize": "4 KB",
        "size": "4096",
        "fullpath": "/home/example/public_ftp",
        "absdir": "/home/example",
        "type": "dir",
        "exists": 1,
        "gid": 508
      },
      {
        "ctime": 1377196555,
        "uid": 508,
        "mode": 16872,
        "mtime": 1377196555,
        "file": "public_html",
        "path": "/home/example",
        "nicemode": "0750",
        "humansize": "4 KB",
        "size": "4096",
        "fullpath": "/home/example/public_html",
        "absdir": "/home/example",
        "type": "dir",
        "exists": 1,
        "gid": 99
      },
      {
        "ctime": 1371711650,
        "uid": 508,
        "mode": 16877,
        "mtime": 1371711650,
        "file": "ssl",
        "path": "/home/example",
        "nicemode": "0755",
        "humansize": "4 KB",
        "size": "4096",
        "fullpath": "/home/example/ssl",
        "absdir": "/home/example",
        "type": "dir",
        "exists": 1,
        "gid": 508
      },
      {
        "ctime": 1377111650,
        "uid": 508,
        "mode": 16877,
        "mtime": 1377111650,
        "file": "tmp",
        "path": "/home/example",
        "nicemode": "0755",
        "humansize": "4 KB",
        "size": "4096",
        "fullpath": "/home/example/tmp",
        "absdir": "/home/example",
        "type": "dir",
        "exists": 1,
        "gid": 508
      },
      {
        "ctime": 1377196555,
        "uid": 508,
        "mode": 16872,
        "mtime": 1377196555,
        "file": "www",
        "path": "/home/example",
        "nicemode": "0750",
        "humansize": "4 KB",
        "size": "4096",
        "fullpath": "/home/example/www",
        "absdir": "/home/example",
        "type": "dir",
        "exists": 1,
        "gid": 99
      }
    ]
  }
}

Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

Parameters	Type	Description	Possible values	Example
`dirs`	string	Required The directory from which to list files.	A valid directory on the server.	`public_html`
`types`	string	A pipe-separated list of file types to return. If you do not use this parameter, the function returns all file types.	`file` — A file. `dir` — A directory. `char` — A character set. `block` — A block of text. `fifo` — A First In, First Out (FIFO) data buffer. `link` — A link `socket` — A network socket.	`file\|dir`
`limit_to_list`	Boolean	Whether to return only entries that begin with `filepath-` If you do not use this parameter, the function returns all filenames.	`1` — Return only files that begin with `filepath-` `0` — Return all files.	`0`
`only_these_files`	string	The files to return. If you do not use this parameter, the function returns all files.	A list of comma-separated files.	`cpbackup-exclude.conf`
`show_hidden`	Boolean	Whether to include hidden files in the output. This parameter defaults to `0`.	`1` — Include hidden files. `0` — Do not include hidden files.	`1`
`check_for_leaf_directories`	Boolean	Whether to return directories that contain subdirectories. This parameter defaults to `0` .	`1` — Return subdirectories. `0` — Do not retain subdirectories.	`1`
`mime_types`	string	The MIME types to return. If you use this parameter, the function returns the specified MIME types and sets the `include_mime` parameter's value to `1` . If you do not use this parameter, the function returns all MIME types.	A comma-separated list of MIME types.	`text-plain`
`raw_mime_types`	string	The raw MIME types to return. If you use this parameter, the function returns the specified MIME types and sets the `include_mime` parameter's value to `1`. If you do not use this parameter, the function returns all MIME types.	A comma-separated list of raw MIME types.	`text/plain`
`include_mime`	Boolean	Whether to return the file's MIME type. This parameter defaults to `0`. Note: If you set this value to `0` but also include the `mime_types` or `raw_mime_types` parameters, the function overrides your specified value and sets this parameter to `1`.	`1` — Include MIME type. `0` — Do not include MIME type.	`1`
`include_hash`	Boolean	Whether to include a hash of the file's information in the return. This parameter defaults to `0`.	`1` — Generate a hash. `0` — Do not generate a hash.	`0`
`include_permissions`	Boolean	Whether to parse the file owner's read and write permissions. This parameter defaults to `0`.	`1` — Parse file permissions. `0` — Do not parse file permissions.	`0`

Returns

Return	Type	Description	Possible values	Example
`files`	array of hashes	An array of hashes that contains information about each file.	This array of hashes includes the `absdir` , `ctime` , `exists` , `file` , `fullpath` , `gid` , `hash` , `humansize` , `isleaf` , `mimename` , `mimetype` , `mode` , `mtime` , `nicemode` , `path` , `phash` , `rawmimename` , `rawmimetype` , `size` , `type` , `uid` , `read` , `write` , and `isparent` returns.
`absdir`	string	The path to the user's home directory. The function returns this value in the `files` array of hashes.	A valid file path.	`/home/user`
`ctime`	string	The file's creation time. The function returns this value in the `files` array of hashes.	A time in Unix time format.	`1400573272`
`exists`	Boolean	Whether the file exists in the directory. The function returns this value in the `files` array of hashes.	`1` — Exists. `0` — Does not exist.	`1`
`file`	string	The filename. The function returns this value in the `files` array of hashes.	A valid filename on the server.	`cgi-bin`
`fullpath`	string	The file's full file path. The function returns this value in the `files` array of hashes.	A valid filepath on the server.	`/home/user/public_html/cgi-bin`
`gid`	integer	The file owner's system group ID. The function returns this value in the `files` array of hashes.	A positive integer.	`503`
`hash`	string	The full file path's hash. The function returns this value in the `files` array of hashes.	A string of letters and integers.	`L2hvbWUvY29saW4vcHVibGljX2h0bWw`
`humansize`	string	The formatted size of the file. The function returns this value in the `files` array of hashes.	A positive integer and one of the following symbols: `KB` — Kilobytes `MB` — Megabytes `GB` — Gigabytes.	`5 KB`
`isleaf`	Boolean	Whether the directory contains subdirectories. The function returns this value in the `files` array of hashes.	`1` — Contains subdirectories. `0` — Does not contain subdirectories.	`1`
`mimename`	string	The file's MIME type name. The function returns this value in the `files` array of hashes.	A valid MIME name on the server.	`text-plain`
`mimetype`	string	The file's MIME type. The function returns this value in the `files` array of hashes.	A valid MIME type on the server.	`text/plain`
`mode`	string	The file's textual permissions. The function returns this value in the `files` array of hashes.	A string value in Unix format .	`16877`
`mtime`	string	The file's last modification time. The function returns this value in the `files` array of hashes.	A time in Unix time format.	`1400573272`
`nicemode`	integer	The file's numerical permissions. The function returns this value in the `files` array of hashes.	An integer value in octal notation .	`0755`
`path`	string	The absolute path to the file. The function returns this value in the `files` array of hashes.	A valid file path.	`/home/user/public.html`
`phash`	string	The parent filepath's file hash. The function returns this value in the `files` array of hashes.	A string of letters and integers.	`L2hvbWUvY29saW4vcHVibGljX2h0bWw`
`rawmimename`	string	The file's raw MIME type's name. The function returns this value in the `files` array of hashes.	A valid raw MIME type's name on the server.	`text-plain`
`rawmimetype`	string	The file's raw MIME type. The function returns this value in the `files` array of hashes.	A valid raw MIME type on the server.	`text/plain`
`size`	integer	The file's size, in bytes. The function returns this value in the `files` array of hashes.	A positive integer.	`4096`
`type`	string	The item's type. The function returns this value in the `files` array of hashes.	`file` — A file. `dir` — A directory. `char` — A character set. `block` — A block of text. `fifo` — A First In, First Out (FIFO) data buffer. `link` — A link. `socket` — A network socket.	`file`
`uid`	integer	The file owner's system user ID. The function returns this value in the `files` array of hashes.	A positive integer.	`502`
`read`	Boolean	Whether the file is readable. Note: The function only returns this value if the `include_permissions` value is `1`. The function returns this value in the `files` array of hashes.	`1` — Readable. `0` — Not readable.	`1`
`write`	Boolean	Whether the file is writable. Note: The function only returns this value if the `include_permissions` value is `1`. The function returns this value in the `files` array of hashes.	`1` — Writable. `0` — Not writable.	`1`
`isparent`	Boolean	Whether the file is a parent record. The function returns this value in the `files` array of hashes.	`1` — A parent record. `0` — Not a parent record.	`1`
`dirs`	array of hashes	An array of hashes that contains information about each directory.	This array of hashes includes the `absdir`, `ctime`, `exists`, `file`, `fullpath`, `gid`, `hash`, `humansize`, `isleaf`, `mimename`, `mimetype`, `mode`, `mtime`, `nicemode`, `path`, `phash`, `rawmimename`, `rawmimetype`, `size`, `type`, `uid`, `read`, `write`, and `isparent` returns.
`absdir`	string	The path to the user's home directory. The function returns this value in the `dirs` array of hashes.	A valid file path.	`/home/user`
`ctime`	string	The directory's creation time. The function returns this value in the `dirs` array of hashes.	A time in Unix time format.	`1400573272`
`exists`	Boolean	Whether the directory exists in the directory. The function returns this value in the `dirs` array of hashes.	`1` — Exists. `0` — Does not exist.	`1`
`file`	string	The directory name. The function returns this value in the `dirs` array of hashes.	A valid directory name on the server.	`cgi-bin`
`fullpath`	string	The directory's full directory path. The function returns this value in the `dirs` array of hashes.	A valid directory path on the server.	`/home/user/public_html/cgi-bin`
`gid`	integer	The directory owner's system group ID. The function returns this value in the `dirs` array of hashes.	A positive integer.	`503`
`hash`	string	The full directory path's hash. The function returns this value in the `dirs` array of hashes.	A string of letters and integers.	`L2hvbWUvY29saW4vcHVibGljX2h0bWw`
`humansize`	string	The formatted size of the directory. The function returns this value in the `dirs` array of hashes.	A positive integer and one of the following symbols: `KB` — Kilobytes `MB` — Megabytes `GB` — Gigabytes.	`5 KB`
`isleaf`	Boolean	Whether the directory contains subdirectories. The function returns this value in the `dirs` array of hashes.	`1` — Contains subdirectories. `0` — Does not contain subdirectories.	`1`
`mimename`	string	The MIME type's name. The function returns this value in the `dirs` array of hashes.	A valid MIME name on the server.	`text-plain`
`mimetype`	string	The directory's MIME's type. The function returns this value in the `dirs` array of hashes.	A valid MIME type on the server.	`text/plain`
`mode`	string	The directory's textual permissions. The function returns this value in the `dirs` array of hashes.	A string value in Unix format.	`16877`
`mtime`	string	The directory's last modification time. The function returns this value in the `dirs` array of hashes.	A time in Unix time format.	`1400573272`
`nicemode`	integer	The directory's numerical permissions. The function returns this value in the `dirs` array of hashes.	An integer value in octal notation.	`0755`
`path`	string	The path to the directory. The function returns this value in the `dirs` array of hashes.	A valid file path.	`/home/user/public.html`
`phash`	string	The parent directory path's hash. The function returns this value in the `dirs` array of hashes.	A string of letters and integers.	`L2hvbWUvY29saW4vcHVibGljX2h0bWw`
`rawmimename`	string	The directory's raw MIME type's name. The function returns this value in the `dirs` array of hashes.	A valid raw MIME type name on the server.	`text-plain`
`rawmimetype`	string	The directory's raw MIME type. The function returns this value in the `dirs` array of hashes.	A valid raw MIME type on the server.	`text/plain`
`size`	integer	The directory's size, in bytes. The function returns this value in the `dirs` array of hashes.	A positive integer.	`4096`
`type`	string	The item's type. The function returns this value in the `dirs` array of hashes.	`file` — A file. `dir` — A directory. `char` — A character set. `block` — A block of text. `fifo` — A First In, First Out (FIFO) data buffer. `link` — A link `socket` — A network socket.	`file`
`uid`	integer	The directory owner's system user ID. The function returns this value in the `dirs` array of hashes.	A positive integer.	`502`
`read`	Boolean	Whether the directory is readable. Note: The function only returns this value if the `include_permissions` value is `1`. The function returns this value in the `dirs` array of hashes.	`1` — Readable. `0` — Not readable.	`1`
`write`	Boolean	Whether the directory is writable. Note: The function only returns this value if the `include_permissions` value is `1`. The function returns this value in the `dirs` array of hashes.	`1` — Writable. `0` — Not writable.	`1`
`isparent`	Boolean	Whether the directory is a parent record. The function returns this value in the `dirs` array of hashes.	`1` — A parent record. `0` — Not a parent record.	`1`

Function information

Module:

Fileman

API Version:

UAPI

Available in:

cPanel 11.44+

Methods:

GET, POST

Required Parameters:

dir

Return Formats:

JSON, XML

Legacy Equivalents:

About this module

The Fileman module provides access to file functions.

About UAPI

UAPI accesses and modifies data for cPanel accounts.

Notes:

These functions may require specific features. To enable or disable features, use WHM's Feature Manager interface.
Unless you call this API via the WHM API, you must use the appropriate cPanel ports (2082 or 2083). You can also call some functions via cPanel's Webmail ports (2095 or 2096).

Find a function

Related functions

Page:

UAPI Modules - Fileman — The Fileman module provides access to file functions.
Page:

UAPI Functions - Fileman::autocompletedir — This function returns any files and directories that begin with a specified string.
Page:

UAPI Functions - Fileman::empty_trash — This function purges content from the .trash folder in the user's home directory.
Page:

UAPI Functions - Fileman::get_file_content — This function retrieves a file's content.
Page:

UAPI Functions - Fileman::get_file_information — This function returns the information for a specified file or directory.

Child pages

UAPI Functions - Fileman::list_files

Description

Examples

Parameters

Returns

Function information

About this module

About UAPI

Find a function

Related functions