Page tree
Skip to end of metadata
Go to start of metadata

 

Description

This function lists a directory's files and their attributes.

Warning:

This function is deprecated as of cPanel version 11.40+. We strongly recommend that you use the following UAPI functions instead of this function:

Examples 


 WHM API (JSON)
https://hostname.example.com:2087/cpsess##########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Fileman&cpanel_jsonapi_func=listfiles&checkleaf=1&dir=%2Fhome%2Fuser&filelist=1&filepath=filelist-A&needmime=1&showdotfiles=1&types=dir%20%7C%20file

Note:

 For more information, read our Calls from the WHM API documentation.

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// List files in /home/user/public_html.
$list_files = $cpanel->api2(
    'Fileman', 'listfiles', 
		array(
		'checkleaf' 	=> '1',
		'dir'			=> '/home/user/public_html/',
		'filelist' 	    => '1',
		'filepath-*'	=> 'filepath-myfile',
		'needmime'		=> '1',
		'showdotfiles'	=> '1',
		'types'			=> 'dir|file',
 ) 
);

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.
 
# Search for directories that begin with /home/user/public_html.
my $search_directories = $cpliveapi->api2(
    'Fileman', 'autocompletedir',
	{
		'checkleaf' 	=> '1',
		'dir'			=> '/home/user/public_html/',
		'filelist' 	    => '1',
		'filepath-*'	=> 'filepath-myfile',
		'needmime'		=> '1',
		'showdotfiles'	=> '1',
		'types'			=> 'dir|file',
    }
 );

Note:

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

 cPanel Tag System (deprecated)

Warning:

In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs.

cPanel API 2 calls that use cPanel tags vary widely in code syntax and in their output. For more information, read our Deprecated cPanel Tag Usage documentation. Examples are only present in order to help developers move from the old cPanel tag system to our LiveAPI.

 Command Line
cpapi2 --user=username Fileman autocompletedir checkleaf=1 dir=%2Fhome%2Fuser%2Fpublic_html%2F filelist=1 filepath-*=filepath-myfile needmime=1 showdotfiles=1 types=dir%7Cfile

Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to cPanel API 2 documentation or run the cpapi2 --help command. 
  • We introduced this functionality in cPanel & WHM version 56.

 Output (JSON)
{
  "cpanelresult": {
    "apiversion": 2,
    "func": "listfiles",
    "files": [
      {
        "ctime": 1371711650,
        "uid": 508,
		"mode": 33184,
		"mtime" : 1371711650
		"isleaf" : "1"
		"mimename" : "homeb"
		"file": "cpbackup-exclude.conf",
        "path": "/home/example",
        "nicemode": "0640",
        "humansize": "1 byte",
        "size": "1",
        "fullpath": "/home/example/cpbackup-exclude.conf",
        "type": "file",
		"mimetype" : "text/plain"
		"exists": 1,
        "gid": 508
      }
    ],
    "dirs": [
      {
        "ctime": 1377179101,
        "uid": "",
        "mode": 16872,
		"isleaf" : "1"
		"mimename" : "homeb"
        "mtime": 1371591601,
        "file": "access-logs",
        "path": "/home/example",
        "nicemode": "0750",
        "humansize": "4 KB",
        "size": "4096",
        "fullpath": "/home/example/access-logs",
        "type": "dir",
		"mimetype" : "text/plain"
        "exists": 1,
        "gid": 508
      }
    ],
    "event": {
      "result": 1
    },
    "module": "Fileman"
  }
}

Note:

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

Parameters

ParameterTypeDescriptionPossible valuesExample

checkleaf

Boolean

Whether to add the isleaf parameter to the output key.

This parameter defaults to 0.

  • 1 — Add the isleaf parameter to the output key.
  • 0 — Do not add the isleaf parameter to the output key.
1
dirstring

The directory.

This parameter defaults to the user's /home directory.

A valid directory name.public_html
filelistBoolean

Whether to search for keys that begin with filepath-*.

This parameter defaults to 0.

  • 1 — Search for keys that begin with filepath-*
  • 0 — Search for keys that do not begin with filepath-*
1
filepath-*string

Which files to list with the output, if the filelist parameter is 1.

Each key indicates a file to view.

This parameter defaults to an empty string.

Any valid filename.filepath-myfile
needmimeBoolean

Whether to return the mimename and mimetype parameters.

This parameter defaults to 0.

  • 1 — Return the mimename and mimetype parameters.
  • 0 — Do not return the mimename and mimetype parameters.
1
showdotfilesBoolean

Whether to add dotfiles to the output keys.

This parameter defaults to 0.

  • 1 — Add dotfiles to the output keys.
  • 0 — Do not add dotfiles to the output keys.
1
typesstring

The types of files to return.

If you do not use this parameter, the function returns all file types.

One or more valid file types, separated by pipe characters.dir|file

 

Returns

ReturnTypeDescriptionPossible valuesExample
ctimeintegerThe file's creation time.A Unix time stamp.1371711650
uidintegerThe file owner's user ID.

A valid user ID on the server.

User
modestringThe file's permissions.A set of file permissions, in textual representation format.
16877
mtimeintegerThe file's last modification time.A Unix time stamp.
1411211655
isleafBooleanWhether the domain contains subdirectories.
  • 0 — The directory contains subdirectories.
  • 1 — The directory does not contain subdirectories.
1
mimenamestringThe file's MIME name.A valid MIME name.
homeb
filestringThe file's name.A valid filename.public_html
pathstring

The path to the file.

A valid absolute file path.

This value does not include the file or directory name.

/home/example/cpbackup-exclude.conf
nicemodeintegerThe file's permissions.A set of file permissions, in octal notation format.
0777
humansize string The formatted size of the file.A positive integer and a unit of measure in Megabytes (MB), Kilobytes (KB), or Gigabytes (GB) .4KB
sizeintegerThe size of the file.A positive integer, in bytes.4096
fullpathstring

The path to the file.

An absolute file path that includes the file or directory name.home/user/public_html
typestringThe item type.
  • file
  • dir
  • char
  • block
  • fifo
  • link
  • socket
file
mimetypestringThe file's MIME type.A valid MIME type.
text/plain
gidintegerThe file owner's system group ID.A positive integer.508
reasonstring

A reason for failure.

Note:

This function only returns a reason value if an error occurred.

A string that describes the error. This is an error message.
resultBoolean

Whether the function succeeded.

  • 1 — The function succeeded.
  • 0 — The function failed.
1