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

 

Description

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

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.

 

 cPanel Template Toolkit
<!-- Get a hash of all the data, then display the file value. -->
[% data = execute( 'Fileman', 'get_file_information' {'path' => 'public_html', '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', 'get_file_information' {'path' => 'public_html', '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 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. 
  • We introduced this functionality in cPanel & WHM version 56.

 Output (JSON)
{
  "messages": null,
  "errors": null,
  "status": 1,
  "data": {
    	"absdir": "/home/example/public_html",
 		"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
  }
}

Note:

Use cPanel's API Shell interface (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
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
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 set.
  • block — Block of text.
  • fifoFirst In, First Out (FIFO) data buffer.
  • link — Link.
  • socket — Network 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