3.10. Filesystem Functions

3.10. Filesystem Functions
Prev	Chapter 3. Function Library	Next

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.

Prototype

intchdir(string)

Example

chdir("/usr/share");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.285. Arguments and Return Values for chdir()

Argument Type	Return Type	Description
`string`	`int`	Changes the current working directory. Returns 0 if successful.

Table 3.286. 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.

Prototype

intchmod(string, int)

Example

chmod("/bin/login", 0755);

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.287. Arguments and Return Values for chmod()

Argument Type	Return Type	Description
`string, int`	`int`	Sets the mode of the given file to the integer passed. Returns 0 if successful.

Table 3.288. 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.

Prototype

intchown(string, softint = -1, softint = -1)

Example

chown("/bin/login", 0, 0);

Platform Availability

HAVE_UNIX_FILEMGT

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.289. Arguments and Return Values for chown()

Argument Type	Return Type	Description
`string, int = -1, int = -1`	`int`	Changes the owner and group of the file passed. Returns 0 if successful.

Table 3.290. Exceptions Thrown by chown()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_FILEMGT` before calling this function.

3.10.4. getcwd()

Synopsis

Returns a string giving the current working directory or NOTHING if the current working directory could not be read.

See getcwd2() for a similar function that throws an exception if an error occurs instead.

Prototype

*stringgetcwd()

Example

my *string $cwd = getcwd();

Restrictions

Not available with PO_NO_FILESYSTEM or PO_NO_EXTERNAL_INFO

Table 3.291. 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 or NOTHING if the current working directory could not be read.

3.10.5. getcwd2()

Synopsis

Returns a string giving the current working directory; throws an exception if the current directory cannot be read.

See getcwd() for a similar function that returns NOTHING instead of throwing an exception if an error occurs.

Prototype

stringgetcwd2()

Example

my string $cwd = getcwd2();

Restrictions

Not available with PO_NO_FILESYSTEM or PO_NO_EXTERNAL_INFO

Table 3.292. Arguments and Return Values for getcwd2()

Argument Type	Return Type	Description
n/a	`string`	Returns the complete path of the current working directory as a string.

Table 3.293. Exceptions Thrown by getcwd2()

err	desc
`GETCWD2-ERROR`	The operating system error is reported in the description string.

3.10.6. hlstat()

Synopsis

Returns a hash of file status 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).

See also File::hlstat() for a static method in the File class that throws an exception instead of returning NOTHING when errors occur.

Prototype

*hashhlstat(string$path)

nothinghlstat() (RT_NOOP)

Example

my *string $type = hlstat("/bin/sh").type; # returns "REGULAR"

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.294. Arguments and Return Values for hlstat()

Argument Type	Return Type	Description
`string$path`	`*hash`	Returns a hash of file status values for the file passed or NOTHING if the `stat()` call fails; 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.

This function does not throw any exceptions.

Table 3.295. 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
`type`	a string indicating the type of file: 'BLOCK-DEVICE', 'DIRECTORY', 'CHARACTER-DEVICE', 'FIFO', 'SYMBOLIC-LINK', 'SOCKET', 'CHARACTER-DEVICE', 'REGULAR', 'UNKNOWN'
`perm`	a string symbolizing the permissions of the file/dir/etc like that output by ls, for example: `-rwxr-xr-x`

3.10.7. hstat()

Synopsis

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

If any errors occur, NOTHING is returned and errno() can be used to retrieve the error number.

See also File::hstat() for a static method in the File class that throws an exception instead of returning NOTHING when errors occur.

Prototype

*hashhstat(string$path)

nothinghstat() (RT_NOOP)

Example

my *hash $h = hstat("/bin/sh")

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.296. Arguments and Return Values for hstat()

Argument Type	Return Type	Description
`string$path`	`*hash`	Returns a hash of file status values for the file passed or NOTHING if the `stat()` call fails; 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.8. is_bdev()

Synopsis

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

Prototype

boolis_bdev(string$path) (CONST)

Example

$bool = is_bdev("/dev/sda");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.297. Arguments and Return Values for is_bdev()

Argument Type	Return Type	Description
`string$path`	`bool`	Returns `True` if the string passed identifies a block device file on the filesystem.

3.10.9. is_cdev()

Synopsis

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

Prototype

boolis_cdev(string$path) (CONST)

Example

$bool = is_cdev("/dev/tty");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.298. Arguments and Return Values for is_cdev()

Argument Type	Return Type	Description
`string$path`	`bool`	Returns `True` if the string passed identifies a character device file on the filesystem.

3.10.10. is_dev()

Synopsis

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

Prototype

boolis_dev(string$path) (CONST)

Example

$bool = is_dev("/dev/sda");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.299. Arguments and Return Values for is_dev()

Argument Type	Return Type	Description
`string$path`	`bool`	Returns `True` if the string passed identifies a device file (either block or character) on the filesystem.

3.10.11. is_dir()

Synopsis

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

Prototype

boolis_dir(string$path) (CONST)

Example

$bool = is_dir("/usr/share");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.300. Arguments and Return Values for is_dir()

Argument Type	Return Type	Description
`string$path`	`bool`	Returns `True` if the string passed identifies a directory on the filesystem.

3.10.12. is_executable()

Synopsis

Returns True if the string passed identifies an executable file.

Prototype

boolis_executable(string$path) (CONST)

Example

$bool = is_executable("/bin/sh");

Platform Availability

HAVE_IS_EXECUTABLE

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.301. Arguments and Return Values for is_executable()

Argument Type	Return Type	Description
`string$path`	`bool`	Returns `True` if the string passed identifies an executable file.

Table 3.302. Exceptions Thrown by is_executable()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available; for maximum portability, check the constant `HAVE_IS_EXECUTABLE` before calling this function.

3.10.13. is_file()

Synopsis

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

Prototype

boolis_file(string) (CONST)

Example

$bool = is_file("/etc/hosts");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.303. Arguments and Return Values for is_file()

Argument Type	Return Type	Description
`string`	`bool`	Returns `True` if the string passed identifies a regular file on the filesystem.

3.10.14. is_link()

Synopsis

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

Prototype

boolis_link(string$path) (CONST)

Example

$bool = is_link("/bin/sh");

Platform Availability

HAVE_UNIX_FILEMGT

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.304. Arguments and Return Values for is_link()

Argument Type	Return Type	Description
`string$path`	`bool`	Returns `True` if the string passed identifies a symbolic link on the filesystem.

3.10.15. is_pipe()

Synopsis

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

Prototype

boolis_pipe(string) (CONST)

Example

$bool = is_pipe("/bin/sh");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.305. Arguments and Return Values for is_pipe()

Argument Type	Return Type	Description
`string`	`bool`	Returns `True` if the string passed identifies a pipe (FIFO) on the filesystem.

3.10.16. is_readable()

Synopsis

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

Prototype

boolis_readable(string$path) (CONST)

Example

$bool = is_readable("/etc/hosts");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.306. Arguments and Return Values for is_readable()

Argument Type	Return Type	Description
`string$path`	`bool`	Returns `True` if the string passed identifies a file readable by the current user.

3.10.17. is_socket()

Synopsis

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

Prototype

boolis_socket(string$path) (CONST)

Example

$bool = is_socket("/tmp/X0");

Platform Availability

HAVE_UNIX_FILEMGT

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.307. Arguments and Return Values for is_socket()

Argument Type	Return Type	Description
`string$path`	`bool`	Returns `True` if the string passed identifies a socket on the filesystem.

Table 3.308. Exceptions Thrown by is_socket()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available; for maximum portability, check the constant `HAVE_UNIX_FILEMGT` before calling this function.

3.10.18. is_writeable()

Synopsis

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

Prototype

boolis_writeable(string$path) (CONST)

Example

$bool = is_writeable("/etc/hosts");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.309. Arguments and Return Values for is_writeable()

Argument Type	Return Type	Description
`string$path`	`bool`	Returns `True` if the string passed identifies a file writable by the current user.

3.10.19. 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.

Prototype

intlchown(string$path, softint$uid = -1, softint$gid = -1)

Example

lchown("/bin/login", 0, 0);

Platform Availability

HAVE_UNIX_FILEMGT

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.310. Arguments and Return Values for lchown()

Argument Type	Return Type	Description
`string$path, int$uid = -1, int$gid = -1`	`int`	Changes the owner and group of the file passed. Returns 0 if successful. If either `$uid` or `$gid` are -1, the values are not changed.

Table 3.311. Exceptions Thrown by lchown()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_FILEMGT` before calling this function.

