cPanel API 2 Functions - Fileman::listfiles

Warning:

The cPanel API 2 system is deprecated. We strongly recommend that you use UAPI instead of cPanel API 2.

Description

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

Warning:

This function is deprecated as of cPanel and WHM version 11.40 and later. We strongly recommend that you use the following UAPI functions 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.

Important:

When you disable the File Storage role, the system disables 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)

Warnings:

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

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.
You must include the --user=username option.
For more information and additional output options, read our Guide to cPanel API 2 documentation or run the cpapi2 --help command.
If you run CloudLinux™, you must use the full path of the cpapi2 command:
```
/usr/local/cpanel/bin/cpapi2
```

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

Parameter	Type	Description	Possible values	Example
`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`
`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 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`
`needmime`	Boolean	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`
`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, in textual representation format.	`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, 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`
`size`	integer	The size of the file.	A positive integer, in bytes.	`4096`
`fullpath`	string	The path to the file.	An absolute file path that includes 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. This function only returns a `reason` value 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`