This is documentation for Mathematica 6, which was
based on an earlier version of the Wolfram Language.
 Mathematica Tutorial Functions »|Tutorials »

# Naming and Finding Files

The precise details of the naming of files differ from one computer system to another. Nevertheless, Mathematica provides some fairly general mechanisms that work on all systems.
As mentioned in "Finding and Manipulating Files", Mathematica assumes that all your files are arranged in a hierarchy of directories. To find a particular file, Mathematica must know both what the name of the file is, and what sequence of directories it is in.
At any given time, however, you have a current working directory, and you can refer to files or other directories by specifying where they are relative to this directory. Typically you can refer to files or directories that are actually in this directory simply by giving their names, with no directory information.
 Directory[] your current working directory SetDirectory["dir"] set your current working directory ResetDirectory[] revert to your previous working directory

Manipulating directories.

This gives a string representing your current working directory.
 Out[1]=
This sets your current working directory to be the Packages subdirectory.
 Out[2]=
Now your current working directory is different.
 Out[3]=
This reverts to your previous working directory.
 Out[4]=
When you call SetDirectory, you can give any directory name that is recognized by your operating system. Thus, for example, on Unix-based systems, you can specify a directory one level up in the directory hierarchy using the notation .., and you can specify your "home" directory as ~.
Whenever you go to a new directory using SetDirectory, Mathematica always remembers what the previous directory was. You can return to this previous directory using ResetDirectory. In general, Mathematica maintains a stack of directories, given by . Every time you call SetDirectory, it adds a new directory to the stack, and every time you call ResetDirectory it removes a directory from the stack.
 ParentDirectory[] the parent of your current working directory \$InitialDirectory the initial directory when Mathematica was started \$HomeDirectory your home directory, if this is defined \$BaseDirectory the base directory for systemwide files to be loaded by Mathematica \$UserBaseDirectory the base directory for user-specific files to be loaded by Mathematica \$InstallationDirectory the top-level directory in which your Mathematica installation resides

Special directories.

Whenever you ask for a particular file, Mathematica in general goes through several steps to try and find the file you want. The first step is to use whatever standard mechanisms exist in your operating system or shell.
Mathematica scans the full name you give for a file, and looks to see whether it contains any of the "metacharacters" *, \$, ~, ?, [, ", \ and '. If it finds such characters, then it passes the full name to your operating system or shell for interpretation. This means that if you are using a Unix-based system, then constructions like name* and \$VAR will be expanded at this point. But in general, Mathematica takes whatever was returned by your operating system or shell, and treats this as the full file name.
For output files, this is the end of the processing that Mathematica does. If Mathematica cannot find a unique file with the name you specified, then it will proceed to create the file.
If you are trying to get input from a file, however, then there is another round of processing that Mathematica does. What happens is that Mathematica looks at the value of the Path option for the function you are using to determine the names of directories relative to which it should search for the file. The default setting for the Path option is the global variable \$Path.
 Get["file",Path->{"dir1","dir2",...}] get a file, searching for it relative to the directories diri \$Path default list of directories relative to which to search for input files

Search path for files.

In general, the global variable \$Path is defined to be a list of strings, with each string representing a directory. Every time you ask for an input file, what Mathematica effectively does is temporarily to make each of these directories in turn your current working directory, and then from that directory to try and find the file you have requested.
Here is a typical setting for \$Path. The current directory (.) and your home directory (~) are listed first.
 Out[5]=
 FileNames[] list all files in your current working directory FileNames["form"] list all files in your current working directory whose names match the string pattern form FileNames[{"form1","form2]",...}] list all files whose names match any of the formi FileNames[forms,{"dir1","dir2",...}] give the full names of all files whose names match forms in any of the directories diri FileNames[forms,dirs,n] include files that are in subdirectories up to n levels down FileNames[forms,dirs,Infinity] include files in all subdirectories FileNames[forms,\$Path,Infinity] give all files whose names match forms in any subdirectory of the directories in \$Path

Getting lists of files in particular directories.

Here is a list of all files in the current working directory whose names end with .m.
 Out[6]=
 Out[7]=
FileNames returns a list of strings corresponding to file names. When it returns a file that is not in your current directory, it gives the name of the file relative to the current directory. Note that all names are given in the format appropriate for the particular computer system on which they were generated.
 DirectoryName["file"] extract the directory name from a file name ToFileName["directory","name"] assemble a full file name from a directory name and a file name ParentDirectory["directory"] give the parent of a directory ToFileName[{"dir1","dir2",...},"name"] assemble a full file name from a hierarchy of directory names ToFileName[{"dir1","dir2",...}] assemble a single directory name from a hierarchy of directory names

Manipulating file names.

You should realize that different computer systems may give file names in different ways. Thus, for example, Windows systems typically give names in the form dir:\dir\dir\name and Unix systems give names in the form dir/dir/name. The function ToFileName assembles file names in the appropriate way for the particular computer system you are using.
This gives the directory portion of the file name.
 Out[8]=
This constructs the full name of another file in the same directory as test.m.
 Out[9]=
If you want to set up a collection of related files, it is often convenient to be able to refer to one file when you are reading another one. The global variable \$Input gives the name of the file from which input is currently being taken. Using DirectoryName and ToFileName you can then conveniently specify the names of other related files.
 \$Input the name of the file or stream from which input is currently being taken

Finding out how to refer to a file currently being read by Mathematica.