cPanel API 2 Functions - Fileman::listfiles - Knowledgebase

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 UAPIfunctions instead of this function:

Fileman::get_file_information — This function returns the information for a specified file or directory.
Fileman::list_files — This function returns a sorted list of files and directories.

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

 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',
 )
);

 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',
    }
 );

cPanel Tag System (deprecated)

Warning:

In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. We strongly recommend that youonly 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.

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

Parameters

Parameter	Type	Description	Possible values	Example
checkleaf	Boolean	Whether to add the isleafparameter to the output key. This parameter defaults to 0.	1 — Add the isleaf parameter to the output key. 0 — Do not add the isleafparameter to the output key.	1
dir	string	The directory. This parameter defaults to the user's/home directory.	A valid directory name.	public_html
filelist	Boolean	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 notbegin 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
needmime	Boolean	Whether to return the mimenameand mimetype parameters. This parameter defaults to 0.	1 — Return the mimenameand mimetype parameters. 0 — Do not return the mimenameand mimetype parameters.	1
showdotfiles	Boolean	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
types	string	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

Return	Type	Description	Possible values	Example
ctime	integer	The file's creation time.	A Unix time stamp.	1371711650
uid	integer	The file owner's user ID.	A valid user ID on the server.	User
mode	string	The file's permissions.	A set of file permissions, intextual representationformat.	16877
mtime	integer	The file's last modification time.	A Unix time stamp.	1411211655
isleaf	Boolean	Whether the domain contains subdirectories.	0 — The directory contains subdirectories. 1 — The directory does not contain subdirectories.	1
mimename	string	The file's MIME name.	A valid MIME name.	homeb
file	string	The file's name.	A valid filename.	public_html
path	string	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
nicemode	integer	The file's permissions.	A set of file permissions, inoctal 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
size	integer	The size of the file.	A positive integer, in bytes.	4096
fullpath	string	The path to the file.	An absolute file path thatincludes the file or directory name.	home/user/public_html
type	string	The item type.	file dir char block fifo link socket	file
mimetype	string	The file's MIME type.	A valid MIME type.	text/plain
gid	integer	The file owner's system group ID.	A positive integer.	508
reason	string	A reason for failure. Note: This function only returns a reasonvalue if an error occurred.	A string that describes the error.	This is an error message.
result	Boolean	Whether the function succeeded.	1 — The function succeeded. 0 — The function failed.	1

Knowledgebase

Categories

Categories