MATLAB®usejava   validateattributes
  

userpath - View or change user portion of search path

Syntax

userpath
userpath('newpath')
userpath('reset')
userpath('clear')

Description

userpath returns a string specifying the user portion of the search path. The user portion of the search path is the first directory on the search path, above the directories supplied by The MathWorks. The default directory is My Documents/MATLAB on Microsoft Windows platforms, and Documents/MATLAB on Microsoft Windows Vista™ platforms. On Apple Macintosh and UNIX[1] platforms, the default value is userhome/Documents/MATLAB. If you remove the userpath directory from the search path and save the changes to the path, it also clears the value of userpath. You can define the userpath directory to also be the MATLAB startup directory. On Windows platforms, userpath is the startup directory, unless the startup directory is otherwise specified, such as by the MATLAB shortcut properties Start in field. On UNIX and Macintosh platforms, the startup directory is userpath if the value of the environment variable MATLAB_USE_USERPATH is set to 1 prior to startup and if the startup directory is not otherwise specified, such as via a startup.m file. On Macintosh and UNIX platforms, you can automatically add additional subdirectories to the top of the search path upon startup by specifying the path for the subdirectories via the MATLABPATH environment variable.

userpath('newpath') sets the userpath value to newpath. The newpath directory appears at the top of the search path immediately and at startup in future sessions, and MATLAB removes the directory previously specified by userpath from the search path. newpath cannot be a relative path. userpath('newpath') does not work when the -nojvm startup option is used. Upon the next startup, newpath, can become the current directory, as described in the syntax for userpath with no arguments.

userpath('reset') sets the userpath value to the default for that platform, creating the Documents/MATLAB (or My Documents/MATLAB) directory if it does not exist. MATLAB immediately adds the default directory to the top of the search path, and also adds it to the path at startup in future sessions; it can become the startup directory as described for the userpath syntax with no arguments. MATLAB removes the directory previously specified by userpath from the search path. userpath('reset') does not work when the -nojvm startup option is used.

userpath('clear') clears the value for userpath. MATLAB the directory previously specified by userpath from the search path. This does not work when the -nojvm startup option is used. You can otherwise specify the startup directory—see Startup Directory for the MATLAB Program.

Examples

Viewing userpath

This example assumes userpath is set to the default value on the Windows XP platform, My Documents\MATLAB. Start MATLAB and run

cd

MATLAB displays the current directory

H:\My Documents\MATLAB

where H is the drive at which My Documents is located for this example. This is the directory specified by userpath. To confirm, run

userpath

and MATLAB returns

H:\My Documents\MATLAB;

Run

path

and MATLAB displays the search path; the userpath portion is at the top:

MATLABPATH

	H:\My Documents\MATLAB
	C:\Program Files\MATLAB\R2008b\toolbox\matlab\general
	C:\Program Files\MATLAB\R2008b\toolbox\matlab\ops

Setting a New Value for userpath

This example assumes userpath is set to the default value on the Windows XP platform, My Documents\MATLAB. To change the value from the default for userpath to C:\Research_Project, run 

userpath('C:\Research_Project')

To view the effect of the change on the search path, run

path

and MATLAB displays the search path, with the new value for userpath portion at the top:

MATLABPATH

	C:\Research_Project
	C:\Program Files\MATLAB\R2008b\toolbox\matlab\general
	C:\Program Files\MATLAB\R2008b\toolbox\matlab\ops
...

Note that MATLAB automatically removed the previous value of userpath, H:\My Documents\MATLAB, from the search path when you assigned a new value to userpath. The next time you start MATLAB, the current directory will be C:\Research_Project on Windows platforms.

Clearing the Value for userpath, and Specifying a New Startup Directory on Windows Platforms

Assume userpath is set to the default value and you do not want any directories to be added to the search path upon startup. To confirm the default is currently set, run

userpath

and MATLAB returns

H:\My Documents\MATLAB

Note the userpath directory at the top of the search path by running

path

MATLAB returns

MATLABPATH

H:\My Documents\MATLAB
C:\Program Files\MATLAB\R2008b\toolbox\matlab\general
C:\Program Files\MATLAB\R2008b\toolbox\matlab\ops
...

To clear the value, run

userpath('clear')

To verify the result, run

userpath

MATLAB returns

ans =
     ''

