This is documentation for Mathematica 5, which was
based on an earlier version of the Wolfram Language.
View current documentation (Version 11.1)

Documentation / Mathematica / The Mathematica Book / Principles of Mathematica / Files and Streams /

2.12.4 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 Section 1.11.2, 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.

Manipulating directories.

This gives a string representing your current working directory.

In[1]:= Directory[ ]

Out[1]= /users/sw

This sets your current working directory to be the Packages subdirectory.

In[2]:= SetDirectory["Packages"]

Out[2]= /users/sw/Packages

Now your current working directory is different.

In[3]:= Directory[ ]

Out[3]= /users/sw/Packages

This reverts to your previous working directory.

In[4]:= ResetDirectory[ ]

Out[4]= /users/sw

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 DirectoryStack[ ]. 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.

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.

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.

In[5]:= $Path

Out[5]= {., ~, /users/math/bin, /users/math/Packages}

Getting lists of files in particular directories.

Here is a list of all files in the current working directory whose names end with .m.

In[6]:= FileNames["*.m"]

Out[6]= {alpha.m, control.m, signals.m, test.m}

This lists files whose names start with a in the current directory, and in subdirectories with names that start with P.

In[7]:= FileNames["a*", {".", "P*"}]

Out[7]= {alpha.m, Packages/astrodata, Packages/astro.m,


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.

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, Unix systems in the form dir/dir/name and Macintosh systems 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.

In[8]:= DirectoryName["Packages/Math/test.m"]


This constructs the full name of another file in the same directory as test.m.

In[9]:= ToFileName[%, "abc.m"]


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.

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