Getting File Information

File and Stream Guide: [ nsIScriptableIO | Accessing Files | Getting File Information | Reading from Files | Writing to Files | Moving, Copying and Deleting Files | Uploading and Downloading Files | Working With Directories ]

Other documentation on files and I/O not using the unavailable nsIScriptableIO APIs: Code snippets: File I/O, Open and Save Dialogs, Reading textual data, Writing textual data, List of file-related error codes.

The nsIFile object has a number of useful attributes which may be used to retrieve information about a file. Two useful attributes fileSize and lastModifiedTime (nsIFile.Attributes) provide a means of retrieving the size of a file and the time when the file was last changed.

File Size

The fileSize (nsIFile.Attributes) attribute holds the size of a file in bytes. If the file does not exist, a 'file not found' exception will occur. You can catch this exception with a try-catch block, but it is better to use nsIFile.exists() to check first. This example will check if a file on the Desktop exists and set the variable 'filesize' to the size of the file. If the file is not present, the 'filesize' variable will not be changed from the default value of 0.

var filesize = 0;
var file = IO.getFile("Desktop", "Saved File");
if (file.exists())
  filesize = file.fileSize;

It is also possible to modify the size of a file by setting the fileSize (nsIFile.Attributes) attribute to a value. This may be useful to truncate a file, however, setting the file size will also increase the size of a file if the value is larger than the current size of the file. In this case, the new part of the file will be filled with empty data. For instance, the following line will set the length of a file to 5000 bytes.

file.fileSize = 5000;

Modified Time

The time that a file was last changed may be retrieved using the lastModifiedTime (nsIFile.Attributes) attribute. This attribute holds a value measured in milliseconds since January 1, 1970. It is convenient to pass the returned time to the Date constructor.

var lastmod = new Date(file.lastModifiedTime);

In this example, a Date object is created using the modification time of a file.

You can change the modification time of a file by setting the lastModifiedTime (nsIFile.Attributes) attribute, or you can just write to the file, in which case the value will be adjusted automatically.

File Permissions

Several methods may be used to check for file permissions. The following four methods return true or false:

• nsIFile.isReadable() - returns true if the file can be read from.
• nsIFile.isWritable() - returns true if the file can be written to.
• nsIFile.isExecutable() - returns true if the file can be executed.
• nsIFile.isHidden() - returns true if the file is hidden.

In this example, an exeception will occur if the file cannot be written to.

if (!file.isWritable())
  throw "File cannot be modified";

If you aren't sure whether a file can be modified, for example, you may wish to check using nsIFile.isWritable() first. Otherwise, an attempt to write to the file will generate an error.

The four methods above are usually sufficient for most purposes. However, you can also use the permissions (nsIFile.Attributes) attribute to get the UNIX-style permission flags for a file. This attribute is also necessary if you need to modify the permissions.

file.permissions = 0640;

It is common to use an octal number (a number in base 8 beginning with 0) for permissions as it can make the value easier to read. In this case, the first digit is the permissions for the owner of the file, the second digit is the permissions for the group of the file and the third digit is the permissions for everyone else. The value is a sum of three values, 4 for readable, 2 for writable and 1 for executable.

The default permissions for files when created through an output stream is 0644, which means that the file is readable and writable by the owner of the file and read only for others.

Some of the permissions may not be supported on some platforms.