Return directory content

This function returns a sorted list of files and directories.

Important:

When you disable the FileStorage role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Authorizations:
query Parameters
dirs
required
string

The directory from which to list files.

Example: dirs=public_html
check_for_leaf_directories
integer
Default: 0

Whether to return directories that contain subdirectories.

  • 1 — Return subdirectories.
  • 0 — Do not retain subdirectories.
Enum: 0 1
Example: check_for_leaf_directories=1
include_hash
integer
Default: 0

Whether to include a hash of the file's information in the return.

  • 1 — Generate a hash.
  • 0 — Do not generate a hash.
Enum: 0 1
Example: include_hash=0
include_mime
integer
Default: 0

Whether to return the file's MIME type.

  • 1 — Include MIME type.
  • 0 — Do not include MIME type.

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.

Enum: 0 1
Example: include_mime=1
include_permissions
integer
Default: 0

Whether to parse the file owner's read and write permissions.

  • 1 — Parse file permissions.
  • 0 — Do not parse file permissions.
Enum: 0 1
Example: include_permissions=0
limit_to_list
integer

Whether to return only entries that begin with the filepath- prefix.

  • 1 — Return only files that begin with the filepath- prefix.
  • 0 — Return all files.

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

Enum: 0 1
Example: limit_to_list=0
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.
Example: mime_types=text-plain
only_these_files
string

A comma-separated list of files to return.

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

Example: only_these_files=cpbackup-exclude.conf
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.
Example: raw_mime_types=text/plain
show_hidden
integer
Default: 0

Whether to include hidden files in the output.

  • 1 — Include hidden files.
  • 0 — Do not include hidden files.
Enum: 0 1
Example: show_hidden=1
types
Array of strings

A pipe-separated list of file types to return.

  • file — A file.
  • dir — A directory.
  • char — A character special device.
  • block — A block special device.
  • fifo — A named pipe (FIFO).
  • link — A symbolic link.
  • socket — A Unix domain socket.

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

Example: types=file|dir

Responses

Response Schema: application/json
apiversion
integer

The version of the API.

func
string

The name of the method called.

module
string

The name of the module called.

object

Request samples

uapi --output=jsonpretty \
  --user=username \
  Fileman \
  list_files \
  dirs='public_html'

Response samples

Content type
application/json
{
  • "apiversion": 3,
  • "func": "list_files",
  • "module": "Fileman",
  • "result": {
    • "data": {
      • "dirs": [
        • {
          • "absdir": "/home/user",
          • "ctime": 1400573272,
          • "exists": 1,
          • "file": "cgi-bin",
          • "fullpath": "/home/user/public_html/cgi-bin",
          • "gid": 503,
          • "hash": "L2hvbWUvY29saW4vcHVibGljX2h0bWw",
          • "humansize": "5 KB",
          • "isleaf": 1,
          • "isparent": 1,
          • "mimename": "text-plain",
          • "mimetype": "text/plain",
          • "mode": "16877",
          • "mtime": 1400573272,
          • "nicemode": 755,
          • "path": "/home/user/public.html",
          • "phash": "L2hvbWUvY29saW4vcHVibGljX2h0bWw",
          • "rawmimename": "text-plain",
          • "rawmimetype": "text/plain",
          • "read": 1,
          • "size": 4096,
          • "type": "file",
          • "uid": 502,
          • "write": 1
          }
        ],
      • "files": [
        • {
          • "absdir": "/home/user",
          • "ctime": 1400573272,
          • "exists": 1,
          • "file": "cgi-bin",
          • "fullpath": "/home/user/public_html/cgi-bin",
          • "gid": 503,
          • "hash": "L2hvbWUvY29saW4vcHVibGljX2h0bWw",
          • "humansize": "5 KB",
          • "isleaf": 1,
          • "isparent": 1,
          • "mimename": "text-plain",
          • "mimetype": "text/plain",
          • "mode": "16877",
          • "mtime": 1400573272,
          • "nicemode": 755,
          • "path": "/home/user/public.html",
          • "phash": "L2hvbWUvY29saW4vcHVibGljX2h0bWw",
          • "rawmimename": "text-plain",
          • "rawmimetype": "text/plain",
          • "read": 1,
          • "size": 4096,
          • "type": "file",
          • "uid": 502,
          • "write": 1
          }
        ]
      },
    • "errors": null,
    • "messages": null,
    • "metadata": { },
    • "status": 1,
    • "warnings": null
    }
}