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

 

Description

This function returns a sorted list of files and directories.

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. 
  • We introduced this functionality in cPanel & WHM version 56.

 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 (Home >> Advanced >> API Shell) to directly test cPanel API calls.

   

Parameters

ParametersTypeDescriptionPossible valuesExample
dirsstring

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

ReturnTypeDescriptionPossible valuesExample
filesarray of hashesAn 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 outputs this return 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 outputs this return 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
dirsarray of hashesAn 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 outputs this return 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 outputs this return 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