Different operating systems employ distinct conventions for file paths. Some operating systems insists that a path starts with a disk, while others only have directories. Some use "/" separators, while others use "\", some ":", etc. Sometimes, the same operating system will even employ distinct and incompatible conventions for file paths. For this reason, developers should avoid manipulating paths directly. Module OS.Path provides functions designed to manipulate paths in a cross-platform manner.

Similarly, both Firefox and the operating system will store special files and directories in different places. For instance, some versions of Windows place temporary directories in C:\Temp, others in C:\Windows\Temp, Local Settings\Temp, C:\Users\%USER%\AppData\Local\Temp ... For this reason, developers should not make assumptions regarding the path of special files and directories. Module OS.Constants.Path provides constants for a few well-known special paths.

Performance note

The functions detailed in this document work on paths without performing any I/O. You can therefore use them from any thread without fear of blocking I/O.

Global Object OS.Constants.Path

Attributes

libDir string read only The full path to the directory containing the libraries of Firefox (libxul, libnss, etc.)
profileDir string read only The full path to the directory containing the profile of the current user. Some operating systems have both a local profile directory and a roaming profile directory. On such operating systems, this is the roaming profile directory.
tmpDir string read only The full path to the system temporary directory.
homeDir string read only The full path to the user's home directory.
desktopDir string read only The full path to the user's desktop directory.
winAppDataDir string read only The full path to the user's application data directory.
winStartMenuProgsDir string read only The full path to the "Programs" subdirectory in the user's start menu directory.
macUserLibDir string read only The full path to the user's Library directory.
macLocalApplicationsDir string read only The full path to the Applications directory.

Global Object OS.Path

Methods Overview

string basename(in string path)
string dirname(in string path)
string fromFileURI (in string path)
string join(in string path1, in string path2, ...)
string normalize(in string path)
object split(in string path)
string toFileURI (in string path)
string winGetDrive(in string path)
bool winIsAbsolute(in string path)

Methods

OS.Path.basename

Return the final component of a path.

For instance:

  • under Unix, basename("/home/user/bashrc") will produce "bashrc";
  • under Windows, basename("C:\\Windows\\Temp") will produce "Temp".
string basename(
  in string path
)
Arguments
path
A valid path
Returns

The final component of path. This is everything after the last "/" (under Unix) or "\" (under Windows).

OS.Path.dirname

Return the directory part of the path.

For instance:

  • under Unix, dirname("/home/user/bashrc") will produce "/home/user";
  • under Windows, dirname("C:\\Windows\\Temp") will produce "C:\\Windows".
string dirname(
  in string path
)
Arguments
path
A valid path
Returns

Everything before the last "/" (under Unix) or "\" (under Windows). If the last few characters are also "/" (respectively "\"), they are ignored. If the path contains no directory, return ".".
 

OS.Path.fromFileURI

Converts a File URI to system path. See also to acheive opposite result: OS.Path.toFileURI

string fromFileURI(
  in string path
)
Arguments
path
A string that is in the form of a File URI. For example on windows: file:///C:/Users
Returns

A string in system path format. For example on windows file:///C:/Users is converted to C:\Users.

OS.Path.join

Join path components. This file is the recommended manner of getting the path of a file or a subdirectory contained in a directory.

Example:

var tmpDir = OS.Constants.Path.tmpDir;
var path = OS.Path.join(tmpDir, "foo", "bar");

will return

  • "/tmp/foo/bar" on most versions of Unix;
  • "C:\\Windows\\Temp\\foo\\bar" on versions of Windows that place the temporary directory in C:\Windows\Temp;
  • etc.
string join(
  in string path,
  ...in string subpaths
)
Arguments
path
A path
subpaths
Zero, one or more paths that must be appended to path
Returns

The result of concatenaging the paths. If any of the subpaths is absolute, anything before this subpath is ignored. The path may not be normalized.

OS.Path.normalize

Normalize a path by removing unneeded ., .., /, \.

For instance:

  • under Unix, normalize("/a/..//b") will produce "/b";
  • under Windows normalize("C:\\A\\..\\\\B") will produce "C:\\B"
string normalize(
  in string path
) throws Error
Arguments
path
A path
Returns

A path equivalent to path, but in which needless occurrences of ".", "..", "/" and "\" have been removed.

Throws
Error
If path is an invalid path, in particular if it is an absolute path that contains too many occurrences of ".."

OS.Path.split

Split a path into its components.

Examples:

  • Under Unix, split("/tmp/a/b") will produce { absolute: true, components: ["tmp", "a", "b"] };
  • Under Windows, split("C:\\Windows\\Temp") will produce { absolute: true, components: ["Windows", "Temp"], winDrive: "C" }
object split(
  in string path
)
Arguments
path
A path. Generally, it should be normalized (see OS.Path.normalize).
Returns

An object with the following fields:

absolute
true if path is absolute, false otherwise
components
An array containing the components that define path. Under Windows, this array will not contain the drive name.
winDrive
(Windows only) The drive name. If path did not start with a drive name, null.

OS.Path.toFileURI

Converts an absolute system path to a File URI. See also to acheive opposite result: OS.Path.fromFileURI

string toFileURI(
  in string path
)
Arguments
path
A path that is in the form of an absolute system path. For example on windows: C:\Users
Returns

A string in File URI format. For example on windows C:\Users is converted to file:///C:/Users.

If the following characters are found in the supplied path argument, they are returned in encoded form:

  • ; becomes %3b
  • ? becomes %3F
  • ' becomes %27
  • # becomes %23

OS.Path.winGetDrive

Return the drive letter(s) from a path.

string winGetDrive(
   in string path
)

Platform-specific

This function is defined only on Windows platforms. Before attempting to use it, you should perform feature detection, as follows:

if ("winGetDrive" in OS.Path) {
  // The function can be used
} else {
  // The function cannot be used
}
Arguments
path
A Windows path. It may start with a drive name.
Returns
null
If path does not start with a drive name.
string
The drive name of path, if there is one. In the current implementation, the drive name is everything before the first occurrence of ":".

OS.Path.winIsAbsolute

Determine if a path is absolute.

bool winIsAbsolute(
  in string path
)

Platform-specific

This function is defined only on Windows platforms. Before attempting to use it, you should perform feature detection, as follows:

if ("winIsAbsolute" in OS.Path) {
  // The function can be used
} else {
  // The function cannot be used
}
Arguments
path
A Windows path.
Returns

true if the path is absolute, i.e. if it starts with a drive letter, false otherwise

Document Tags and Contributors

Tags: 
 Contributors to this page: ilyakamens, teoli, Noitidart, jukbot, mar.castelluccio, Cykesiopka, Yoric
 Last updated by: ilyakamens,