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 ]

Important note: The pages from the File and Stream Guide use the IO object (nsIScriptableIO), which was not available in any released version of the platform (pending some fixes). There are alternative XPCOM APIs you can use, your help in updating this pages to use the supported API is very much welcome!

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.

Files and Streams

This section describes how to access and get information about files, read from files and create and write files.

Using Files

A XUL application or extension may access files on disk, and either read or write to files. A file is accessed via a File object. To get a reference to a File object use nsIScriptableIO.getFile(). The following example will retrieve a reference to a file located in the profile directory named sample.txt.

var file = IO.getFile("Profile", "sample.txt");

The nsIScriptableIO object is a global object always available within an application or extension. It provides a number of useful functions for dealing with files.

Retrieve a File Object
For information about getting a File Object, see Accessing Files
Get Information about a File
Available information about a file include the permissions, size, and last modified date of a file. See Getting File Information for more details.
Reading from a File
For information about reading from text and binary files, see Reading from Files.
Writing to a File
For information about writing to text and binary files, see Writing to Files.
Copying and Moving Files
Files may be moved and copied on disk. For details, see Copying a File and Moving a File.
Deleting Files
To learn how to delete a file, see Deleting a File.
Open and Save Dialogs
You can show a dialog to the user to allow them to select a file to open or enter a filename for saving. For details about this, see Open and Save Dialogs.
File Errors
See File Errors for a list of errors that might occur while using files.

Working With Directories

Directories may be accessed in a similar manner using nsIScriptableIO.getFile(). For instance, in the following example, a subdirectory is retrieved. If the name 'subdirname' refers to a directory, then the returned object will refer to this directory. The returned value is still a nsIFile object, however a number of methods may be used which are only of value for subdirectories.

var file = IO.getFile("Profile", "subdirname");

For more information about using directories, see Working with Directories. Specifically, to create a directory, see Creating Directories and to retrieve a list of files or subdirectories within a directory, see Iterating over the Files in a Directory.

Upload and Download Files

Upload Files
To learn how to upload and post files to a web site, see Uploading and Downloading Files.
Download Files
To learn how to download and save a file from a web site to disk, see Downloading Files.