3.10.20. lstat()

Synopsis

Returns a list of file status 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.

Prototype

*listlstat(string$path)

nothinglstat() (RT_NOOP)

Example

my *list $list = lstat("/bin/sh");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.312. Arguments and Return Values for lstat()

Argument Type	Return Type	Description
`string$path`	`*list`	Returns a list of file status 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.21. mkdir()

Synopsis

Creates a directory, optionally specifying the mode.

Prototype

intmkdir(string$path, softint$mode = 0777)

Example

mkdir("/tmp/newdir", 0755);

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.313. Arguments and Return Values for mkdir()

Argument Type	Return Type	Description
`string$path, softint$mode = 0777`	`int`	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.

3.10.22. mkfifo()

Synopsis

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

Prototype

intmkfifo(string$path, softint$mode = 0600)

Example

mkfifo("/tmp/pipe");

Platform Availability

HAVE_UNIX_FILEMGT

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.314. Arguments and Return Values for mkfifo()

Argument Type	Return Type	Description
`string$path, softint$mode = 0600`	`int`	Creates a named pipe with the supplied path and optional mode. If the second argument giving the `mode` is not supplied, then 0660 is used by default.

Table 3.315. Exceptions Thrown by mkfifo()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_FILEMGT` before calling this function.

3.10.23. readlink()

Synopsis

Returns the target of a symbolic link; throws an exception if an error occurs (ex: file does not exist or is not a symbolic link).

Prototype

stringreadlink(string$path)

Example

my string $str = readlink("/tmp/symbolic_link");

Platform Availability

HAVE_UNIX_FILEMGT

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.316. Arguments and Return Values for readlink()

Argument Type	Return Type	Description
`stringstring$path)`	`string`	Returns the target of a symbolic link as string; throws an exception if an error occurs (ex: file does not exist or is not a symbolic link).

Table 3.317. Exceptions Thrown by readlink()

err	desc
`READLINK-ERROR`	Invalid arguments or a system error occured (ex: file does not exist or is not a symbolic link).
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_UNIX_FILEMGT` before calling this function.

