3.10. Filesystem Functions

The following functions return information about or are related to the filesystem. See the File class for a class enabling files to be created, read or written, and the Dir class allowing directories to be manipulated.

3.10.1. chdir()

Synopsis

Changes the current working directory.

Usage
chdir(directory_string)
Example
chdir("/usr/share");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.255. Arguments and Return Values for chdir()

Argument Type

Return Type

Description

String

Integer

Changes the current working directory. Returns 0 if successful.


Table 3.256. Exceptions Thrown by chdir()

err

desc

CHDIR-PARAMETER-ERROR

The string for the new directory was missing from the call.


3.10.2. chmod()

Synopsis

Changes the mode of a file.

Usage
chmod(filename, mode)
Example
chmod("/bin/login", 0755);
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.257. Arguments and Return Values for chmod()

Argument Type

Return Type

Description

String, Integer

Integer

Sets the mode of the given file to the integer passed. Returns 0 if successful.


Table 3.258. Exceptions Thrown by chmod()

err

desc

CHMOD-PARAMETER-ERROR

Either the filename or the mode was missing from the call.


3.10.3. chown()

Synopsis

Changes the user and group owners of a file, if the current user has permission to do so (normally only the superuser can change the user owner), follows symbolic links. For a version of this function that does not follow symbolic links, see the lchown() function.

Usage
chown(filepath, user_id, group_id)
Example
chown("/bin/login", 0, 0);
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.259. Arguments and Return Values for chown()

Argument Type

Return Type

Description

String, Integer, Integer

Integer

Changes the owner and group of the file passed. Returns 0 if successful.


Table 3.260. Exceptions Thrown by chown()

err

desc

CHOWN-PARAMETER-ERROR

Expecting a string as the first argument.


3.10.4. getcwd()

Synopsis

Returns a string giving the current working directory.

Usage
getcwd()
Example
my $cwd = getcwd();
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.261. Arguments and Return Values for getcwd()

Argument Type

Return Type

Description

n/a

String

Returns the complete path of the current working directory as a string.


3.10.5. hlstat()

Synopsis

Returns a hash of filesystem values for the file passed; symbolic links are not followed; information is returned about symbolic links (see hstat() for a version of this function that follows symbolic links).

Usage
hlstat(pathname)
Example
$type = hlstat("/bin/sh").type; # returns "REGULAR"
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.262. Arguments and Return Values for hlstat()

Argument Type

Return Type

Description

String

Hash

Returns a hash of filesystem values for the file passed; symbolic links are not followed (information is returned about symbolic links). See also hstat(). See Stat Hash below for a description of the hash returned by this function.


Table 3.263. Stat Hash Description

Key

Value Description

dev

device inode number the file is on

inode

inode of the file

mode

inode protection mode

nlink

number of hard links to this file

uid

user ID of the owner

gid

group ID of the owner

rdev

device type number

size

file size in bytes

atime

last access time of the file

mtime

last modified time of the file

ctime

last change time of the file's inode

blksize

block size

blocks

blocks allocated for the file

type

a string indicating the type of file: 'BLOCK-DEVICE', 'DIRECTORY', 'CHARACTER-DEVICE', 'FIFO', 'SYMBOLIC-LINK', 'SOCKET', 'CHARACTER-DEVICE', 'REGULAR', 'UNKNOWN'


This function does not throw any exceptions.

3.10.6. hstat()

Synopsis

Returns a hash of filesystem values for the file passed; symbolic links are followed; see hlstat() to retrieve information about a symbolic link.

Usage
hstat(pathname)
Example
$type = hstat("/bin/sh").type; # returns "REGULAR"
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.264. Arguments and Return Values for hstat()

Argument Type

Return Type

Description

String

Hash

Returns a hash of filesystem values for the file passed; symbolic links are followed. See also hlstat(). See Stat Hash for a description of the hash returned by this function.


This function does not throw any exceptions.

3.10.7. is_bdev()

Synopsis

Returns True if the string passed identifies a block device file on the filesystem.