Confirm the userpath directory was removed from the path by running:

path

MATLAB returns

MATLABPATH

C:\Program Files\MATLAB\R2008b\toolbox\matlab\general
C:\Program Files\MATLAB\R2008b\toolbox\matlab\ops
...

After clearing the userpath value, unless you otherwise specify the startup directory, the startup directory will be the desktop on Windows platforms. There are a number of ways to specify the startup directory. For example, right-click the Windows shortcut icon for MATLAB and select Properties from the context menu. In the Properties dialog box Shortcut tab, enter the full path to the new startup directory in the Start in field, for example, I\:my_matlab_files\my_mfiles. The next time you start MATLAB, the current directory will be I\:my_matlab_files\my_mfiles, but that directory will not be on the search path. Note that you do not have to clear the userpath to specify a different startup directory; when you otherwise specify a startup directory, the userpath directory is added to the search path upon startup, but is not the startup directory.

Removing userpath from the Search Path; Resets the Startup Directory

In this example, assume userpath is set to the default value and you remove the userpath directory from the search path, then save the changes. This has the same effect as clearing the value for userpath. To confirm the default is currently set, run

userpath

and MATLAB returns

H:\My Documents\MATLAB

Note the userpath directory at the top of the search path by running

path

MATLAB returns

MATLABPATH

H:\My Documents\MATLAB
C:\Program Files\MATLAB\R2008b\toolbox\matlab\general
C:\Program Files\MATLAB\R2008b\toolbox\matlab\ops
...

Remove H:\My Documents\MATLAB from the search path and confirm the result by running

rmpath('H:\My Documents\MATLAB')
path

MATLAB returns

MATLABPATH

	C:\Program Files\MATLAB\R2008b\toolbox\matlab\general
	C:\Program Files\MATLAB\R2008b\toolbox\matlab\ops
...

Running

userpath

at this point shows the value is still set

H:\My Documents\MATLAB

Save changes to the path by running

savepath

Now when you run

userpath

MATLAB returns

ans =
     ''

showing the value is now cleared. Removing the directory from the search path and saving the changes to the path has the same effect as clearing the value for userpath. At the next startup, the startup directory will not be H:\My Documents\MATLAB, and H:\My Documents\MATLAB will not be on the search path.

Assigning userpath as the Startup Directory on a UNIX or Macintosh Platform

This example assumes userpath is set to the default value on a Macintosh platform and that you start MATLAB using a bash X11 shell, where smith is the home directory. Set the MATLAB_USE_USERPATH environment variable so that userpath will be used as the startup directory:

export MATLAB_USE_USERPATH=1

From that shell, start MATLAB. After MATLAB starts, verify its current directory by running

pwd

MATLAB returns

/Users/smith/Documents/MATLAB

That is the value defined for userpath, which you can confirm by running

userpath

MATLAB returns

/Users/smith/Documents/MATLAB

The userpath is at the top of the search path, which you can confirm by running

path

MATLAB returns

/Users/smith/Documents/MATLAB
/Users/smith/Applications/MATLAB/R2008b/toolbox/matlab/general
/Users/smith/Applications/MATLAB/R2008b/toolbox/matlab/ops

...

Adding Directories to the Search Path Upon Startup on a UNIX or Macintosh Platform

This example assumes userpath is set to the default value on a UNIX platform with a csh shell, where j is the user's home directory.

To add additional directories to the search path upon startup, for example, /home/j/Documents/MATLAB/mine and /home/j/Documents/MATLAB/mine/research, run the following in an X11 terminal:

setenv MATLABPATH '/home/j/Documents/MATLAB/mine':'/home/j/Documents/MATLAB/mine/research'

Separate multiple directories using a : (colon).

MATLAB displays

MATLABPATH

home/j/Documents/MATLAB
home/j/Documents/MATLAB/mine
home/j/Documents/MATLAB/mine/research
home/j/Applications/MATLAB/R2008b/toolbox/matlab/general
home/j/Applications/MATLAB/R2008b/toolbox/matlab/ops
...

See Also

addpath, path, pathtool, rmpath, savepath, startup,

Startup and Shutdown and Search Path in the MATLAB Desktop Tools and Development Environment documentation

[1] UNIX is a registered trademark of The Open Group in the United States and other countries.

  

usejavausejava validateattributesvalidateattributes

 © 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS