help findfile
-------------------------------------------------------------------------------
Title
[P] findfile -- Find file in path
Syntax
findfile filename [, path(path) nodescend all]
where filename and path may optionally be enclosed in quotes, and the
default is to look over the ado-path if option path() is not specified.
Description
findfile looks for a file along a specified path and, if the file is
found, displays the fully qualified name and returns the name in r(fn).
If the file is not found, the file-not-found error, r(601), is issued.
Unless told otherwise, findfile looks along the ado-path, the same path
that Stata uses for searching for ado-files, help files, etc.
In programming contexts, findfile is usually preceded by quietly; see [P]
quietly.
findfile is not a utility to search everywhere for a file you have lost.
findfile is for use in those rare ado-files that use prerecorded datasets
and for which you wish to place the datasets along the ado-path, along
with the ado-file itself.
Options
path(path) specifies the path over which findfile is to search. Not
specifying this option is equivalent to specifying
path(`"`c(adopath)'"').
If specified, path should be a list of directory (folder) names
separated by semicolons; for example,
path(`".;~/bin;"~/data/my data";~"')
path(`".;\bin;"\data\my data";~"')
The individual directory names may be enclosed in quotes, but if any
are, remember to enclose the entire path argument in compound quotes.
Also any of the directory names may be specified as STATA, UPDATES,
BASE, SITE, PLUS, PERSONAL, or OLDPLACE, which are indirect
references to directories recorded by sysdir:
path(UPDATES;BASE;SITE;.;PERSONAL;PLUS)
path(\bin:SITE;.;PERSONAL;PLUS)
path(`"\bin;.;"\data\my data";PERSONAL;PLUS"')
path(`".;`c(adopath)'"')
nodescend specifies that findfile not follow Stata's normal practice of
searching in letter subdirectories of directories in the path, as
well as the directories themselves. nodescend is rarely specified,
and, if it is specified, path() would usually be specified, too.
all specifies that all files along the path with the specified name are
to be found and then listed and saved in r(fn). When all is not
specified, the default is to stop the search when the first instance
of the specified name is found.
When all is specified, the fully qualified names of the files found
are returned in r(fn), listed one after the other, and each enclosed
in quotes. Thus when all is specified, if you later need to quote
the returned list, you must use compound double quotes. Also
remember that findfile issues a file-not-found error if no files are
found. If you wish to suppress that and want r(fn) returned
containing nothing, precede findfile with capture. Thus typical
usage of findfile, all is
capture findfile filename, all
local filelist `"`r(fn)'"'
Saved results
findfile saves the following in r():
Macros
r(fn) (all not specified) name of the file found; name not enclosed
in quotes
(all specified) names of the files found, listed one
after the other, each enclosed in
quotes
Also see
Manual: [P] findfile
Help: [P] sysdir, [D] sysuse; [P] _getfilename