Usage
is_bdev(path)
Example
$bool = is_bdev("/dev/sda");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.265. Arguments and Return Values for is_bdev()

Argument Type

Return Type

Description

Path

Boolean

Returns True if the string passed identifies a block device file on the filesystem.


3.10.8. is_cdev()

Synopsis

Returns True if the string passed identifies a character device file on the filesystem.

Usage
is_cdev(path)
Example
$bool = is_cdev("/dev/tty");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.266. Arguments and Return Values for is_cdev()

Argument Type

Return Type

Description

Path

Boolean

Returns True if the string passed identifies a character device file on the filesystem.


3.10.9. is_dev()

Synopsis

Returns True if the string passed identifies a device file (either block or character) on the filesystem.

Usage
is_dev(path)
Example
$bool = is_dev("/dev/sda");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.267. Arguments and Return Values for is_dev()

Argument Type

Return Type

Description

Path

Boolean

Returns True if the string passed identifies a device file (either block or character) on the filesystem.


3.10.10. is_dir()

Synopsis

Returns True if the string passed identifies a directory on the filesystem.

Usage
is_dir(path)
Example
$bool = is_dir("/usr/share");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.268. Arguments and Return Values for is_dir()

Argument Type

Return Type

Description

Path

Boolean

Returns True if the string passed identifies a directory on the filesystem.


3.10.11. is_executable()

Synopsis

Returns True if the string passed identifies an executable file.

Usage
is_executable(path)
Example
$bool = is_executable("/bin/sh");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.269. Arguments and Return Values for is_executable()

Argument Type

Return Type

Description

Path

Boolean

Returns True if the string passed identifies an executable file.


3.10.12. is_file()

Synopsis

Returns True if the string passed identifies a regular file on the filesystem.

Usage
is_file(path)
Example
$bool = is_file("/etc/hosts");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.270. Arguments and Return Values for is_file()

Argument Type

Return Type

Description

Path

Boolean

Returns True if the string passed identifies a regular file on the filesystem.


3.10.13. is_link()

Synopsis

Returns True if the string passed identifies a symbolic link on the filesystem.

Usage
is_link(path)
Example
$bool = is_link("/bin/sh");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.271. Arguments and Return Values for is_link()

Argument Type

Return Type

Description

Path

Boolean

Returns True if the string passed identifies a symbolic link on the filesystem.


3.10.14. is_pipe()

Synopsis

Returns True if the string passed identifies a pipe (FIFO) on the filesystem.

Usage
is_pipe(path)
Example
$bool = is_pipe("/bin/sh");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.272. Arguments and Return Values for is_pipe()

Argument Type

Return Type

Description

Path

Boolean

Returns True if the string passed identifies a pipe (FIFO) on the filesystem.


3.10.15. is_readable()

Synopsis

Returns True if the string passed identifies a file readable by the current user.

Usage
is_readable(path)
Example
$bool = is_readable("/etc/hosts");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.273. Arguments and Return Values for is_readable()

Argument Type

Return Type

Description

Path

Boolean

Returns True if the string passed identifies a file readable by the current user.


3.10.16. is_socket()

Synopsis

Returns True if the string passed identifies a socket on the filesystem.

Usage
is_socket(path)
Example
$bool = is_socket("/tmp/X0");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.274. Arguments and Return Values for is_socket()

Argument Type

Return Type

Description

Path

Boolean

Returns True if the string passed identifies a socket on the filesystem.


3.10.17. is_writeable()

Synopsis

Returns True if the string passed identifies a file writable by the current user.

Usage
is_writeable(path)
Example
$bool = is_writeable("/etc/hosts");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.275. Arguments and Return Values for is_writeable()

Argument Type

Return Type

Description

Path

Boolean

Returns True if the string passed identifies a file writable by the current user.


3.10.18. lchown()

Synopsis

Changes the user and group owners of a file, if the current user has permission to do so (normally only the superuser can change the user owner), does not follow symbolic links. For a version of this function that follows symbolic links, see the chown() function.

Usage
lchown(filepath, user_id, group_id)
Example
lchown("/bin/login", 0, 0);
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.276. Arguments and Return Values for lchown()

Argument Type

Return Type

Description

String, Integer, Integer

Integer

Changes the owner and group of the file passed. Returns 0 if successful.


Table 3.277. Exceptions Thrown by lchown()

err

desc

CHOWN-PARAMETER-ERROR

Expecting a string as the first argument.


3.10.19. lstat()

Synopsis

Returns a list of filesystem values for the file or symbolic link passed. Does not follow symbolic links, but rather returns filesystem information for symbolic links. See also stat() for a version of this function that follows symbolic links, and hlstat() for a version of this function that returns a user-friendly hash instead of a list.

Usage
lstat(pathname)
Example
$list = lstat(("/bin/sh");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.278. Arguments and Return Values for lstat()

Argument Type

Return Type

Description

String

List

Returns a list of filesystem values for the file passed. See Stat List for a description of the list returned by this function.


This function does not throw any exceptions.

3.10.20. mkdir()

Synopsis

Creates a directory, optionally specifying the mode.

Usage
mkdir(string_name, [mode])
Example
mkdir("/tmp/newdir", 0755);
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.279. Arguments and Return Values for mkdir()

Argument Type

Return Type

Description

String, [Integer]

Integer

Creates a directory with the specified name. If the mode parameter is not sent, then 0777 is used by default (which is AND'ed with the umask). Returns 0 if no error occurred.


Table 3.280. Exceptions Thrown by mkdir()

err

desc

MKDIR-PARAMETER-ERROR

Missing directory name for the mkdir() call.


3.10.21. mkfifo()

Synopsis

Creates a named pipe file with an optional file mode (default = 0600).

Usage
mkfifo(filename, [mode])
Example
mkfifo("/tmp/pipe");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.281. Arguments and Return Values for mkfifo()

Argument Type

Return Type

Description

String, [Integer]

Integer

Creates a named pipe with the supplied path and optional mode. If mode is not supplied, then 0660 is used by default.


This function does not throw any exceptions.

3.10.22. rename()

Synopsis

Renames (or moves) files or directories. Note that for this call to function properly, the Qore process must have sufficient permissions and access to the given filesystem objects or paths to execute the rename operation.

This function does not return any value; if any errors occur, an exception is thrown.

Usage
rename(old_path, new_path)
Example
rename("/tmp/temp_file", "/home/test/test_file.txt");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.282. Arguments and Return Values for rename()

Argument Type

Return Type

Description

String, String

n/a

Renames (or moves) the file ior directory indentified by old_path to the new name and/or location given by new_path


Table 3.283. Exceptions Thrown by rename()

err

desc

RENAME-ERROR

Missing arguments or a system error occured.


3.10.23. rmdir()

Synopsis

Removes a directory.

Usage
rmdir(path)
Example
rmdir("/tmp/newdir");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.284. Arguments and Return Values for rmdir()

Argument Type

Return Type

Description

String

Integer

Removes an empty directory. Returns 0 if no error occurred.


Table 3.285. Exceptions Thrown by rmdir()

err

desc

RMDIR-PARAMETER-ERROR

Missing directory name for the rmdir() call.


3.10.24. umask()

Synopsis

Sets the file creation mask for the process.

Usage
umask(mode)
Example
umask(0777);
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.286. Arguments and Return Values for umask()

Argument Type

Return Type

Description

Integer

Integer

Sets the file creation mask for the process, returns 0 for success. If no argument is passed, no action is taken, and the function returns NOTHING.


This function does not throw any exceptions.

3.10.25. unlink()

Synopsis

Deletes a file and returns 0 for success.

Usage
unlink(file)
Example
unlink("/tmp/tmp_file");
Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.287. Arguments and Return Values for unlink()

Argument Type

Return Type

Description

String

Integer

Deletes a file and returns 0 for success.


This function does not throw any exceptions.