PHP Tools for Working with the File and Operating System

File Types and Links

Numerous functions are available for learning various details about files and links (or file pointers) found on a file system. Those functions are introduced in this section.

filetype()

string filetype (string filename)

The filetype() function determines and returns the file type of filename. Eight values are possible:

1. block: A block device such as a floppy disk drive or CD-ROM.
   
2. char: A character device, which is responsible for a nonbuffered exchange of data between the operating system and a device such as a terminal or printer.
   
3. dir: A directory.
   
4. fifo: A named pipe, which is commonly used to facilitate the passage of information from one process to another.
   
5. file: A hard link, which serves as a pointer to a file inode. This type is produced for anything you would consider to be a file, such as a text document or executable.
   
6. link: A symbolic link, which is a pointer to the pointer of a file.
   
7. socket: A socket resource. At the time of writing, this value is undocumented.
   
8. unknown: The type is unknown.

Let's consider three examples. In the first example, you determine the type of a CD-ROM drive:

echo filetype("/mnt/cdrom"); // char

Next, you determine the type of a Linux partition:

echo filetype("/dev/sda6"); // block

Finally, you determine the type of a regular old HTML file:

echo filetype("/home/www/htdocs/index.html"); // file

link()

int link (string target, string link)

The link() function creates a hard link, link, to target, returning TRUE on success and FALSE otherwise. Note that because PHP scripts typically execute under the guise of the server daemon process owner, this function will fail unless that user has write permissions within the directory in which link is to reside.

linkinfo()

int linkinfo (string path)

The lstat() function is used to return useful information about a symbolic link, including items such as the size, time of last modification, and the owner's user ID. The linkinfo() function returns one particular item offered by the lstat() function, used to determine whether the symbolic link specified by path really exists. This function isn't available for the Windows platform.

lstat()

array lstat (string symlink)

The lstat() function returns numerous items of useful information regarding the symbolic link referenced by symlink. See the following section on fstat() for a complete accounting of the returned array.

fstat()

array fstat (resource filepointer)

The fstat() function retrieves an array of useful information pertinent to a file referenced by a file pointer, filepointer. This array can be accessed either numerically or via associative indices, each of which is listed in its numerically indexed position:

1. dev (0): The device number upon which the file resides.
   
2. ino (1): The file's inode number. The inode number is the unique numerical identifier associated with each file name and is used to reference the associated entry in the inode table that contains information about the file's size, type, location, and other key characteristics.
   
3. mode (2): The file's inode protection mode. This value determines the access and modification privileges assigned to the file.
   
4. nlink (3): The number of hard links associated with the file.
   
5. uid (4): The file owner's user ID (UID).
   
6. gid (5): The file group's group ID (GID).
   
7. rdev (6): The device type, if the inode device is available. Note that this element is not available for the Windows platform.
   
8. size (7): The file size, in bytes.
   
9. atime (8): The time of the file's last access, in Unix timestamp format.
   
10. mtime (9): The time of the file's last modification, in Unix timestamp format.
    
11. ctime (10): The time of the file's last change, in Unix timestamp format.
    
12. blksize (11): The file system's block size. Note that this element is not available on the Windows platform.
    
13. blocks (12): The number of blocks allocated to the file.

Consider the example shown in Listing 10-1.

Listing 10-1. Retrieving Key File Information

<?php

/* Convert timestamp to desired format. */
function tstamp_to_date($tstamp) {
return date("m-d-y g:i:sa", $tstamp);
}

$file = "/usr/local/apache2/htdocs/book/chapter10/stat.php";
/* Open the file */
$fh = fopen($file, "r");

/* Retrieve file information */
$fileinfo = fstat($fh);

/* Output some juicy information about the file. */
echo "Filename: ".basename($file)."<br />";
echo "Filesize: ".round(($fileinfo["size"]/1024), 2)." kb <br />";
echo "Last accessed: ".tstamp_to_date($fileinfo["atime"])."<br />";
echo "Last modified: ".tstamp_to_date($fileinfo["mtime"])."<br />";
?>

This code returns:

--------------------------------------------Filename: stat.php
Filesize: 2.16 kb
Last accessed: 06-09-05 12:03:00pm
Last modified: 06-09-05 12:02:59pm
--------------------------------------------

stat()

array stat (string filename)

The stat() function returns an array of useful information about the file specified by filename, or FALSE if it fails. This function operates exactly like fstat(), returning all of the same array elements; the only difference is that stat() requires an actual file name and path rather than a resource handle.

If filename is a symbolic link, then the information will be pertinent to the file the symbolic link points to, and not the symbolic link itself. To retrieve information about a symbolic link, use lstat(), introduced a bit earlier in this chapter.

readlink()

string readlink (string path)

The readlink() function returns the target of the symbolic link specified by path, or FALSE if an error occurs. Therefore, if link test-link.txt is a symbolic link pointing to test.txt, the following will return the absolute pathname to the file:

echo readlink("/home/jason/test-link.txt");
// returns /home/jason/myfiles/test.txt

symlink()

int symlink (string target, string link)

The symlink() function creates a symbolic link named link to the existing target, returning TRUE on success and FALSE otherwise. Note that because PHP scripts typically execute under the guise of the server daemon process owner, this function will fail unless that daemon owner has write permissions within the directory in which link is to reside. Consider this example, in which symbolic link "03" is pointed to the directory "2003":

<?php
$link = symlink("/www/htdocs/stats/2003", "/www/htdocs/stats/03");
?>