3.10.24. 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.

Prototype

nothingrename(string$old_path, string$new_path)

Example

rename("/tmp/temp_file", "/home/test/test_file.txt");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.318. Arguments and Return Values for rename()

Argument Type	Return Type	Description
`string$old_path, string$new_path`	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.319. Exceptions Thrown by rename()

err	desc
`RENAME-ERROR`	Invalid arguments or a system error occured.

3.10.25. rmdir()

Synopsis

Removes a directory.

Prototype

intrmdir(string$path)

Example

rmdir("/tmp/newdir");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.320. Arguments and Return Values for rmdir()

Argument Type	Return Type	Description
`string$path`	`int`	Removes an empty directory. Returns 0 if no error occurred.

3.10.26. stat()

Synopsis

Returns a list of file status values for the file passed, following any symbolic links. If any errors occur, NOTHING is returned and errno() can be used to retrieve the error number.

See also lstat() for a version of this function that does not follow symbolic links, and see hstat() for a version of this function that returns a user-friendly hash instead of a list.

See also File::stat() for a static method in the File class that throws an exception instead of returning NOTHING when errors occur.

Prototype

*liststat(string$path)

nothingstat() (RT_NOOP)

Example

$mode = stat($filepath)[2];

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.321. Arguments and Return Values for stat()

