« XPCOM API Reference


The NS_NewLocalFile function creates an instance of nsILocalFile that provides a platform independent representation of a file path.

#include "nsXPCOM.h"
#include "nsILocalFile.h"
nsresult NS_NewLocalFile(
  const nsAString& aPath,
  PRBool aFollowLinks,
  nsILocalFile** aResult


[in] A UTF-16 string object that specifies an absolute filesystem path. This path does not need to reference an existing file. It is an error to pass a relative filesystem path.
[in] This attribute will determine if the nsILocalFile instance will automatically resolve symbolic links. This parameter has no effect on UNIX systems. On Windows, passing true causes shortcuts to be automatically resolved, and on MacOS, passing true causes finder aliases to be automatically resolved.
[out] A reference to the newly created nsILocalFile instance.

Return Values

The NS_NewLocalFile function returns NS_OK if successful. Otherwise, it returns an error code.

Indicates that the specified path is invalid. This error is returned if a relative file path is passed to NS_NewLocalFile.


On UNIX systems, the prefix "~/" is supported as a shorthand for the user's home directory.

Example Code

// Create a local file that references c:\foo.txt
nsresult rv;
nsCOMPtr<nsILocalFile> file;
rv = NS_NewLocalFile(nsEmbedString(L"c:\\foo.txt"), PR_FALSE,
if (NS_FAILED(rv))
  return rv;

Note: GCC requires the -fshort-wchar option to compile this example since PRUnichar is an unsigned short. This example should compile by default under MSVC.

nsEmbedString is used to convert the UCS-2 character array to an object that can be passed as a const nsAString& parameter.


This function was finalized for Mozilla 1.0. See bug 129279 for details.

See Also

nsILocalFile, nsIFile

Document Tags and Contributors

 Contributors to this page: Sheppy, Fionn, DarinFisher, Nickolay
 Last updated by: Sheppy,