You can find our user documentation at docs.cpanel.net.

Check out our new API beta site!

Child pages
  • UAPI Functions - Fileman::get_file_information
Skip to end of metadata
Go to start of metadata

Description

This function returns the information for a specified file or directory.

Important:

In cPanel & WHM version 76 and later, when you disable the File Storage role, the system disables this function.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Fileman/get_file_information?path=public_html&show_hidden=0&check_for_leaf_directories=1&include_mime=1&include_hash=1&include_permissions=1



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.
 
// Get file info for /home/user/public_html.
$get_file_information = $cpanel->uapi(
    'Fileman', 'get_file_information',
		array(
		'path'								=> 'public_html',
		'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.
 
# Get file info for /home/user/public.html
my $ get_file_information = $cpliveapi->uapi(
 'Fileman', 'get_file_information',
		{
		'path'								=> 'public_html',
		'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.


 Command Line
uapi --user=username Fileman get_file_information path=public_html show_hidden=0 check_for_leaf_directories=1 include_mime=1 include_hash=1 include_permissions=1


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. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
   "module" : "Fileman",
   "result" : {
      "warning" : null,
      "messages" : null,
      "status" : 1,
      "errors" : null,
      "data" : {
         "gid" : 99,
         "size" : "21",
         "fullpath" : "/home/newl/public_html",
         "isleaf" : 0,
         "exists" : 1,
         "file" : "public_html",
         "mimetype" : "publichtml",
         "rawmimetype" : "httpd/unix-directory",
         "type" : "dir",
         "read" : 1,
         "rawmimename" : "httpd/unix-directory",
         "write" : 1,
         "mtime" : 158220764,
         "phash" : "L2hvbWUvbnV3MQ",
         "uid" : 1015,
         "nicemode" : "0750"
         "humansize" : "21 bytes",
         "mode" : 16872,
         "hash" : "L2hvbWUvbmV3MS9wdWJsaWNfaHRtbA",
         "mimename" : "publichtml",
         "path" : "/home/newl",
         "absdir" : "/home/newl",
         "ctime" : 1582207644
      },
      "metadata" : {}
   },
   "func" : "get_file_information",
   "apiversion" : 3
}


    
  


Note:

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

Parameters

ParametersTypeDescriptionPossible valuesExample
pathstring

Required

The directory from which to list files.

A valid directory, relative to the user's home directory.public_html
show_hiddenBoolean

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_directoriesBoolean

Whether to flag directories that contain subdirectories.

This parameter defaults to 0.

  • 1 — Flag directories that contain subdirectories.
  • 0 — Do not flag directories that contain subdirectories.
1
include_mimeBoolean

Whether to return the file's MIME type.

This parameter defaults to 0 .

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

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

This parameter defaults to 0 .

  • 1 — Generate a hash.
  • 0 — Do not generate a hash.
0
include_permissionsBoolean

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
absdirstringThe path to the user's home directory.A valid filepath./home/user
ctimestringThe file's creation time.

A time in Unix time format.

1400573272
existsBooleanWhether the file exists in the directory.
  • 1 — Exists.
  • 0 — Does not exist.
1
filestringThe filename.A valid filename on the server.cgi-bin
fullpathstringThe file's full filepath.A valid filepath on the server./home/user/public_html/cgi-bin
gidintegerThe file owner's system group ID.A positive integer.503
hashstringThe full filepath's hash.A string of letters and integers.L2hvbWUvY29saW4vcHVibGljX2h0bWw
humansizestringThe formatted size of the file.

A positive integer and one of the following symbols:

  • KB — kilobytes
  • MB — megabytes
  • GB — gigabytes
5 KB
isleafBooleanWhether the directory contains subdirectories.
  • 1 — Contains subdirectories.
  • 0 — Does not contain subdirectories.
1
mimenamestringThe file's MIME name.A valid MIME name.publichtml
mimetypestringThe file's MIME type.A valid MIME type.text/plain
modestringThe file's textual permissionsA string value, in Unix format .
16872
mtimestringThe file's last modification time.A time in  Unix time  format. 1400573272
nicemodeintegerThe file's numerical permissions.An integer value, in octal notation .0755
pathstringThe file's path.A valid file path./home/user/public.html
phashstringThe parent filepath's file hash.A string of letters and integers.L2hvbWUvY29saW4vcHVibGljX2h0bWw
rawmimenamestringThe file's raw MIME name.A valid raw MIME name.httpd/unix_directory
rawmimetypestringThe file's raw MIME type.A valid raw MIME type on the server.text/plain
sizeintegerThe file's size.A positive integer, measured in bytes.4096
typestringThe item's type.
  • file — File.
  • dir — Directory.
  • char — Character special device.
  • block — Block special device.
  • fifo — Named pipe (FIFO).
  • link — Symbolic link.
  • socket — Unix domain socket.
file
uidintegerThe file owner's system user ID.A positive integer.502
readBoolean

Whether the file is readable.

The function only returns this value if you set the include_permissions value to 1.

  • 1 — Readable.
  • 0 — Not readable.
1
writeBoolean

Whether the file is writable.

The function only returns this value if you set the include_permissions value to 1 .

  • 1 — Writable.
  • 0 — Not writable.
1