Argument Type	Return Type	Description
`string$path`	`*list`	Returns a list of file status values for the file passed, following symbolic links or NOTHING if the call fails. See Stat List below for a description of the list returned by this function.

This function does not throw any exceptions.

Table 3.322. Stat List Description

Position	Data Type	Description
0	`int`	device inode number the file is on
1	`int`	inode of the file
2	`int`	inode protection mode
3	`int`	number of hard links to this file
4	`int`	user ID of the owner
5	`int`	group ID of the owner
6	`int`	device type number
7	`int`	file size in bytes
8	`date`	last access time of the file
9	`date`	last modified time of the file
10	`date`	last change time of the file's inode
11	`int`	block size
12	`int`	blocks allocated for the file

3.10.27. statvfs()

Synopsis

Returns a hash of filesystem status values for the file or directory path passed.

If any errors occur, NOTHING is returned and errno() can be used to retrieve the error number.

See also File::statvfs() for a static method in the File class that throws an exception instead of returning NOTHING when errors occur.

Prototype

*hashstatvfs(string$path)

Example

my *hash $h = statvfs("/tmp")

Platform Availability

HAVE_STATVFS

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.323. Arguments and Return Values for statvfs()

Argument Type	Return Type	Description
`string$path`	`*hash`	Returns a hash of filesystem status values for the file or directory name passed or NOTHING if the `statvfs()` call fails. See also File::statvfs(). See Filesystem Status Hash for a description of the hash returned by this function.

Table 3.324. Exceptions Thrown by statvfs()

err	desc
`MISSING-FEATURE-ERROR`	This exception is thrown when the function is not available on the runtime platform; for maximum portability, check the constant `HAVE_STATVFS` before calling this function.

Table 3.325. Filesystem Status Hash Description

Key	Value Description
`namemax`	The maximum length in mytes of file names on the filesystem
`fsid`	The filesystem ID; may not be set or meaningful on all filesystems/systems: see system documentation for `statvfs()`
`frsize`	The size in bytes of the minimum allocation unit on the filesystem
`bsize`	The filesystem's block size
`flag`	Flags describing mount options for the filesystem
`files`	The total number of inodes on the filesystem
`favail`	The number of free inodes available to unpriviledged users
`ffree`	The total number of free indes available to priviledged users
`blocks`	The total number of blocks on the filesystem (capacity in bytes = bsize * blocks)
`bavail`	The number of free blocks available to unpriviledged users (bytes = bsize * bavail)
`bfree`	The total number of free indes available to priviledged users (bytes = bsize * bfree)

3.10.28. umask()

Synopsis

Sets the file creation mask for the process.

Prototype

intumask(softint$mask)

nothingumask() (RT_NOOP)

Example

umask(0777);

Restrictions

Not available with PO_NO_PROCESS_CONTROL

Table 3.326. Arguments and Return Values for umask()

Argument Type	Return Type	Description
`softint$mask`	`int`	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.29. unlink()

Synopsis

Deletes a file and returns 0 for success.

Prototype

intunlink(string$path)

nothingunlink() (RT_NOOP)

Example

unlink("/tmp/tmp_file");

Restrictions

Not available with PO_NO_FILESYSTEM

Table 3.327. Arguments and Return Values for unlink()

Argument Type	Return Type	Description
`string$path`	`int`	Deletes a file and returns 0 for success.

This function does not throw any exceptions.

Prev	Up	Next
3.9. Digest Functions	Home	3.11. Data Compression Functions