850 lines
405 KiB
HTML
850 lines
405 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=0.8"/><title>15.2 Filesystem</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="extras.css" title="default"/><link rel="stylesheet" type="text/css" href="../racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">The Racket Reference</a></td></tr></table></div><div class="tocviewsublisttop" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="model.html" class="tocviewlink" data-pltdoc="x">Language Model</a></td></tr><tr><td align="right">2 </td><td><a href="notation.html" class="tocviewlink" data-pltdoc="x">Notation for Documentation</a></td></tr><tr><td align="right">3 </td><td><a href="syntax.html" class="tocviewlink" data-pltdoc="x">Syntactic Forms</a></td></tr><tr><td align="right">4 </td><td><a href="data.html" class="tocviewlink" data-pltdoc="x">Datatypes</a></td></tr><tr><td align="right">5 </td><td><a href="structures.html" class="tocviewlink" data-pltdoc="x">Structures</a></td></tr><tr><td align="right">6 </td><td><a href="mzlib_class.html" class="tocviewlink" data-pltdoc="x">Classes and Objects</a></td></tr><tr><td align="right">7 </td><td><a href="mzlib_unit.html" class="tocviewlink" data-pltdoc="x">Units</a></td></tr><tr><td align="right">8 </td><td><a href="contracts.html" class="tocviewlink" data-pltdoc="x">Contracts</a></td></tr><tr><td align="right">9 </td><td><a href="match.html" class="tocviewlink" data-pltdoc="x">Pattern Matching</a></td></tr><tr><td align="right">10 </td><td><a href="control.html" class="tocviewlink" data-pltdoc="x">Control Flow</a></td></tr><tr><td align="right">11 </td><td><a href="concurrency.html" class="tocviewlink" data-pltdoc="x">Concurrency and Parallelism</a></td></tr><tr><td align="right">12 </td><td><a href="Macros.html" class="tocviewlink" data-pltdoc="x">Macros</a></td></tr><tr><td align="right">13 </td><td><a href="input-and-output.html" class="tocviewlink" data-pltdoc="x">Input and Output</a></td></tr><tr><td align="right">14 </td><td><a href="security.html" class="tocviewlink" data-pltdoc="x">Reflection and Security</a></td></tr><tr><td align="right">15 </td><td><a href="os.html" class="tocviewselflink" data-pltdoc="x">Operating System</a></td></tr><tr><td align="right">16 </td><td><a href="memory.html" class="tocviewlink" data-pltdoc="x">Memory Management</a></td></tr><tr><td align="right">17 </td><td><a href="unsafe.html" class="tocviewlink" data-pltdoc="x">Unsafe Operations</a></td></tr><tr><td align="right">18 </td><td><a href="running.html" class="tocvie
|
||
|
|
by <span class="RktVar">kind</span>, which must be one of the following:</div></p><ul><li><p><a name="(idx._(gentag._317._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">home-dir</span> —<wbr></wbr> the current <a name="(tech._user's._home._directory)"></a><span style="font-style: italic">user’s home
|
||
|
|
directory</span>.</p><p>On all platforms, if the <a name="(idx._(gentag._318._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">PLTUSERHOME</span> environment
|
||
|
|
variable is defined as a <a href="Manipulating_Paths.html#%28tech._complete%29" class="techoutside" data-pltdoc="x"><span class="techinside">complete</span></a> path, then the path is used
|
||
|
|
as the user’s home directory.</p><p>On Unix and Mac OS, when <span class="stt">PLTUSERHOME</span> does not apply,
|
||
|
|
the user’s home directory is determined by
|
||
|
|
expanding the path <span class="stt">"~"</span>, which is expanded by first checking
|
||
|
|
for a <a name="(idx._(gentag._319._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">HOME</span> environment variable. If none is defined,
|
||
|
|
the <a name="(idx._(gentag._320._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">USER</span> and <a name="(idx._(gentag._321._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">LOGNAME</span> environment
|
||
|
|
variables are consulted (in that order) to find a user name, and then
|
||
|
|
system files are consulted to locate the user’s home directory.</p><p>On Windows, when <span class="stt">PLTUSERHOME</span> does not apply,
|
||
|
|
the user’s home directory is the user-specific profile
|
||
|
|
directory as determined by the Windows registry. If the registry
|
||
|
|
cannot provide a directory for some reason, the value of the
|
||
|
|
<a name="(idx._(gentag._322._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">USERPROFILE</span> environment variable is used instead, as
|
||
|
|
long as it refers to a directory that exists. If <span class="stt">USERPROFILE</span>
|
||
|
|
also fails, the directory is the one specified by the
|
||
|
|
<a name="(idx._(gentag._323._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">HOMEDRIVE</span> and <a name="(idx._(gentag._324._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">HOMEPATH</span> environment
|
||
|
|
variables. If those environment variables are not defined, or if the
|
||
|
|
indicated directory still does not exist, the directory containing
|
||
|
|
the current executable is used as the home directory.</p></li><li><p><a name="(idx._(gentag._325._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">pref-dir</span> —<wbr></wbr> the standard directory for
|
||
|
|
storing the current user’s preferences. The preferences directory
|
||
|
|
might not exist.</p><p>On Unix, the preferences directory is normally the <span class="stt">"racket"</span>
|
||
|
|
subdirectory of the path specified by
|
||
|
|
<a name="(idx._(gentag._326._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">XDG_CONFIG_HOME</span>, or <span class="stt">".config/racket"</span> in the
|
||
|
|
<a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a> if <span class="stt">XDG_CONFIG_HOME</span> is not set
|
||
|
|
to an absolute path or if <span class="stt">PLTUSERHOME</span> is set. Either way, if
|
||
|
|
that directory does not exist but a <span class="stt">".racket"</span> directory
|
||
|
|
exists in the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a>, then that directory is
|
||
|
|
the preference directory, instead.</p><p>On Windows, the preferences directory is <span class="stt">"Racket"</span> in the
|
||
|
|
<a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a> if determined by <span class="stt">PLTUSERHOME</span>,
|
||
|
|
otherwise in the user’s application-data folder as specified by the
|
||
|
|
Windows registry; the application-data folder is usually
|
||
|
|
<span class="stt">"Application Data"</span> in the user’s profile directory.</p><p>On Mac OS, the preferences directory is
|
||
|
|
<span class="stt">"Library/Preferences"</span> in the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a>.</p></li><li><p><a name="(idx._(gentag._327._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">pref-file</span> —<wbr></wbr> a file that contains a
|
||
|
|
symbol-keyed association list of preference values. The file’s
|
||
|
|
directory path always matches the result returned for
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">pref-dir</span>. The file name is <span class="stt">"racket-prefs.rktd"</span> on Unix
|
||
|
|
and Windows, and it is <span class="stt">"org.racket-lang.prefs.rktd"</span> on Mac OS.
|
||
|
|
The file’s directory might not exist. See also
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._get-preference%29%29" class="RktValLink" data-pltdoc="x">get-preference</a></span>.</p></li><li><p><a name="(idx._(gentag._328._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">temp-dir</span> —<wbr></wbr> the standard directory for
|
||
|
|
storing temporary files. On Unix and Mac OS, this is the directory
|
||
|
|
specified by the <a name="(idx._(gentag._329._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">TMPDIR</span> environment variable, if it
|
||
|
|
is defined, otherwise it is the first path that exists among
|
||
|
|
<span class="stt">"/var/tmp"</span>, <span class="stt">"/usr/tmp"</span>, and <span class="stt">"/tmp"</span>. On
|
||
|
|
Windows, the result is the directory specified by the
|
||
|
|
<a name="(idx._(gentag._330._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">TMP</span> or <a name="(idx._(gentag._331._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">TEMP</span> environment variable,
|
||
|
|
if it is defined, otherwise it is the current directory.</p></li><li><p><a name="(idx._(gentag._332._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">init-dir</span> —<wbr></wbr> the directory containing the
|
||
|
|
initialization file used by the Racket executable.</p><p>On Unix, the initialization directory is the same as the result
|
||
|
|
returned for <span class="RktVal">'</span><span class="RktVal">pref-dir</span>—<wbr></wbr>unless that directory does not
|
||
|
|
exist and a <span class="stt">".racketrc"</span> file exists in the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home
|
||
|
|
directory</span></a>, in which case the home directory is the initialization
|
||
|
|
directory.</p><p>On Windows, the initialization directory is the same as the
|
||
|
|
<a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a>.</p><p>On Mac OS, the initialization directory is <span class="stt">"Library/Racket"</span>
|
||
|
|
in the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a>—<wbr></wbr>unless no
|
||
|
|
<span class="stt">"racketrc.rktl"</span> exists there and a <span class="stt">".racketrc"</span> file
|
||
|
|
does exist in the home directory, in which case the home directory is
|
||
|
|
the initialization directory.</p></li><li><p><a name="(idx._(gentag._333._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">init-file</span> —<wbr></wbr> the file loaded at start-up by
|
||
|
|
the Racket executable. The directory part of the
|
||
|
|
path is the same path as returned for <span class="RktVal">'</span><span class="RktVal">init-dir</span>.</p><p>On Windows, the file part of the name is
|
||
|
|
<a name="(idx._(gentag._334._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">"racketrc.rktl"</span>.</p><p>On Unix and Mac OS, the file part of the name is
|
||
|
|
<a name="(idx._(gentag._335._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">"racketrc.rktl"</span>—<wbr></wbr>unless the path returned for
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">init-dir</span> is the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a>, in which case
|
||
|
|
the file part of the name is <a name="(idx._(gentag._336._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">".racketrc"</span>.</p></li><li><p><a name="(idx._(gentag._337._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">config-dir</span> —<wbr></wbr> a directory for
|
||
|
|
the installation’s configuration. This directory is specified by the
|
||
|
|
<a name="(idx._(gentag._338._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">PLTCONFIGDIR</span> environment variable, and it can be
|
||
|
|
overridden by the <span class="nobreak"><span class="stt">--config</span></span> or <span class="nobreak"><span class="stt">-G</span></span> command-line flag. If no
|
||
|
|
environment variable or flag is specified, or if the value is not a
|
||
|
|
legal path name, then this directory defaults to an
|
||
|
|
<span class="stt">"etc"</span> directory relative to the current executable.
|
||
|
|
If the result of <span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">config-dir</span><span class="RktPn">)</span> is a
|
||
|
|
relative path, it is relative to the current executable.
|
||
|
|
The directory might not exist.</p></li><li><p><a name="(idx._(gentag._339._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">host-config-dir</span> —<wbr></wbr> like
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">config-dir</span>, but when cross-platform build mode has been
|
||
|
|
selected (through the <span class="nobreak"><span class="stt">-C</span></span> or <span class="nobreak"><span class="stt">--cross</span></span> argument to
|
||
|
|
<span class="stt">racket</span>; see <a href="running-sa.html#%28part._mz-cmdline%29" data-pltdoc="x">Command Line</a>), the result refers to a
|
||
|
|
directory for the current system’s installation, instead of for the
|
||
|
|
target system.</p></li><li><p><a name="(idx._(gentag._340._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">addon-dir</span> —<wbr></wbr> a directory for
|
||
|
|
user-specific Racket configuration, packages, and extension.
|
||
|
|
This directory is specified by the
|
||
|
|
<a name="(idx._(gentag._341._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">PLTADDONDIR</span> environment variable, and it can be
|
||
|
|
overridden by the <span class="nobreak"><span class="stt">--addon</span></span> or <span class="nobreak"><span class="stt">-A</span></span> command-line flag. If no
|
||
|
|
environment variable or flag is specified, or if the value is not a
|
||
|
|
legal path name, then this directory defaults to a platform-specific
|
||
|
|
locations. The directory might not exist.</p><p>On Unix, the default is normally the <span class="stt">"racket"</span> subdirectory
|
||
|
|
of the path specified by <a name="(idx._(gentag._342._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">XDG_DATA_HOME</span>, or
|
||
|
|
<span class="stt">".local/share/racket"</span> in the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a> if
|
||
|
|
<span class="stt">XDG_CONFIG_HOME</span> is not set to an absolute path or if
|
||
|
|
<span class="stt">PLTUSERHOME</span> is set. If that directory does not exists but a
|
||
|
|
<span class="stt">".racket"</span> directory exists in the user’s home directory,
|
||
|
|
that the <span class="stt">".racket"</span> directory path is the default, instead.</p><p>On Windows, the default is the same as the <span class="RktVal">'</span><span class="RktVal">pref-dir</span> directory.</p><p>On Mac OS, the default is <span class="stt">"Library/Racket"</span> within the
|
||
|
|
<a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a>.</p></li><li><p><a name="(idx._(gentag._343._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">cache-dir</span> —<wbr></wbr> a directory for storing
|
||
|
|
user-specific caches. The directory might not exist.</p><p>On Unix, the cache directory is normally the <span class="stt">"racket"</span>
|
||
|
|
subdirectory of the path specified by
|
||
|
|
<a name="(idx._(gentag._344._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">XDG_CACHE_HOME</span>, or <span class="stt">".cache/racket"</span> in the
|
||
|
|
<a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a> if <span class="stt">XDG_CACHE_HOME</span> is not set to
|
||
|
|
an absolute path or if <span class="stt">PLTUSERHOME</span> is set. If that directory
|
||
|
|
does not exist but a <span class="stt">".racket"</span> directory exists in the home
|
||
|
|
directory, then the <span class="stt">".racket"</span> directory is the cache
|
||
|
|
directory, instead.</p><p>On Windows, the cache directory is the same as the result returned
|
||
|
|
for <span class="RktVal">'</span><span class="RktVal">addon-dir</span>.</p><p>On Mac OS, the cache directory is <span class="stt">"Library/Caches/Racket"</span>
|
||
|
|
within the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a>.</p></li><li><p><a name="(idx._(gentag._345._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">doc-dir</span> —<wbr></wbr> the standard directory for
|
||
|
|
storing the current user’s documents. On Unix, it’s
|
||
|
|
the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a>. On Windows, it is the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s
|
||
|
|
home directory</span></a> if determined by <span class="stt">PLTUSERHOME</span>, otherwise it
|
||
|
|
is the user’s documents folder as specified by the Windows registry;
|
||
|
|
the documents folder is usually <span class="stt">"My Documents"</span> in the user’s
|
||
|
|
home directory. On Mac OS, it’s the <span class="stt">"Documents"</span> directory
|
||
|
|
in the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a>.</p></li><li><p><a name="(idx._(gentag._346._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">desk-dir</span> —<wbr></wbr> the directory for the current user’s
|
||
|
|
desktop. On Unix, it’s the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a>. On
|
||
|
|
Windows, it is the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a> if determined by
|
||
|
|
<span class="stt">PLTUSERHOME</span>, otherwise it is the user’s desktop folder as
|
||
|
|
specified by the Windows registry; the desktop folder is usually
|
||
|
|
<span class="stt">"Desktop"</span> in the user’s home directory. On Mac OS, it is
|
||
|
|
<span class="stt">"Desktop"</span> in the <a href="Filesystem.html#%28tech._user%27s._home._directory%29" class="techoutside" data-pltdoc="x"><span class="techinside">user’s home directory</span></a></p></li><li><p><a name="(idx._(gentag._347._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">sys-dir</span> —<wbr></wbr> the directory containing the
|
||
|
|
operating system for Windows. On Unix and Mac OS, the
|
||
|
|
result is <span class="RktVal">"/"</span>.</p></li><li><p><a name="(idx._(gentag._348._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">exec-file</span> —<wbr></wbr> the path of the Racket
|
||
|
|
executable as provided by the operating system for the current
|
||
|
|
invocation. For some operating systems, the path can be relative.</p><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>For GRacket, the executable path is the name of a GRacket
|
||
|
|
executable.</p></blockquote></blockquote></blockquote></li><li><p><a name="(idx._(gentag._349._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">run-file</span> —<wbr></wbr> the path of the current
|
||
|
|
executable; this may be different from result for
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">exec-file</span> because an alternate path was provided through a
|
||
|
|
<span class="nobreak"><span class="stt">--name</span></span> or <span class="nobreak"><span class="stt">-N</span></span> command-line flag to the Racket
|
||
|
|
(or GRacket) executable, or because an embedding executable
|
||
|
|
installed an alternate path. In particular a “launcher” script
|
||
|
|
created by <span class="RktSym"><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=raco&rel=exe.html%23%2528def._%2528%2528lib._launcher%252Flauncher..rkt%2529._make-racket-launcher%2529%2529&version=8.6" class="RktValLink Sq" data-pltdoc="x">make-racket-launcher</a></span> sets this path to the
|
||
|
|
script’s path.</p></li><li><p><a name="(idx._(gentag._350._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">collects-dir</span> —<wbr></wbr> a path to the main
|
||
|
|
collection of libraries (see <a href="collects.html" data-pltdoc="x">Libraries and Collections</a>). If this path is
|
||
|
|
relative, then it is relative to the executable as reported by
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">exec-file</span><span class="RktPn">)</span>—<wbr></wbr>though the latter could be a
|
||
|
|
soft-link or relative to the user’s executable search path, so that
|
||
|
|
the two results should be combined with
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._find-executable-path%29%29" class="RktValLink" data-pltdoc="x">find-executable-path</a></span>. The <span class="RktVal">'</span><span class="RktVal">collects-dir</span> path is
|
||
|
|
normally embedded in the Racket executable, but it can be
|
||
|
|
overridden by the <span class="nobreak"><span class="stt">--collects</span></span> or <span class="nobreak"><span class="stt">-X</span></span> command-line flag.</p></li><li><p><a name="(idx._(gentag._351._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">host-collects-dir</span> —<wbr></wbr> like
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">collects-dir</span>, but when cross-platform build mode has been
|
||
|
|
selected (through the <span class="nobreak"><span class="stt">-C</span></span> or <span class="nobreak"><span class="stt">--cross</span></span> argument to
|
||
|
|
<span class="stt">racket</span>; see <a href="running-sa.html#%28part._mz-cmdline%29" data-pltdoc="x">Command Line</a>), the result refers to a
|
||
|
|
directory for the current system’s installation, instead of for the
|
||
|
|
target system. In cross-platform build mode, collection
|
||
|
|
files are normally read from the target system’s installation,
|
||
|
|
but some tasks require current-system directories (such as
|
||
|
|
the one that holds foreign libraries) that are configured relative
|
||
|
|
to the main library-collection path.</p></li><li><p><a name="(idx._(gentag._352._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">orig-dir</span> —<wbr></wbr> the current directory at
|
||
|
|
start-up, which can be useful in converting a relative-path result
|
||
|
|
from <span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">exec-file</span><span class="RktPn">)</span> or
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">run-file</span><span class="RktPn">)</span> to a complete path.</p></li></ul><p class="SHistory">Changed in version 6.0.0.3 of package <span class="stt">base</span>: Added <span class="stt">PLTUSERHOME</span>.<br/>Changed in version 6.9.0.1: Added <span class="RktVal">'</span><span class="RktVal">host-config-dir</span>
|
||
|
|
and <span class="RktVal">'</span><span class="RktVal">host-collects-dir</span>.<br/>Changed in version 7.8.0.9: Added <span class="RktVal">'</span><span class="RktVal">cache-dir</span>, and changed
|
||
|
|
to use XDG directories as preferred on Unix
|
||
|
|
with the previous paths as a fallback, and
|
||
|
|
with similar adjustments for Mac OS.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/private/misc..rkt)._path-list-string-~3epath-list))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-list-string-~3epath-list%29%29" class="RktValDef RktValLink" data-pltdoc="x">path-list-string->path-list</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">str</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">default-path-list</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">same</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">str</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span><span class="hspace"> </span><span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._bytes~3f%29%29" class="RktValLink" data-pltdoc="x">bytes?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">default-path-list</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">same</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">Parses a string or byte string containing a list of paths, and returns
|
||
|
|
a list of paths. On Unix and Mac OS, paths in a path-list string are
|
||
|
|
separated by a <span class="RktInBG"><span class="hspace"></span><span class="RktIn">:</span><span class="hspace"></span></span>; on Windows, paths are separated by a
|
||
|
|
<span class="RktInBG"><span class="hspace"></span><span class="RktIn">;</span><span class="hspace"></span></span>, and all <span class="RktInBG"><span class="hspace"></span><span class="RktIn">"</span><span class="hspace"></span></span>s in the string are discarded. Whenever the path
|
||
|
|
list contains an empty path, the list
|
||
|
|
<span class="RktVar">default-path-list</span> is spliced into the returned list of
|
||
|
|
paths. Parts of <span class="RktVar">str</span> that do not form a valid path are not
|
||
|
|
included in the returned list. The given <span class="RktVar">str</span> must not contain
|
||
|
|
a nul character or nul byte.</div></p><p class="SHistory">Changed in version 8.0.0.10 of package <span class="stt">base</span>: Changed to allow <span class="RktVal">'</span><span class="RktVal">same</span> in
|
||
|
|
<span class="RktVar">default-path-list</span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/private/misc..rkt)._find-executable-path))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._find-executable-path%29%29" class="RktValDef RktValLink" data-pltdoc="x">find-executable-path</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">program</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktVar">related</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">deepest?</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="RktPn">)</span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">program</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">related</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">deepest?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></div><div class="SIntra
|
||
|
|
<span class="RktVal">#f</span> if the path cannot be found.</div></p><p>On Windows, if <span class="RktVar">program</span> is not found and it has no file
|
||
|
|
extension, then the search starts over with <span class="stt">".exe"</span> added to
|
||
|
|
<span class="RktVar">program</span>, and the result is <span class="RktVal">#f</span> only if the path with
|
||
|
|
<span class="stt">".exe"</span> also cannot be found. The result includes the
|
||
|
|
extension <span class="stt">".exe"</span> if only <span class="RktVar">program</span> with the extension
|
||
|
|
is found.</p><p>If <span class="RktVar">related</span> is not <span class="RktVal">#f</span>, then it must be a relative
|
||
|
|
path string, and the path found for <span class="RktVar">program</span> must be such
|
||
|
|
that the file or directory <span class="RktVar">related</span> exists in the same
|
||
|
|
directory as the executable. The result is then the full path for the
|
||
|
|
found <span class="RktVar">related</span>, instead of the path for the executable.</p><p>This procedure is used by the Racket executable to find the
|
||
|
|
standard library collection directory (see <a href="collects.html" data-pltdoc="x">Libraries and Collections</a>). In
|
||
|
|
this case, <span class="RktVar">program</span> is the name used to start Racket and
|
||
|
|
<span class="RktVar">related</span> is <span class="RktVal">"collects"</span>. The <span class="RktVar">related</span>
|
||
|
|
argument is used because, on Unix and Mac OS, <span class="RktVar">program</span> may
|
||
|
|
involve a sequence of soft links; in this case,
|
||
|
|
<span class="RktVar">related</span> determines which link in the chain is relevant.</p><p>If <span class="RktVar">related</span> is not <span class="RktVal">#f</span>, then when
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._find-executable-path%29%29" class="RktValLink" data-pltdoc="x">find-executable-path</a></span> does not find a <span class="RktVar">program</span>
|
||
|
|
that is a link to another file path, the search can continue with the
|
||
|
|
destination of the link. Further links are inspected until
|
||
|
|
<span class="RktVar">related</span> is found or the end of the chain of links is
|
||
|
|
reached. If <span class="RktVar">deepest?</span> is <span class="RktVal">#f</span> (the default), then the
|
||
|
|
result corresponds to the first path in a chain of links for which
|
||
|
|
<span class="RktVar">related</span> is found (and further links are not actually
|
||
|
|
explored); otherwise, the result corresponds to the last link in the
|
||
|
|
chain for which <span class="RktVar">related</span> is found.</p><p>If <span class="RktVar">program</span> is a pathless name,
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._find-executable-path%29%29" class="RktValLink" data-pltdoc="x">find-executable-path</a></span> gets the value of the
|
||
|
|
<a name="(idx._(gentag._353._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">PATH</span> environment variable; if this environment
|
||
|
|
variable is defined, <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._find-executable-path%29%29" class="RktValLink" data-pltdoc="x">find-executable-path</a></span> tries each path in
|
||
|
|
<span class="stt">PATH</span> as a prefix for <span class="RktVar">program</span> using the search
|
||
|
|
algorithm described above for path-containing
|
||
|
|
<span class="RktVar">program</span>s. If the <span class="stt">PATH</span> environment variable is
|
||
|
|
not defined, <span class="RktVar">program</span> is prefixed with the current
|
||
|
|
directory and used in the search algorithm above. (On Windows, the
|
||
|
|
current directory is always implicitly the first item in
|
||
|
|
<span class="stt">PATH</span>, so <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._find-executable-path%29%29" class="RktValLink" data-pltdoc="x">find-executable-path</a></span> checks the current
|
||
|
|
directory first on Windows.)</p><p class="SHistory">Changed in version 8.1.0.7 of package <span class="stt">base</span>: Added search with <span class="stt">".exe"</span>
|
||
|
|
on Windows.</p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""fileutils"">15.2.2<tt> </tt><a name="(part._fileutils)"></a>Files</h5><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._file-exists~3f))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-exists~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">file-exists?</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns <span class="RktVal">#t</span> if a file (not a directory) <span class="RktVar">path</span> exists,
|
||
|
|
<span class="RktVal">#f</span> otherwise.</div></p><p>On Windows, <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-exists~3f%29%29" class="RktValLink" data-pltdoc="x">file-exists?</a></span> reports <span class="RktVal">#t</span> for all
|
||
|
|
variations of the special filenames (e.g., <span class="RktVal">"LPT1"</span>,
|
||
|
|
<span class="RktVal">"x:/baddir/LPT1"</span>).</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._link-exists~3f))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._link-exists~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">link-exists?</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns <span class="RktVal">#t</span> if a link <span class="RktVar">path</span> exists,
|
||
|
|
<span class="RktVal">#f</span> otherwise.</div></p><p>The predicates <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-exists~3f%29%29" class="RktValLink" data-pltdoc="x">file-exists?</a></span> or <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._directory-exists~3f%29%29" class="RktValLink" data-pltdoc="x">directory-exists?</a></span>
|
||
|
|
work on the final destination of a link or series of links, while
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._link-exists~3f%29%29" class="RktValLink" data-pltdoc="x">link-exists?</a></span> only follows links to resolve the base part of
|
||
|
|
<span class="RktVar">path</span> (i.e., everything except the last name in the
|
||
|
|
path).</p><p>This procedure never raises the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span>
|
||
|
|
exception.</p><p>On Windows, <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._link-exists~3f%29%29" class="RktValLink" data-pltdoc="x">link-exists?</a></span> reports <span class="RktVal">#t</span> for both
|
||
|
|
symbolic links and junctions.</p><p class="SHistory">Changed in version 6.0.1.12 of package <span class="stt">base</span>: Added support for links on Windows.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._file-or-directory-type))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-type%29%29" class="RktValDef RktValLink" data-pltdoc="x">file-or-directory-type</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktVar">must-exist?</span><span class="RktOpt">]</span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">file</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">directory</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">link</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">directory-link</span><span class="hspace"> </span><span class="RktVal">#f</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">must-exist?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></div><div class="SIntrapara">Reports whether <span class="RktVar">path</span> refers to a file, directory, link, or
|
||
|
|
directory link (in the case of Windows; see also
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._make-file-or-directory-link%29%29" class="RktValLink" data-pltdoc="x">make-file-or-directory-link</a></span>), assuming that <span class="RktVar">path</span> can
|
||
|
|
be accessed.</div></p><p>If <span class="RktVar">path</span> cannot be accessed, the result is <span class="RktVal">#f</span> if
|
||
|
|
<span class="RktVar">must-exist?</span> is <span class="RktVal">#f</span>, otherwise the
|
||
|
|
<span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> exception is raised.</p><p class="SHistory">Added in version 7.8.0.5 of package <span class="stt">base</span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._delete-file))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._delete-file%29%29" class="RktValDef RktValLink" data-pltdoc="x">delete-file</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Deletes the file with path <span class="RktVar">path</span> if it exists, otherwise the
|
||
|
|
<span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> exception is raised. If <span class="RktVar">path</span> is a link, the link
|
||
|
|
is deleted rather than the destination of the link.</div></p><p>On Windows, if an initial attempt to delete the file fails with a
|
||
|
|
permission error and the value of
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-force-delete-permissions%29%29" class="RktValLink" data-pltdoc="x">current-force-delete-permissions</a></span> is true, then
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._delete-file%29%29" class="RktValLink" data-pltdoc="x">delete-file</a></span> attempts to change the file’s permissions (to
|
||
|
|
allow writes) and then delete the file; the permission change followed
|
||
|
|
by deletion is a non-atomic sequence, with no attempt to revert a
|
||
|
|
permission change if the deletion fails.</p><p>On Windows, <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._delete-file%29%29" class="RktValLink" data-pltdoc="x">delete-file</a></span> can delete a symbolic link, but not
|
||
|
|
a junction. Use <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._delete-directory%29%29" class="RktValLink" data-pltdoc="x">delete-directory</a></span> to delete a junction.</p><p>On Windows, beware that if a file is deleted while it remains in use
|
||
|
|
by some process (e.g., a background search indexer), then the file’s
|
||
|
|
content will eventually go away, but the file’s name remains occupied
|
||
|
|
until the file is no longer used. As long as the name remains
|
||
|
|
occupied, attempts to open, delete, or replace the file will trigger a
|
||
|
|
permission error (as opposed to a file-exists error). A common
|
||
|
|
technique to avoid this pitfall is to move the file to a generated
|
||
|
|
temporary name before deleting it. See also
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._delete-directory%2Ffiles%29%29" class="RktValLink" data-pltdoc="x">delete-directory/files</a></span>.</p><p class="SHistory">Changed in version 6.1.1.7 of package <span class="stt">base</span>: Changed Windows behavior to use
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-force-delete-permissions%29%29" class="RktValLink" data-pltdoc="x">current-force-delete-permissions</a></span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._rename-file-or-directory))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._rename-file-or-directory%29%29" class="RktValDef RktValLink" data-pltdoc="x">rename-file-or-directory</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">old</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">new</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktVar">exists-ok?</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">old</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">new</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">exists-ok?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></div><div class="SIntrapara">Renames the file or directory with path <span class="RktVar">old</span>—<wbr></wbr>if it
|
||
|
|
exists—<wbr></wbr>to the path <span class="RktVar">new</span>. If the file or directory is not
|
||
|
|
renamed successfully, the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> exception is raised.</div></p><p>This procedure can be used to move a file/directory to a different
|
||
|
|
directory (on the same filesystem) as well as rename a file/directory within
|
||
|
|
a directory. Unless <span class="RktVar">exists-ok?</span> is provided as a true value,
|
||
|
|
<span class="RktVar">new</span> cannot refer to an existing file or directory, but the
|
||
|
|
check is not atomic with the rename operation on Unix and Mac OS. Even if
|
||
|
|
<span class="RktVar">exists-ok?</span> is true, <span class="RktVar">new</span> cannot refer to an existing
|
||
|
|
file when <span class="RktVar">old</span> is a directory, and vice versa.</p><p>If <span class="RktVar">new</span> exists and is replaced, the replacement is atomic
|
||
|
|
on Unix and Mac OS, but it is not guaranteed to be atomic on
|
||
|
|
Windows. Furthermore, if <span class="RktVar">new</span> exists and is opened by any
|
||
|
|
process for reading or writing, then attempting to replace it will
|
||
|
|
typically fail on Windows. See also <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-atomic-output-file%29%29" class="RktValLink" data-pltdoc="x">call-with-atomic-output-file</a></span>.</p><p>If <span class="RktVar">old</span> is a link, the link is renamed rather than the
|
||
|
|
destination of the link, and it counts as a file for replacing any
|
||
|
|
existing <span class="RktVar">new</span>.</p><p>On Windows, beware that a directory cannot be renamed if any file
|
||
|
|
within the directory is open. That constraint is particularly
|
||
|
|
problematic if a search indexer is running in the background (as in
|
||
|
|
the default Windows configuration). A possible workaround is to
|
||
|
|
combine <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._copy-directory%2Ffiles%29%29" class="RktValLink" data-pltdoc="x">copy-directory/files</a></span> and
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._delete-directory%2Ffiles%29%29" class="RktValLink" data-pltdoc="x">delete-directory/files</a></span>, since the latter can deal with open
|
||
|
|
files, although that sequence is obviously not atomic and temporarily
|
||
|
|
duplicates files.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._file-or-directory-modify-seconds))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-modify-seconds%29%29" class="RktValDef RktValLink" data-pltdoc="x">file-or-directory-modify-seconds</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">path</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktVar">secs-n</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-integer?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">secs-n</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="prototype"><tr><td valign="top"><span class="RktPn">(</span><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-modify-seconds%29%29" class="RktValDef RktValLink" data-pltdoc="x">file-or-directory-modify-seconds</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">path</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">secs-n</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr></table></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">secs-n</span><span class="hspace"> </spa
|
||
|
|
the file or directory’s last modification date in seconds
|
||
|
|
since <a href="time.html#%28tech._the._epoch%29" class="techoutside" data-pltdoc="x"><span class="techinside">the epoch</span></a> (see also <a href="time.html" data-pltdoc="x">Time</a>) when
|
||
|
|
<span class="RktVar">secs-n</span> is not provided or is <span class="RktVal">#f</span>.</div></p><p>For FAT filesystems on Windows, directories do not have modification
|
||
|
|
dates. Therefore, the creation date is returned for a directory, but
|
||
|
|
the modification date is returned for a file.</p><p>If <span class="RktVar">secs-n</span> is provided and not <span class="RktVal">#f</span>, the access and
|
||
|
|
modification times of <span class="RktVar">path</span> are set to the given time.</p><p>On error (e.g., if no such file exists), then <span class="RktVar">fail-thunk</span> is
|
||
|
|
called (through a tail call) to produce the result of the
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-modify-seconds%29%29" class="RktValLink" data-pltdoc="x">file-or-directory-modify-seconds</a></span> call. If <span class="RktVar">fail-thunk</span> is
|
||
|
|
not provided, an error raises <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._file-or-directory-permissions))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-permissions%29%29" class="RktValDef RktValLink" data-pltdoc="x">file-or-directory-permissions</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktVar">mode</span><span class="RktOpt">]</span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">read</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">write</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">execute</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">mode</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-permissions%29%29" class="RktValDef RktValLink" data-pltdoc="x">file-or-directory-permissions</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktVar">mode</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29" class="RktValLink" data-pltdoc="x">integer-in</a></span><span class="hspace"> </span><span class="RktVal">0</span><span class="hspace"> </span><span class="RktVal">65535</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">mode</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktVal">'<
|
||
|
|
a list containing <a name="(idx._(gentag._356._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">read</span>, <a name="(idx._(gentag._357._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">write</span>,
|
||
|
|
and/or <a name="(idx._(gentag._358._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">execute</span> to indicate permission the given file
|
||
|
|
or directory path by the current user and group. On Unix and Mac OS,
|
||
|
|
permissions are checked for the current effective user instead of the
|
||
|
|
real user.</div></p><p>If <span class="RktVal">'</span><span class="RktVal">bits</span> is supplied as the second argument, the result is a
|
||
|
|
platform-specific integer encoding of the file or directory properties
|
||
|
|
(mostly permissions), and the result is independent of the current
|
||
|
|
user and group. The lowest nine bits of the encoding are somewhat
|
||
|
|
portable, reflecting permissions for the file or directory’s owner,
|
||
|
|
members of the file or directory’s group, or other users:</p><ul><li><p><span class="RktVal">#o400</span> : owner has read permission</p></li><li><p><span class="RktVal">#o200</span> : owner has write permission</p></li><li><p><span class="RktVal">#o100</span> : owner has execute permission</p></li><li><p><span class="RktVal">#o040</span> : group has read permission</p></li><li><p><span class="RktVal">#o020</span> : group has write permission</p></li><li><p><span class="RktVal">#o010</span> : group has execute permission</p></li><li><p><span class="RktVal">#o004</span> : others have read permission</p></li><li><p><span class="RktVal">#o002</span> : others have write permission</p></li><li><p><span class="RktVal">#o001</span> : others have execute permission</p></li></ul><p>See also <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._user-read-bit%29%29" class="RktValLink" data-pltdoc="x">user-read-bit</a></span>, etc. On Windows, permissions from
|
||
|
|
all three (owner, group, and others) are always the same, and read and
|
||
|
|
execute permission are always available. On Unix and Mac OS,
|
||
|
|
higher bits have a platform-specific meaning.</p><p>If an integer is supplied as the second argument, it is used as an
|
||
|
|
encoding of properties (mostly permissions) to install for the file.</p><p>In all modes, the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> exception is raised on error (e.g., if no
|
||
|
|
such file exists).</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._file-or-directory-stat))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-stat%29%29" class="RktValDef RktValLink" data-pltdoc="x">file-or-directory-stat</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktVar">as-link?</span><span class="RktOpt">]</span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fhash..rkt%29._hash%2Fc%29%29" class="RktValLink" data-pltdoc="x">hash/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="symbols.html#%28def._%28%28quote._~23~25kernel%29._symbol~3f%29%29" class="RktValLink" data-pltdoc="x">symbol?</a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktSym"><a href="hashtables.html#%28def._%28%28quote._~23~25kernel%29._hash-eq~3f%29%29" class="RktValLink" data-pltdoc="x">hash-eq?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">as-link?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></div><div class="SIntrapara"><a name="(idx._(gentag._359._(lib._scribblings/reference/reference..scrbl)))"></a>Returns a hash with the following keys and values,
|
||
|
|
where each value currently is a nonnegative exact integer:</div></p><ul><li><p><a name="(idx._(gentag._360._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">device-id</span> : device ID</p></li><li><p><a name="(idx._(gentag._361._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">inode</span> : inode number</p></li><li><p><a name="(idx._(gentag._362._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">mode</span> : mode bits (see below)</p></li><li><p><a name="(idx._(gentag._363._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">hardlink-count</span> : number of hard links</p></li><li><p><a name="(idx._(gentag._364._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">user-id</span> : numeric user ID of owner</p></li><li><p><a name="(idx._(gentag._365._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">group-id</span> : numeric group ID of owner</p></li><li><p><a name="(idx._(gentag._366._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">device-id-for-special-file</span> : device ID (if special file)</p></li><li><p><a name="(idx._(gentag._367._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">size</span> : size of file or symbolic link in bytes</p></li><li><p><a name="(idx._(gentag._368._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">block-size</span> : size of filesystem blocks</p></li><li><p><a name="(idx._(gentag._369._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">block-count</span> : number of used filesystem blocks</p></li><li><p><a name="(idx._(gentag._370._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">access-time-seconds</span> : last access time in seconds
|
||
|
|
since <a href="time.html#%28tech._the._epoch%29" class="techoutside" data-pltdoc="x"><span class="techinside">the epoch</span></a></p></li><li><p><a name="(idx._(gentag._371._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">modify-time-seconds</span> : last modification time in
|
||
|
|
seconds since <a href="time.html#%28tech._the._epoch%29" class="techoutside" data-pltdoc="x"><span class="techinside">the epoch</span></a></p></li><li><p><a name="(idx._(gentag._372._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">change-time-seconds</span> : last status change time in
|
||
|
|
seconds since <a href="time.html#%28tech._the._epoch%29" class="techoutside" data-pltdoc="x"><span class="techinside">the epoch</span></a></p></li><li><p><a name="(idx._(gentag._373._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">creation-time-seconds</span> : creation time in seconds since
|
||
|
|
<a href="time.html#%28tech._the._epoch%29" class="techoutside" data-pltdoc="x"><span class="techinside">the epoch</span></a></p></li><li><p><a name="(idx._(gentag._374._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">access-time-nanoseconds</span> : last access time in
|
||
|
|
nanoseconds since <a href="time.html#%28tech._the._epoch%29" class="techoutside" data-pltdoc="x"><span class="techinside">the epoch</span></a></p></li><li><p><a name="(idx._(gentag._375._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">modify-time-nanoseconds</span> : last modification time in
|
||
|
|
nanoseconds since <a href="time.html#%28tech._the._epoch%29" class="techoutside" data-pltdoc="x"><span class="techinside">the epoch</span></a></p></li><li><p><a name="(idx._(gentag._376._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">change-time-nanoseconds</span> : last status change time in
|
||
|
|
nanoseconds since <a href="time.html#%28tech._the._epoch%29" class="techoutside" data-pltdoc="x"><span class="techinside">the epoch</span></a></p></li><li><p><a name="(idx._(gentag._377._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktVal">'</span><span class="RktVal">creation-time-nanoseconds</span> : creation time in
|
||
|
|
nanoseconds since <a href="time.html#%28tech._the._epoch%29" class="techoutside" data-pltdoc="x"><span class="techinside">the epoch</span></a></p></li></ul><p>If <span class="RktVar">as-link?</span> is a true value, then if <span class="RktVar">path</span> refers to a
|
||
|
|
symbolic link, the stat information of the link is returned instead of the stat
|
||
|
|
information of the referenced filesystem item.</p><p>The mode bits are the bits for permissions and other data, as returned from the
|
||
|
|
Posix <span class="stt">stat</span>/<span class="stt">lstat</span> functions or the Windows <span class="stt">_wstat64</span> function,
|
||
|
|
respectively. To select portions of the bit pattern, use the constants
|
||
|
|
<a name="(idx._(gentag._378._(lib._scribblings/reference/reference..scrbl)))"></a><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._user-read-bit%29%29" class="RktValLink" data-pltdoc="x">user-read-bit</a></span>, etc.</p><p>Depending on the operating system and filesystem, the “nanoseconds”
|
||
|
|
timestamps may have less than nanoseconds precision. For example, in one
|
||
|
|
environment a timestamp may be <span class="RktVal">1234567891234567891</span> (nanoseconds
|
||
|
|
precision) and in another environment <span class="RktVal">1234567891000000000</span> (seconds
|
||
|
|
precision).</p><p>Values that aren’t available for a platform/filesystem combination may be set
|
||
|
|
to <span class="RktVal">0</span>. For example, this applies to the <span class="RktVal">'</span><span class="RktVal">user-id</span> and
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">group-id</span> keys on Windows. Also, Posix platforms provide the status
|
||
|
|
change timestamp, but not the creation timestamp; for Windows it’s the
|
||
|
|
opposite.</p><p>If <span class="RktVar">as-link?</span> is <span class="RktVal">#f</span> and <span class="RktVar">path</span> isn’t accessible,
|
||
|
|
the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> exception is raised. This exception is also raised if
|
||
|
|
<span class="RktVar">as-link?</span> is a true value and <span class="RktVar">path</span> can’t be resolved, i.e., is
|
||
|
|
a dangling link.</p><p class="SHistory">Added in version 8.3.0.7 of package <span class="stt">base</span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._file-or-directory-identity))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-identity%29%29" class="RktValDef RktValLink" data-pltdoc="x">file-or-directory-identity</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktVar">as-link?</span><span class="RktOpt">]</span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-positive-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-positive-integer?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">as-link?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></div><div class="SIntrapara"><a name="(idx._(gentag._379._(lib._scribblings/reference/reference..scrbl)))"></a>Returns a number that represents the identity of
|
||
|
|
<span class="RktVar">path</span> in terms of the device and file or directory that it
|
||
|
|
accesses. This function can be used to check whether two paths
|
||
|
|
correspond to the same filesystem entity under the assumption that the
|
||
|
|
path’s entity selection does not change.</div></p><p>If <span class="RktVar">as-link?</span> is a true value, then if <span class="RktVar">path</span> refers to
|
||
|
|
a filesystem link, the identity of the link is returned instead of the
|
||
|
|
identity of the referenced file or directory (if any).</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._file-size))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-size%29%29" class="RktValDef RktValLink" data-pltdoc="x">file-size</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._exact-nonnegative-integer~3f%29%29" class="RktValLink" data-pltdoc="x">exact-nonnegative-integer?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns the (logical) size of the specified file in bytes. On Mac
|
||
|
|
OS, this size excludes the resource-fork size. On error (e.g., if no
|
||
|
|
such file exists), the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> exception is raised.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._copy-file))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._copy-file%29%29" class="RktValDef RktValLink" data-pltdoc="x">copy-file</a></span></span><span class="hspace"> </span><span class="RktVar">src</span><span class="hspace"> </span><span class="RktVar">dest</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktVar">exists-ok?</span><span class="RktOpt">]</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">src</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">dest</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">exists-ok?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></div><div class="SIntrapara">Creates the file <span class="RktVar">dest</span> as a copy of <span class="RktVar">src</span>, if
|
||
|
|
<span class="RktVar">dest</span> does not already exist. If <span class="RktVar">dest</span> already exists
|
||
|
|
and <span class="RktVar">exists-ok?</span> is <span class="RktVal">#f</span>, the copy fails with
|
||
|
|
<span class="RktSym"><a href="exns.html#%28def._%28%28quote._~23~25kernel%29._exn~3afail~3afilesystem~3aexists~3f%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem:exists?</a></span> exception is raised; otherwise, if <span class="RktVar">dest</span>
|
||
|
|
exists, its content is replaced with the content of <span class="RktVar">src</span>. File
|
||
|
|
permissions are transferred from <span class="RktVar">src</span> to <span class="RktVar">dest</span>; on Windows,
|
||
|
|
the modification time of <span class="RktVar">src</span> is also transferred to <span class="RktVar">dest</span>. If
|
||
|
|
<span class="RktVar">src</span> refers to a link, the target of the link is copied,
|
||
|
|
rather than the link itself; if <span class="RktVar">dest</span> refers to a link and
|
||
|
|
<span class="RktVar">exists-ok?</span> is true, the target of the link is updated.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._make-file-or-directory-link))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._make-file-or-directory-link%29%29" class="RktValDef RktValLink" data-pltdoc="x">make-file-or-directory-link</a></span></span><span class="hspace"> </span><span class="RktVar">to</span><span class="hspace"> </span><span class="RktVar">path</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">to</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Creates a link <span class="RktVar">path</span> to <span class="RktVar">to</span>. The
|
||
|
|
creation will fail if <span class="RktVar">path</span> already exists. The <span class="RktVar">to</span>
|
||
|
|
need not refer to an existing file or directory, and <span class="RktVar">to</span> is
|
||
|
|
not expanded before writing the link. If the link is not created
|
||
|
|
successfully,the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> exception is raised.</div></p><p>On Windows XP and earlier, the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aunsupported%29%29" class="RktValLink" data-pltdoc="x">exn:fail:unsupported</a></span> exception is raised. On
|
||
|
|
later versions of Windows, the creation of links tends to be
|
||
|
|
disallowed by security policies. Windows distinguishes between file
|
||
|
|
and directory links, and a directory link is created only if
|
||
|
|
<span class="RktVar">to</span> parses syntactically as a directory (see
|
||
|
|
<span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path-~3edirectory-path%29%29" class="RktValLink" data-pltdoc="x">path->directory-path</a></span>). Furthermore, a relative-path link is
|
||
|
|
parsed specially by the operating system; see <a href="windowspaths.html" data-pltdoc="x">Windows Paths</a>
|
||
|
|
for more information. When <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._make-file-or-directory-link%29%29" class="RktValLink" data-pltdoc="x">make-file-or-directory-link</a></span>
|
||
|
|
succeeds, it creates a symbolic link as opposed to a junction or hard
|
||
|
|
link. Beware that directory links must be deleted using
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._delete-directory%29%29" class="RktValLink" data-pltdoc="x">delete-directory</a></span> instead of <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._delete-file%29%29" class="RktValLink" data-pltdoc="x">delete-file</a></span>.</p><p class="SHistory">Changed in version 6.0.1.12 of package <span class="stt">base</span>: Added support for links on Windows.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._current-force-delete-permissions))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-force-delete-permissions%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-force-delete-permissions</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-force-delete-permissions%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-force-delete-permissions</a></span></span><span class="hspace"> </span><span class="RktVar">any/c</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">any/c</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">A <a href="eval-model.html#%28tech._parameter%29" class="techoutside" data-pltdoc="x"><span class="techinside">parameter</span></a> that determines on Windows whether
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._delete-file%29%29" class="RktValLink" data-pltdoc="x">delete-file</a></span> and <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._delete-directory%29%29" class="RktValLink" data-pltdoc="x">delete-directory</a></span> attempt to change a
|
||
|
|
file or directory’s permissions to delete it. The default value is
|
||
|
|
<span class="RktVal">#t</span>.</div></p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""directories"">15.2.3<tt> </tt><a name="(part._directories)"></a>Directories</h5><p>See also: <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._rename-file-or-directory%29%29" class="RktValLink" data-pltdoc="x">rename-file-or-directory</a></span>,
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-modify-seconds%29%29" class="RktValLink" data-pltdoc="x">file-or-directory-modify-seconds</a></span>,
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-permissions%29%29" class="RktValLink" data-pltdoc="x">file-or-directory-permissions</a></span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._current-directory))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-directory</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._complete-path~3f%29%29" class="RktValLink" data-pltdoc="x">complete-path?</a></span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-directory</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">A <a href="eval-model.html#%28tech._parameter%29" class="techoutside" data-pltdoc="x"><span class="techinside">parameter</span></a> that determines the current directory for resolving
|
||
|
|
relative paths.</div></p><p>When the parameter procedure is called to set the current directory,
|
||
|
|
the path argument is <a href="pathutils.html#%28tech._cleanse%29" class="techoutside" data-pltdoc="x"><span class="techinside">cleanse</span></a>d using <span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._cleanse-path%29%29" class="RktValLink" data-pltdoc="x">cleanse-path</a></span>,
|
||
|
|
simplified using <span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._simplify-path%29%29" class="RktValLink" data-pltdoc="x">simplify-path</a></span>, and then converted to a
|
||
|
|
directory path with <span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path-~3edirectory-path%29%29" class="RktValLink" data-pltdoc="x">path->directory-path</a></span>; cleansing and
|
||
|
|
simplification raise an exception if the path is ill-formed. Thus, the
|
||
|
|
current value of <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span> is always a cleansed,
|
||
|
|
simplified, complete, directory path.</p><p>The path is not checked for existence when the parameter is set.</p><p>On Unix and Mac OS, the initial value of the parameter for a Racket
|
||
|
|
process is taken from the <a name="(idx._(gentag._380._(lib._scribblings/reference/reference..scrbl)))"></a><span class="stt">PWD</span> environment
|
||
|
|
variable—<wbr></wbr>if the value of the environment variable identifies the
|
||
|
|
same directory as the operating system’s report of the current
|
||
|
|
directory.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._current-directory-for-user))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory-for-user%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-directory-for-user</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._complete-path~3f%29%29" class="RktValLink" data-pltdoc="x">complete-path?</a></span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory-for-user%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-directory-for-user</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Like <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span>, but for use only by
|
||
|
|
<span class="RktSym"><a href="exns.html#%28def._%28%28quote._~23~25kernel%29._srcloc-~3estring%29%29" class="RktValLink" data-pltdoc="x">srcloc->string</a></span> for reporting paths relative to a
|
||
|
|
directory.</div></p><p>Normally, <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory-for-user%29%29" class="RktValLink" data-pltdoc="x">current-directory-for-user</a></span> should stay at its
|
||
|
|
initial value, reflecting the directory where a user started a
|
||
|
|
process. A tool such as DrRacket, however, implicitly lets a user
|
||
|
|
select a directory (for the file being edited), in which case updating
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory-for-user%29%29" class="RktValLink" data-pltdoc="x">current-directory-for-user</a></span> makes sense.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._current-drive))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-drive%29%29" class="RktValDef RktValLink" data-pltdoc="x">current-drive</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Returns the current drive name Windows. For other platforms, the
|
||
|
|
<span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aunsupported%29%29" class="RktValLink" data-pltdoc="x">exn:fail:unsupported</a></span> exception is raised. The current drive is always the drive
|
||
|
|
of the current directory.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._directory-exists~3f))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._directory-exists~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">directory-exists?</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns <span class="RktVal">#t</span> if <span class="RktVar">path</span> refers to a directory,
|
||
|
|
<span class="RktVal">#f</span> otherwise.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._make-directory))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._make-directory%29%29" class="RktValDef RktValLink" data-pltdoc="x">make-directory</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktVar">permissions</span><span class="RktOpt">]</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">permissions</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._integer-in%29%29" class="RktValLink" data-pltdoc="x">integer-in</a></span><span class="hspace"> </span><span class="RktVal">0</span><span class="hspace"> </span><span class="RktVal">65535</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#o777</span></td></tr></table></blockquote></div><div class="SIntrapara">Creates a new directory with the path <span class="RktVar">path</span>. If the directory
|
||
|
|
is not created successfully, the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> exception is raised.</div></p><p>The <span class="RktVar">permissions</span> argument specifies the permissions of the
|
||
|
|
created directory, where an integer representation of permissions is
|
||
|
|
treated the same as for <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-permissions%29%29" class="RktValLink" data-pltdoc="x">file-or-directory-permissions</a></span>. On
|
||
|
|
Unix and Mac OS, these permissions bits are combined with the
|
||
|
|
process’s umask. On Windows, <span class="RktVar">permissions</span> is not used.</p><p class="SHistory">Changed in version 8.3.0.5 of package <span class="stt">base</span>: Added the <span class="RktVar">permissions</span> argument.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._delete-directory))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._delete-directory%29%29" class="RktValDef RktValLink" data-pltdoc="x">delete-directory</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Deletes an existing directory with the path <span class="RktVar">path</span>. If the
|
||
|
|
directory is not deleted successfully, the
|
||
|
|
<span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> exception is raised.</div></p><p>On Windows, if an initial attempt to delete the directory fails with a
|
||
|
|
permission error and the value of <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-force-delete-permissions%29%29" class="RktValLink" data-pltdoc="x">current-force-delete-permissions</a></span>
|
||
|
|
is true, then <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._delete-file%29%29" class="RktValLink" data-pltdoc="x">delete-file</a></span> attempts to change the
|
||
|
|
directory’s permissions (to allow writes) and then delete the
|
||
|
|
directory; the permission change followed by deletion is a non-atomic
|
||
|
|
sequence, with no attempt to revert a permission change if the deletion
|
||
|
|
fails.</p><p class="SHistory">Changed in version 6.1.1.7 of package <span class="stt">base</span>: Changed Windows behavior to use
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-force-delete-permissions%29%29" class="RktValLink" data-pltdoc="x">current-force-delete-permissions</a></span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/private/base..rkt)._directory-list))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._directory-list%29%29" class="RktValDef RktValLink" data-pltdoc="x">directory-list</a></span></span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktPn">#:build?</span><span class="hspace"> </span><span class="RktVar">build?</span><span class="RktOpt">]</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">build?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></div><div class="SIntrapara"><blockquote class="refpara"><blockquote class="refcolumn"><blockquote class="refcontent"><p>See also the <span class="RktSym"><a href="sequences.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._in-directory%29%29" class="RktValLink" data-pltdoc="x">in-directory</a></span> sequence constructor.</p></blockquote></blockquote></blockquote></div></p><p>Returns a list of all files and directories in the directory specified
|
||
|
|
by <span class="RktVar">path</span>. If <span class="RktVar">build?</span> is <span class="RktVal">#f</span>, the resulting
|
||
|
|
paths are all <a href="More_Path_Utilities.html#%28tech._path._element%29" class="techoutside" data-pltdoc="x"><span class="techinside">path elements</span></a>; otherwise, the individual results
|
||
|
|
are combined with <span class="RktVar">path</span> using <span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._build-path%29%29" class="RktValLink" data-pltdoc="x">build-path</a></span>.
|
||
|
|
On Windows, an element of the result list may start with
|
||
|
|
<span class="RktInBG"><span class="hspace"></span><span class="RktIn">\\?\REL\\</span><span class="hspace"></span></span>.</p><p>The resulting paths are always sorted using <span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3c~3f%29%29" class="RktValLink" data-pltdoc="x">path<?</a></span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._filesystem-root-list))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._filesystem-root-list%29%29" class="RktValDef RktValLink" data-pltdoc="x">filesystem-root-list</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Returns a list of all current root directories. Obtaining this list
|
||
|
|
can be particularly slow on Windows.</div></p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""filesystem-change"">15.2.4<tt> </tt><a name="(part._filesystem-change)"></a>Detecting Filesystem Changes</h5><p>Many operating systems provide notifications for filesystem changes,
|
||
|
|
and those notifications are reflected in Racket by <a href="Filesystem.html#%28tech._filesystem._change._event%29" class="techoutside" data-pltdoc="x"><span class="techinside">filesystem
|
||
|
|
change events</span></a>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._filesystem-change-evt~3f))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._filesystem-change-evt~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">filesystem-change-evt?</a></span></span><span class="hspace"> </span><span class="RktVar">v</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="booleans.html#%28def._%28%28quote._~23~25kernel%29._boolean~3f%29%29" class="RktValLink" data-pltdoc="x">boolean?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">v</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Returns <span class="RktVal">#t</span> if <span class="RktVar">v</span> is a <a href="Filesystem.html#%28tech._filesystem._change._event%29" class="techoutside" data-pltdoc="x"><span class="techinside">filesystem change
|
||
|
|
event</span></a>, <span class="RktVal">#f</span> otherwise.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._filesystem-change-evt))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._filesystem-change-evt%29%29" class="RktValDef RktValLink" data-pltdoc="x">filesystem-change-evt</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktVar">failure-thunk</span><span class="RktOpt">]</span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._filesystem-change-evt~3f%29%29" class="RktValLink" data-pltdoc="x">filesystem-change-evt?</a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">failure-thunk</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">#f</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></div><div class="SIntrapara">Creates a <a name="(tech._filesystem._change._event)"></a><span style="font-style: italic">filesystem change event</span>, which is a
|
||
|
|
<a href="sync.html#%28tech._synchronizable._event%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronizable event</span></a> that becomes <a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for
|
||
|
|
synchronization</span></a> after a change to <span class="RktVar">path</span>:</div></p><ul><li><p>If <span class="RktVar">path</span> refers to a file, the event becomes
|
||
|
|
<a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for synchronization</span></a> when the file’s content or
|
||
|
|
attributes change, or when the file is deleted.</p></li><li><p>If <span class="RktVar">path</span> refers to a directory, the event becomes
|
||
|
|
<a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for synchronization</span></a> if a file or subdirectory is
|
||
|
|
added, renamed, or removed within the directory.</p></li></ul><p>The event also becomes <a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for synchronization</span></a> if
|
||
|
|
it is passed to <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._filesystem-change-evt-cancel%29%29" class="RktValLink" data-pltdoc="x">filesystem-change-evt-cancel</a></span>.</p><p>Finally, depending on the precision of information available from the
|
||
|
|
operating system, the event may become <a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for
|
||
|
|
synchronization</span></a> under other circumstances. For example, on
|
||
|
|
Windows, an event for a file becomes ready when any file changes
|
||
|
|
within in the same directory as the file.</p><p>After a <a href="Filesystem.html#%28tech._filesystem._change._event%29" class="techoutside" data-pltdoc="x"><span class="techinside">filesystem change event</span></a> becomes <a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for
|
||
|
|
synchronization</span></a>, it stays <a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for synchronization</span></a>. The
|
||
|
|
event’s <a href="sync.html#%28tech._synchronization._result%29" class="techoutside" data-pltdoc="x"><span class="techinside">synchronization result</span></a> is the event itself.</p><p>If the current platform does not support filesystem-change
|
||
|
|
notifications, then the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3aunsupported%29%29" class="RktValLink" data-pltdoc="x">exn:fail:unsupported</a></span> exception is raised if
|
||
|
|
<span class="RktVar">failure-thunk</span> is not provided as a procedure, or <span class="RktVar">failure-thunk</span> is
|
||
|
|
called in tail position if provided. Similarly, if there is any
|
||
|
|
operating-system error when creating the event (such as a non-existent
|
||
|
|
file), then the <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> exception is raised or <span class="RktVar">failure-thunk</span>
|
||
|
|
is called.</p><p>Creation of a filesystem change event allocates resources at the
|
||
|
|
operating-system level. The resources are released at latest when the
|
||
|
|
event is sychronized and <a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for synchronization</span></a>, when the
|
||
|
|
event is canceled with <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._filesystem-change-evt-cancel%29%29" class="RktValLink" data-pltdoc="x">filesystem-change-evt-cancel</a></span>, or when
|
||
|
|
the garbage collector determine that the filesystem change event is
|
||
|
|
unreachable. See also <span class="RktSym"><a href="runtime.html#%28def._%28%28quote._~23~25kernel%29._system-type%29%29" class="RktValLink" data-pltdoc="x">system-type</a></span> in <span class="RktVal">'</span><span class="RktVal">fs-change</span> mode.</p><p>A filesystem change event is placed under the management of the
|
||
|
|
<a href="eval-model.html#%28tech._current._custodian%29" class="techoutside" data-pltdoc="x"><span class="techinside">current custodian</span></a> when it is created. If the <a href="eval-model.html#%28tech._custodian%29" class="techoutside" data-pltdoc="x"><span class="techinside">custodian</span></a>
|
||
|
|
is shut down, <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._filesystem-change-evt-cancel%29%29" class="RktValLink" data-pltdoc="x">filesystem-change-evt-cancel</a></span> is applied to the
|
||
|
|
event.</p><p class="SHistory">Changed in version 7.3.0.8 of package <span class="stt">base</span>: Allow <span class="RktVal">#f</span> for <span class="RktVar">failure-thunk</span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((quote._~23~25kernel)._filesystem-change-evt-cancel))"></a><span title="Provided from: racket/base, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._filesystem-change-evt-cancel%29%29" class="RktValDef RktValLink" data-pltdoc="x">filesystem-change-evt-cancel</a></span></span><span class="hspace"> </span><span class="RktVar">evt</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">evt</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._filesystem-change-evt~3f%29%29" class="RktValLink" data-pltdoc="x">filesystem-change-evt?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Causes <span class="RktVar">evt</span> to become immediately <a href="sync.html#%28tech._ready._for._synchronization%29" class="techoutside" data-pltdoc="x"><span class="techinside">ready for
|
||
|
|
synchronization</span></a>, whether it was ready or not before, and releases the
|
||
|
|
resources (at the operating-system level) for tracking filesystem
|
||
|
|
changes.</div></p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""runtime-path"">15.2.5<tt> </tt><a name="(part._runtime-path)"></a><a name="(mod-path._racket/runtime-path)"></a>Declaring Paths Needed at Run Time</h5><p><div class="SIntrapara"><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span><span class="stt"> </span><a href="Filesystem.html#%28mod-path._racket%2Fruntime-path%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/runtime-path</span></a><span class="RktPn">)</span></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <a href="https://pkgs.racket-lang.org/package/base" title="Install this package using `raco pkg install base`"><span class="stt">base</span></a></span></td></tr></table></div><div class="SIntrapara">The bindings documented in this section are provided by the <a href="Filesystem.html#%28mod-path._racket%2Fruntime-path%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/runtime-path</span></a> library, not <a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/base</span></a> or <a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket</span></a>.</div></p><p>The <a href="Filesystem.html#%28mod-path._racket%2Fruntime-path%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/runtime-path</span></a> library provides forms for
|
||
|
|
accessing files and directories at run time using a path that are
|
||
|
|
usually relative to an enclosing source file. Unlike using
|
||
|
|
<span class="RktSym"><a href="collects.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._collection-path%29%29" class="RktValLink" data-pltdoc="x">collection-path</a></span>, <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span> exposes each
|
||
|
|
run-time path to tools like the executable and distribution creators,
|
||
|
|
so that files and directories needed at run time are carried along in
|
||
|
|
a distribution.</p><p>In addition to the bindings described below,
|
||
|
|
<a href="Filesystem.html#%28mod-path._racket%2Fruntime-path%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/runtime-path</span></a> provides <span class="RktSym"><a href="quote.html#%28form._%28%28quote._~23~25kernel%29._~23~25datum%29%29" class="RktStxLink" data-pltdoc="x">#%datum</a></span> in
|
||
|
|
<a href="syntax-model.html#%28tech._phase._level%29" class="techoutside" data-pltdoc="x"><span class="techinside">phase level</span></a> 1, since string constants are often used as
|
||
|
|
compile-time expressions with <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._racket/runtime-path..rkt)._define-runtime-path))"></a><span title="Provided from: racket/runtime-path | Package: base"><span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">define-runtime-path</a></span></span><span class="hspace"> </span><span class="RktVar">id</span><span class="hspace"> </span><span class="RktVar">maybe-runtime?-id</span><span class="hspace"> </span><span class="RktVar">expr</span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="stt"> </span></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="specgrammar"><tr><td align="right" valign="baseline"><span class="RktVar">maybe-runtime?-id</span></td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="center" valign="baseline">=</td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td></td></tr></table></td></tr><tr><td align="right" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="center" valign="baseline">|</td><td align="left" valign="baseline"><span class="stt"> </span></td><td align="left" valign="baseline"><span class="RktPn">#:runtime?-id</span><span class="hspace"> </span><span class="RktVar">runtime?-id</span></td></tr></table></td></tr></table></blockquote></div><div class="SIntrapara">Uses <span class="RktVar">expr</span> as both a compile-time (i.e., <a href="eval-model.html#%28tech._phase%29" class="techoutside" data-pltdoc="x"><span class="techinside">phase</span></a> 1)
|
||
|
|
expression and a run-time (i.e., <a href="eval-model.html#%28tech._phase%29" class="techoutside" data-pltdoc="x"><span class="techinside">phase</span></a> 0) expression. In either
|
||
|
|
context, <span class="RktVar">expr</span> should produce a path, a string that represents
|
||
|
|
a path, a list of the form <span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">lib</span><span class="stt"> </span><span class="RktVar">str</span><span class="stt"> </span><span class="RktMeta">...+</span><span class="RktPn">)</span>, or a list
|
||
|
|
of the form <span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">so</span><span class="stt"> </span><span class="RktVar">str</span><span class="RktPn">)</span> or <span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">so</span><span class="stt"> </span><span class="RktVar">str</span><span class="stt"> </span><span class="RktVar">vers</span><span class="RktPn">)</span>.
|
||
|
|
If <span class="RktVar">runtime?-id</span> is provided, then it is bound in the context
|
||
|
|
of <span class="RktVar">expr</span> to <span class="RktVal">#f</span> for the compile-time instance of
|
||
|
|
<span class="RktVar">expr</span> and <span class="RktVal">#t</span> for the run-time instance of <span class="RktVar">expr</span>.</div></p><p>For run time, <span class="RktVar">id</span> is bound to a path that is based on the
|
||
|
|
result of <span class="RktVar">expr</span>. The path is normally computed by taking a
|
||
|
|
relative path result from <span class="RktVar">expr</span> and adding it to a path for
|
||
|
|
the enclosing file (which is computed as described below). However,
|
||
|
|
tools like the executable creator can also arrange (by colluding with
|
||
|
|
<a href="Filesystem.html#%28mod-path._racket%2Fruntime-path%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/runtime-path</span></a>) to have a different base path
|
||
|
|
substituted in a generated executable. If <span class="RktVar">expr</span> produces an
|
||
|
|
absolute path, it is normally returned directly, but again may be
|
||
|
|
replaced by an executable creator. In all cases, the executable
|
||
|
|
creator preserves the relative locations of all paths within a given
|
||
|
|
<a href="collects.html#%28tech._package%29" class="techoutside" data-pltdoc="x"><span class="techinside">package</span></a> (treating paths outside of any package as being together).
|
||
|
|
When <span class="RktVar">expr</span> produces a relative or absolute path, then the path
|
||
|
|
bound to <span class="RktVar">id</span> is always an absolute path.</p><p>If <span class="RktVar">expr</span> produces a list of the form <span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">lib</span><span class="stt"> </span><span class="RktVar">str</span><span class="stt"> </span><span class="RktMeta">...+</span><span class="RktPn">)</span>, the value bound to <span class="RktVar">id</span> is an absolute path. The path
|
||
|
|
refers to a collection-based file similar to using the value as a
|
||
|
|
<a href="Module_Names_and_Loading.html#%28tech._module._path%29" class="techoutside" data-pltdoc="x"><span class="techinside">module path</span></a>.</p><p>If <span class="RktVar">expr</span> produces a list of the form <span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">so</span><span class="stt"> </span><span class="RktVar">str</span><span class="RktPn">)</span>
|
||
|
|
or <span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">so</span><span class="stt"> </span><span class="RktVar">str</span><span class="stt"> </span><span class="RktVar">vers</span><span class="RktPn">)</span>,
|
||
|
|
the value bound to <span class="RktVar">id</span> can be either <span class="RktVar">str</span> or an
|
||
|
|
absolute path; it is an absolute path when searching in the
|
||
|
|
Racket-specific shared-object library directories (as determined by
|
||
|
|
<span class="RktSym"><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=raco&rel=dirs.html%23%2528def._%2528%2528lib._setup%252Fdirs..rkt%2529._get-lib-search-dirs%2529%2529&version=8.6" class="RktValLink Sq" data-pltdoc="x">get-lib-search-dirs</a></span>) locates the path. In this way, shared-object
|
||
|
|
libraries that are installed specifically for Racket get carried
|
||
|
|
along in distributions. The search tries each directory in order;
|
||
|
|
within a directory, the search tries using <span class="RktVar">str</span> directly,
|
||
|
|
then it tries adding each version specified by <span class="RktVar">vers</span>—<wbr></wbr>which defaults
|
||
|
|
to <span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">#f</span><span class="RktVal">)</span>—<wbr></wbr>along with
|
||
|
|
a platform-specific shared-library extension—<wbr></wbr>as produced by
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="runtime.html#%28def._%28%28quote._~23~25kernel%29._system-type%29%29" class="RktValLink" data-pltdoc="x">system-type</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">so-suffix</span><span class="RktPn">)</span>. A <span class="RktVar">vers</span>
|
||
|
|
can be a string, or it can be a list of strings and <span class="RktVal">#f</span>.</p><p>If <span class="RktVar">expr</span> produces a list of the form <span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">share</span><span class="stt"> </span><span class="RktVar">str</span><span class="RktPn">)</span>, the value bound to <span class="RktVar">id</span> can be either <span class="RktVar">str</span> or
|
||
|
|
an absolute path; it is an absolute path when searching in the
|
||
|
|
directories reported by <span class="RktSym"><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=raco&rel=dirs.html%23%2528def._%2528%2528lib._setup%252Fdirs..rkt%2529._find-user-share-dir%2529%2529&version=8.6" class="RktValLink Sq" data-pltdoc="x">find-user-share-dir</a></span> and
|
||
|
|
<span class="RktSym"><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=raco&rel=dirs.html%23%2528def._%2528%2528lib._setup%252Fdirs..rkt%2529._find-share-dir%2529%2529&version=8.6" class="RktValLink Sq" data-pltdoc="x">find-share-dir</a></span> (in that order) locates the path. In this way,
|
||
|
|
files that are installed in Racket’s <span class="stt">"share"</span> directory get
|
||
|
|
carried along in distributions.</p><p>If <span class="RktVar">expr</span> produces a list of the form <span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">module</span><span class="stt"> </span><span class="RktVar">module-path</span><span class="stt"> </span><span class="RktVar">var-ref</span><span class="RktPn">)</span> or <span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">so</span><span class="stt"> </span><span class="RktVar">str</span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktVar">str-or-false</span><span class="stt"> </span><span class="RktMeta"><a href="stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29" class="RktStxLink" data-pltdoc="x">...</a></span><span class="RktPn">)</span><span class="RktPn">)</span>, the value bound to <span class="RktVar">id</span> is a
|
||
|
|
<a href="Module_Names_and_Loading.html#%28tech._module._path._index%29" class="techoutside" data-pltdoc="x"><span class="techinside">module path index</span></a>, where <span class="RktVar">module-path</span> is treated as
|
||
|
|
relative (if it is relative) to the module that is the home of the
|
||
|
|
<a href="Locations____variable-reference.html#%28tech._variable._reference%29" class="techoutside" data-pltdoc="x"><span class="techinside">variable reference</span></a> <span class="RktVar">var-ref</span>, where <span class="RktVar">var-ref</span>
|
||
|
|
can be <span class="RktVal">#f</span> if <span class="RktVar">module-path</span> is absolute. In an
|
||
|
|
executable, the corresponding module is carried along, including all
|
||
|
|
of its dependencies.</p><p>For compile-time, the <span class="RktVar">expr</span> result is used by an executable
|
||
|
|
creator—<wbr></wbr>but not the result when the containing module is
|
||
|
|
compiled. Instead, <span class="RktVar">expr</span> is preserved in the module as a
|
||
|
|
compile-time expression (in the sense of
|
||
|
|
<span class="RktSym"><a href="begin.html#%28form._%28%28quote._~23~25kernel%29._begin-for-syntax%29%29" class="RktStxLink" data-pltdoc="x">begin-for-syntax</a></span>). Later, at the time that an executable is
|
||
|
|
created, the compile-time portion of the module is executed (again),
|
||
|
|
and the result of <span class="RktVar">expr</span> is the file or directory to be included with the
|
||
|
|
executable. The reason for the extra compile-time execution is that
|
||
|
|
the result of <span class="RktVar">expr</span> might be platform-dependent, so the result
|
||
|
|
should not be stored in the (platform-independent) bytecode form of
|
||
|
|
the module; the platform at executable-creation time, however, is the
|
||
|
|
same as at run time for the executable. Note that <span class="RktVar">expr</span> is
|
||
|
|
still evaluated at run time; consequently, avoid procedures like
|
||
|
|
<span class="RktSym"><a href="collects.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._collection-path%29%29" class="RktValLink" data-pltdoc="x">collection-path</a></span>, which depends on the source installation,
|
||
|
|
and instead use relative paths and forms like <span class="RktPn">(</span><span class="RktSym"><a href="pairs.html#%28def._%28%28quote._~23~25kernel%29._list%29%29" class="RktValLink" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">lib</span><span class="stt"> </span><span class="RktVar">str</span><span class="stt"> </span><span class="RktMeta">...+</span><span class="RktPn">)</span>.</p><p>If a path is needed only on some platforms and not on others, use
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path-list%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path-list</a></span> with an <span class="RktVar">expr</span> that produces an
|
||
|
|
empty list on platforms where the path is not needed.</p><p>Beware that if <span class="RktVar">expr</span> produces the path of a directory when
|
||
|
|
creating an executable, the directory’s full content (including any
|
||
|
|
subdirectories) is included with the executable or eventual
|
||
|
|
distribution.</p><p>Also beware that <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span> in a <a href="syntax-model.html#%28tech._phase._level%29" class="techoutside" data-pltdoc="x"><span class="techinside">phase level</span></a> other
|
||
|
|
than 0 does not cooperate properly with an executable creator. To work
|
||
|
|
around that limitation, put <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span> in a separate
|
||
|
|
module—<wbr></wbr>perhaps a <a href="eval-model.html#%28tech._submodule%29" class="techoutside" data-pltdoc="x"><span class="techinside">submodule</span></a> created by <span class="RktSym"><a href="module.html#%28form._%28%28quote._~23~25kernel%29._module%29%29" class="RktStxLink" data-pltdoc="x">module</a></span>—<wbr></wbr>then
|
||
|
|
export the definition, and then the module containing the definition
|
||
|
|
can be <span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span>d into any phase level. Using
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span> in a <a href="syntax-model.html#%28tech._phase._level%29" class="techoutside" data-pltdoc="x"><span class="techinside">phase level</span></a> other than 0
|
||
|
|
logs a warning at expansion time.</p><p>The enclosing path for a <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span> is determined as
|
||
|
|
follows from the <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span> syntactic form:</p><ul><li><p>If the form has a source module according to
|
||
|
|
<span class="RktSym"><a href="stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-source-module%29%29" class="RktValLink" data-pltdoc="x">syntax-source-module</a></span>, then the source location is
|
||
|
|
determined by preserving the original expression as a syntax
|
||
|
|
object, extracting its source module path at run time (again
|
||
|
|
using <span class="RktSym"><a href="stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-source-module%29%29" class="RktValLink" data-pltdoc="x">syntax-source-module</a></span>), and then resolving the
|
||
|
|
resulting module path index. Note that <span class="RktSym"><a href="stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-source-module%29%29" class="RktValLink" data-pltdoc="x">syntax-source-module</a></span>
|
||
|
|
is based on a syntax object’s <a href="syntax-model.html#%28tech._lexical._information%29" class="techoutside" data-pltdoc="x"><span class="techinside">lexical information</span></a>, not its
|
||
|
|
source location.</p></li><li><p>If the expression has no source module, the
|
||
|
|
<span class="RktSym"><a href="stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-source%29%29" class="RktValLink" data-pltdoc="x">syntax-source</a></span> location associated with the form is
|
||
|
|
used, if is a string or path.</p></li><li><p>If no source module is available, and <span class="RktSym"><a href="stxops.html#%28def._%28%28quote._~23~25kernel%29._syntax-source%29%29" class="RktValLink" data-pltdoc="x">syntax-source</a></span>
|
||
|
|
produces no path, then <span class="RktSym"><a href="eval.html#%28def._%28%28quote._~23~25kernel%29._current-load-relative-directory%29%29" class="RktValLink" data-pltdoc="x">current-load-relative-directory</a></span>
|
||
|
|
is used if it is not <span class="RktVal">#f</span>. Finally,
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span> is used if all else fails.</p></li></ul><p>In the latter two cases, the path is normally preserved in
|
||
|
|
(platform-specific) byte form, but if the enclosing path corresponds to a
|
||
|
|
result of <span class="RktSym"><a href="collects.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._collection-file-path%29%29" class="RktValLink" data-pltdoc="x">collection-file-path</a></span>, then the path is record as
|
||
|
|
relative to the corresponding module path.</p><p class="SHistory">Changed in version 6.0.1.6 of package <span class="stt">base</span>: Preserve relative paths only within a package.<br/>Changed in version 7.5.0.7: Added support for <span class="RktVal">'</span><span class="RktVal">share</span> in <span class="RktVar">expr</span>.</p><p>Examples:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">Access a file </span><span class="stt">"data.txt"</span><span class="RktCmt"> at run-time that is originally</span></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">located in the same directory as the module source file:</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span><span class="hspace"> </span><span class="RktSym">data-file</span><span class="hspace"> </span><span class="RktVal">"data.txt"</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="define.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._define%29%29" class="RktStxLink" data-pltdoc="x">define</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">read-data</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="file-ports.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._with-input-from-file%29%29" class="RktValLink" data-pltdoc="x">with-input-from-file</a></span><span class="hspace"> </span><span class="RktSym">data-file</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-bytes%29%29" class="RktValLink" data-pltdoc="x">read-bytes</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-size%29%29" class="RktValLink" data-pltdoc="x">file-size</a></span><span class="hspace"> </span><span class="RktSym">data-file</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">Load a platform-specific shared object (using </span><span class="RktSym">ffi-lib</span><span class="RktCmt">)</span></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">that is located in a platform-specific sub-directory of the</span></td></tr><tr><td><span class="RktCmt">;</span><span class="RktCmt"> </span><span class="RktCmt">module</span><span class="RktCmt">'</span><span class="RktCmt">s source directory:</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span><span class="hspace"> </span><span class="RktSym">libfit-path</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._build-path%29%29" class="R
|
||
|
|
paths at once. The <span class="RktVar">expr</span> should produce as many values as
|
||
|
|
<span class="RktVar">id</span>s.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._racket/runtime-path..rkt)._define-runtime-path-list))"></a><span title="Provided from: racket/runtime-path | Package: base"><span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path-list%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">define-runtime-path-list</a></span></span><span class="hspace"> </span><span class="RktVar">id</span><span class="hspace"> </span><span class="RktVar">maybe-runtime?-id</span><span class="hspace"> </span><span class="RktVar">expr</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Like <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span>, but <span class="RktVar">expr</span> should produce a
|
||
|
|
list of paths.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._racket/runtime-path..rkt)._define-runtime-module-path-index))"></a><span title="Provided from: racket/runtime-path | Package: base"><span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-module-path-index%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">define-runtime-module-path-index</a></span></span><span class="hspace"> </span><span class="RktVar">id</span><span class="hspace"> </span><span class="RktVar">maybe-runtime?-id</span><span class="hspace"> </span><span class="RktVar">module-path-expr</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Similar to <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span>, but <span class="RktVar">id</span> is bound to a
|
||
|
|
<a href="Module_Names_and_Loading.html#%28tech._module._path._index%29" class="techoutside" data-pltdoc="x"><span class="techinside">module path index</span></a> that encapsulates the result of
|
||
|
|
<span class="RktVar">module-path-expr</span> relative to the enclosing module.</div></p><p>Use <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-module-path-index%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-module-path-index</a></span> to bind a module path that is
|
||
|
|
passed to a reflective function like <span class="RktSym"><a href="Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._dynamic-require%29%29" class="RktValLink" data-pltdoc="x">dynamic-require</a></span> while
|
||
|
|
also creating a module dependency for building and distributing
|
||
|
|
executables.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._racket/runtime-path..rkt)._runtime-require))"></a><span title="Provided from: racket/runtime-path | Package: base"><span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._runtime-require%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">runtime-require</a></span></span><span class="hspace"> </span><span class="RktVar">module-path</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Similar to <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-module-path-index%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-module-path-index</a></span>, but creates the
|
||
|
|
distribution dependency without binding a module path index. When
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._runtime-require%29%29" class="RktStxLink" data-pltdoc="x">runtime-require</a></span> is used multiple times within a module with
|
||
|
|
the same <span class="RktVar">module-path</span>, all but the first use expands to an
|
||
|
|
empty <span class="RktSym"><a href="begin.html#%28form._%28%28quote._~23~25kernel%29._begin%29%29" class="RktStxLink" data-pltdoc="x">begin</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._racket/runtime-path..rkt)._define-runtime-module-path))"></a><span title="Provided from: racket/runtime-path | Package: base"><span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-module-path%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">define-runtime-module-path</a></span></span><span class="hspace"> </span><span class="RktVar">id</span><span class="hspace"> </span><span class="RktVar">module-path</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Similar to <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-path</a></span>, but <span class="RktVar">id</span> is bound to a
|
||
|
|
<a href="Module_Names_and_Loading.html#%28tech._resolved._module._path%29" class="techoutside" data-pltdoc="x"><span class="techinside">resolved module path</span></a>. The <a href="Module_Names_and_Loading.html#%28tech._resolved._module._path%29" class="techoutside" data-pltdoc="x"><span class="techinside">resolved module path</span></a> for
|
||
|
|
<span class="RktVar">id</span> corresponds to <span class="RktVar">module-path</span> (with the same syntax
|
||
|
|
as a module path for <span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span>), which can be relative to the
|
||
|
|
enclosing module.</div></p><p>The <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-module-path-index%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-module-path-index</a></span> form is usually
|
||
|
|
preferred, because it creates a weaker link to the referenced module.
|
||
|
|
Unlike <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-module-path-index%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-module-path-index</a></span>, the
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-module-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-module-path</a></span> form creates a <span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._for-label%29%29" class="RktStxLink" data-pltdoc="x">for-label</a></span>
|
||
|
|
dependency from an enclosing module to <span class="RktVar">module-path</span>. Since the
|
||
|
|
dependency is merely <span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._for-label%29%29" class="RktStxLink" data-pltdoc="x">for-label</a></span>, <span class="RktVar">module-path</span> is not
|
||
|
|
<a href="eval-model.html#%28tech._instantiate%29" class="techoutside" data-pltdoc="x"><span class="techinside">instantiate</span></a>d or <a href="syntax-model.html#%28tech._visit%29" class="techoutside" data-pltdoc="x"><span class="techinside">visit</span></a>ed when the enclosing module is
|
||
|
|
<a href="eval-model.html#%28tech._instantiate%29" class="techoutside" data-pltdoc="x"><span class="techinside">instantiate</span></a>d or <a href="syntax-model.html#%28tech._visit%29" class="techoutside" data-pltdoc="x"><span class="techinside">visit</span></a>ed (unless such a dependency is
|
||
|
|
created by other <span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span>s), but the code for the referenced
|
||
|
|
module is loaded when the enclosing module is loaded.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._racket/runtime-path..rkt)._runtime-paths))"></a><span title="Provided from: racket/runtime-path | Package: base"><span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._runtime-paths%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">runtime-paths</a></span></span><span class="hspace"> </span><span class="RktVar">module-path</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">This form is mainly for use by tools such as executable builders. It
|
||
|
|
expands to a quoted list containing the run-time paths declared by
|
||
|
|
<span class="RktVar">module-path</span>, returning the compile-time results of the
|
||
|
|
declaration <span class="RktSym">expr</span>s, except that paths are converted to byte
|
||
|
|
strings. The enclosing module must require (directly or indirectly)
|
||
|
|
the module specified by <span class="RktVar">module-path</span>, which is an unquoted
|
||
|
|
module path. The resulting list does <span class="emph">not</span> include module paths
|
||
|
|
bound through <span class="RktSym"><a href="Filesystem.html#%28form._%28%28lib._racket%2Fruntime-path..rkt%29._define-runtime-module-path%29%29" class="RktStxLink" data-pltdoc="x">define-runtime-module-path</a></span>.</div></p><h5 x-source-module="(lib "scribblings/reference/reference.scrbl")" x-source-pkg="racket-doc" x-part-tag=""file-lib"">15.2.6<tt> </tt><a name="(part._file-lib)"></a><a name="(mod-path._racket/file)"></a>More File and Directory Utilities</h5><p><div class="SIntrapara"><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29" class="RktStxLink" data-pltdoc="x">require</a></span><span class="stt"> </span><a href="Filesystem.html#%28mod-path._racket%2Ffile%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/file</span></a><span class="RktPn">)</span></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <a href="https://pkgs.racket-lang.org/package/base" title="Install this package using `raco pkg install base`"><span class="stt">base</span></a></span></td></tr></table></div><div class="SIntrapara">The bindings documented in this section are provided by the <a href="Filesystem.html#%28mod-path._racket%2Ffile%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/file</span></a> and <a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket</span></a> libraries, but not <a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket/base</span></a>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._file-~3estring))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._file-~3estring%29%29" class="RktValDef RktValLink" data-pltdoc="x">file->string</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktPn">#:mode</span><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="RktOpt">]</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">text</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span></td></tr></table></blockquote></div><div class="SIntrapara">Reads all characters from <span class="RktVar">path</span> and returns them as a s
|
||
|
|
The <span class="RktVar">mode-flag</span> argument is the same as for
|
||
|
|
<span class="RktSym"><a href="file-ports.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-input-file%29%29" class="RktValLink" data-pltdoc="x">open-input-file</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._file-~3ebytes))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._file-~3ebytes%29%29" class="RktValDef RktValLink" data-pltdoc="x">file->bytes</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktPn">#:mode</span><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="RktOpt">]</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._bytes~3f%29%29" class="RktValLink" data-pltdoc="x">bytes?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">text</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span></td></tr></table></blockquote></div><div class="SIntrapara">Reads all characters from <span class="RktVar">path</span> and returns them as a
|
||
|
|
<a href="bytestrings.html#%28tech._byte._string%29" class="techoutside" data-pltdoc="x"><span class="techinside">byte string</span></a>. The <span class="RktVar">mode-flag</span> argument is the same as
|
||
|
|
for <span class="RktSym"><a href="file-ports.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-input-file%29%29" class="RktValLink" data-pltdoc="x">open-input-file</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._file-~3evalue))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._file-~3evalue%29%29" class="RktValDef RktValLink" data-pltdoc="x">file->value</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktPn">#:mode</span><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="RktOpt">]</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">text</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span></td></tr></table></blockquote></div><div class="SIntrapara">Reads a single S-expression from <span class="RktVar">path</span> using <span class="RktSym"><a href="Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29" class="RktValLink" data-pltdoc="x">read</a></span>.
|
||
|
|
The <span class="RktVar">mode-flag</span> argument is the same as for
|
||
|
|
<span class="RktSym"><a href="file-ports.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-input-file%29%29" class="RktValLink" data-pltdoc="x">open-input-file</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._file-~3elist))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._file-~3elist%29%29" class="RktValDef RktValLink" data-pltdoc="x">file->list</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span><span class="RktOpt">[</span><span class="RktVar">proc</span><span class="hspace"> </span><span class="RktPn">#:mode</span><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="RktOpt">]</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">proc</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._input-port~3f%29%29" class="RktValLink" data-pltdoc="x">input-port?</a></span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="RktPn"> .</span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktSym"><a href="Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29" class="RktValLink" data-pltdoc="x">read</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">text</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span></td></tr></table></blockquote></div><div class="SIntrapara">Repeatedly calls <span class="RktVar">proc</span> to consume the contents of
|
||
|
|
<span class="RktVar">path</span>, until <span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._eof%29%29" class="RktValLink" data-pltdoc="x">eof</a></span> is produced. The <span class="RktVar">mode-flag</span>
|
||
|
|
argument is the same as for <span class="RktSym"><a href="file-ports.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-input-file%29%29" class="RktValLink" data-pltdoc="x">open-input-file</a></span>. </div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._file-~3elines))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._file-~3elines%29%29" class="RktValDef RktValLink" data-pltdoc="x">file->lines</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">path</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:mode</span><span class="hspace"> </span><span class="RktVar">mode-flag</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:line-mode</span><span class="hspace"> </span><span class="RktVar">line-mode</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktSym"><a href="strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span><span class="RktPn">)</span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">text</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="argcontract"><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">line-mode</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">:</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span c
|
||
|
|
<span class="RktVar">line-mode</span> argument is the same as the second argument to
|
||
|
|
<span class="RktSym"><a href="Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-line%29%29" class="RktValLink" data-pltdoc="x">read-line</a></span>, but the default is <span class="RktVal">'</span><span class="RktVal">any</span> instead of
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">linefeed</span>. The <span class="RktVar">mode-flag</span> argument is the same as for
|
||
|
|
<span class="RktSym"><a href="file-ports.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-input-file%29%29" class="RktValLink" data-pltdoc="x">open-input-file</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._file-~3ebytes-lines))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._file-~3ebytes-lines%29%29" class="RktValDef RktValLink" data-pltdoc="x">file->bytes-lines</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">path</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:mode</span><span class="hspace"> </span><span class="RktVar">mode-flag</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:line-mode</span><span class="hspace"> </span><span class="RktVar">line-mode</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._bytes~3f%29%29" class="RktValLink" data-pltdoc="x">bytes?</a></span><span class="RktPn">)</span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">text</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="argcontract"><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">line-mode</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">:</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktP
|
||
|
|
lines like <span class="RktSym"><a href="Byte_and_String_Input.html#%28def._%28%28quote._~23~25kernel%29._read-bytes-line%29%29" class="RktValLink" data-pltdoc="x">read-bytes-line</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._display-to-file))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._display-to-file%29%29" class="RktValDef RktValLink" data-pltdoc="x">display-to-file</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">v</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">path</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:mode</span><span class="hspace"> </span><span class="RktVar">mode-flag</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:exists</span><span class="hspace"> </span><span class="RktVar">exists-flag</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">v</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">text</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class
|
||
|
|
<span class="RktVar">exists-flag</span> arguments are the same as for
|
||
|
|
<span class="RktSym"><a href="file-ports.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-output-file%29%29" class="RktValLink" data-pltdoc="x">open-output-file</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._write-to-file))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._write-to-file%29%29" class="RktValDef RktValLink" data-pltdoc="x">write-to-file</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">v</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">path</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:mode</span><span class="hspace"> </span><span class="RktVar">mode-flag</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:exists</span><span class="hspace"> </span><span class="RktVar">exists-flag</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">v</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">mode-flag</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">binary</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">text</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace">&n
|
||
|
|
<span class="RktVar">separator</span> after each element. The <span class="RktVar">mode-flag</span> and
|
||
|
|
<span class="RktVar">exists-flag</span> arguments are the same as for
|
||
|
|
<span class="RktSym"><a href="file-ports.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-output-file%29%29" class="RktValLink" data-pltdoc="x">open-output-file</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top" colspan="3"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._copy-directory/files))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._copy-directory%2Ffiles%29%29" class="RktValDef RktValLink" data-pltdoc="x">copy-directory/files</a></span></span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">src</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">dest</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:keep-modify-seconds?</span><span class="hspace"> </span><span class="RktVar">keep-modify-seconds?</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:preserve-links?</span><span class="hspace"> </span><span class="RktVar">preserve-links?</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">src</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">dest</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">keep-modify-seconds?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktVal">#f</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">preserve-links?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></div><div class="SIntrapara">Copies the file or directory <span class="RktVar">src</span> to <span class="RktVar">dest</span>, raising
|
||
|
|
<span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> if the file or directory cannot be
|
||
|
|
copied, possibly because <span class="RktVar">dest</span> exists already. If <span class="RktVar">src</span>
|
||
|
|
is a directory, the copy applies recursively to the directory’s
|
||
|
|
content. If a source is a link and <span class="RktVar">preserve-links?</span> is <span class="RktVal">#f</span>,
|
||
|
|
the target of the link is copied rather than the link itself; if
|
||
|
|
<span class="RktVar">preserve-links?</span> is <span class="RktVal">#t</span>, the link is copied.</div></p><p>If <span class="RktVar">keep-modify-seconds?</span> is <span class="RktVal">#f</span>, then file copies
|
||
|
|
keep only the properties kept by <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._copy-file%29%29" class="RktValLink" data-pltdoc="x">copy-file</a></span>. If
|
||
|
|
<span class="RktVar">keep-modify-seconds?</span> is true, then each file copy also keeps
|
||
|
|
the modification date of the original.</p><p class="SHistory">Changed in version 6.3 of package <span class="stt">base</span>: Added the <span class="RktPn">#:preserve-links?</span> argument.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._delete-directory/files))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._delete-directory%2Ffiles%29%29" class="RktValDef RktValLink" data-pltdoc="x">delete-directory/files</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">path</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:must-exist?</span><span class="hspace"> </span><span class="RktVar">must-exist?</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">must-exist?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktVal">#t</span></td></tr></table></blockquote></div><div class="SIntrapara">Deletes the file or directory specified by <span class="RktVar">path</span>, raising
|
||
|
|
<span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> if the file or directory cannot be
|
||
|
|
deleted. If <span class="RktVar">path</span> is a directory, then
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._delete-directory%2Ffiles%29%29" class="RktValLink" data-pltdoc="x">delete-directory/files</a></span> is first applied to each file and
|
||
|
|
directory in <span class="RktVar">path</span> before the directory is deleted.</div></p><p>If <span class="RktVar">must-exist?</span> is true, then <span class="RktSym"><a href="exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3afilesystem%29%29" class="RktValLink" data-pltdoc="x">exn:fail:filesystem</a></span> is
|
||
|
|
raised if <span class="RktVar">path</span> does not exist. If <span class="RktVar">must-exist?</span> is
|
||
|
|
false, then <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._delete-directory%2Ffiles%29%29" class="RktValLink" data-pltdoc="x">delete-directory/files</a></span> succeeds if <span class="RktVar">path</span>
|
||
|
|
does not exist (but a failure is possible if <span class="RktVar">path</span> initially
|
||
|
|
exists and is removed by another thread or process before
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._delete-directory%2Ffiles%29%29" class="RktValLink" data-pltdoc="x">delete-directory/files</a></span> deletes it).</p><p>On Windows, <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._delete-directory%2Ffiles%29%29" class="RktValLink" data-pltdoc="x">delete-directory/files</a></span> attempts to move a file
|
||
|
|
into the temporary-file directory before deleting it, which avoids
|
||
|
|
problems caused by deleting a file that is currently open (e.g., by a
|
||
|
|
search indexer running as a background process). If the move attempt
|
||
|
|
fails (e.g., because the temporary directory is on a different drive
|
||
|
|
than the file), then the file is deleted directly with
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._delete-file%29%29" class="RktValLink" data-pltdoc="x">delete-file</a></span>.</p><p class="SHistory">Changed in version 7.0 of package <span class="stt">base</span>: Added Windows-specific file deletion.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top" colspan="3"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._find-files))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._find-files%29%29" class="RktValDef RktValLink" data-pltdoc="x">find-files</a></span></span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">predicate</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktVar">start-path</span><span class="RktOpt">]</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:skip-filtered-directory?</span><span class="hspace"> </span><span class="RktVar">skip-filtered-directory?</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:follow-links?</span><span class="hspace"> </span><span class="RktVar">follow-links?</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">predicate</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="RktPn"> .</span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">start-path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </sp
|
||
|
|
list of all files and directories for which <span class="RktVar">predicate</span> returns
|
||
|
|
true. If <span class="RktVar">start-path</span> is <span class="RktVal">#f</span>, then the traversal starts
|
||
|
|
from <span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span><span class="RktPn">)</span>. In the resulting list, each
|
||
|
|
directory precedes its content.</div></p><p>The <span class="RktVar">predicate</span> procedure is called with a single argument for
|
||
|
|
each file or directory. If <span class="RktVar">start-path</span> is <span class="RktVal">#f</span>, the
|
||
|
|
argument is a pathname string that is relative to the current
|
||
|
|
directory. Otherwise, it is a path building on
|
||
|
|
<span class="RktVar">start-path</span>. Consequently, supplying
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span><span class="RktPn">)</span> for <span class="RktVar">start-path</span> is different from
|
||
|
|
supplying <span class="RktVal">#f</span>, because <span class="RktVar">predicate</span> receives complete
|
||
|
|
paths in the former case and relative paths in the latter. Another
|
||
|
|
difference is that <span class="RktVar">predicate</span> is not called for the current
|
||
|
|
directory when <span class="RktVar">start-path</span> is <span class="RktVal">#f</span>.</p><p>If <span class="RktVar">skip-filtered-directory?</span> is true, then when
|
||
|
|
<span class="RktVar">predicate</span> returns <span class="RktVal">#f</span> for a directory, the
|
||
|
|
directory’s content is not traversed.</p><p>If <span class="RktVar">follow-links?</span> is true, the <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._find-files%29%29" class="RktValLink" data-pltdoc="x">find-files</a></span> traversal
|
||
|
|
follows links, and links are not included in the result. If
|
||
|
|
<span class="RktVar">follow-links?</span> is <span class="RktVal">#f</span>, then links are not followed,
|
||
|
|
and links are included in the result.</p><p>If <span class="RktVar">start-path</span> does not refer to an existing file or
|
||
|
|
directory, then <span class="RktVar">predicate</span> will be called exactly once with
|
||
|
|
<span class="RktVar">start-path</span> as the argument.</p><p>The <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._find-files%29%29" class="RktValLink" data-pltdoc="x">find-files</a></span> procedure raises an exception if it encounters
|
||
|
|
a directory for which <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._directory-list%29%29" class="RktValLink" data-pltdoc="x">directory-list</a></span> fails.</p><p class="SHistory">Changed in version 6.3.0.11 of package <span class="stt">base</span>: Added the
|
||
|
|
<span class="RktPn">#:skip-filtered-directory?</span>
|
||
|
|
argument.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._pathlist-closure))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._pathlist-closure%29%29" class="RktValDef RktValLink" data-pltdoc="x">pathlist-closure</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">path-list</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:path-filter</span><span class="hspace"> </span><span class="RktVar">path-filter</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:follow-links?</span><span class="hspace"> </span><span class="RktVar">follow-links?</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path-list</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._listof%29%29" class="RktValLink" data-pltdoc="x">listof</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path-filter</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="RktPn"> .</span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%2Fc%29%29" class="RktValLink" data-pltdoc="x">any/c</a></span><span class="RktPn">)</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td><
|
||
|
|
directory, returns a list such that</div></p><ul><li><p>if a nested path is given, all of its ancestors are also
|
||
|
|
included in the result (but the same ancestor is not added
|
||
|
|
twice);</p></li><li><p>if a path refers to directory, all of its descendants are also
|
||
|
|
included in the result, except as omitted by <span class="RktVar">path-filter</span>;</p></li><li><p>ancestor directories appear before their descendants in the
|
||
|
|
result list, as long as they are not misordered in the given
|
||
|
|
<span class="RktVar">path-list</span>.</p></li></ul><p>If <span class="RktVar">path-filter</span> is a procedure, then it is applied to each
|
||
|
|
descendant of a directory. If <span class="RktVar">path-filter</span> returns
|
||
|
|
<span class="RktVal">#f</span>, then the descendant (and any of its descendants, in the
|
||
|
|
case of a subdirectory) are omitted from the result.</p><p>If <span class="RktVar">follow-links?</span> is true, then the traversal of directories
|
||
|
|
and files follows links, and the link paths are not included in the
|
||
|
|
result. If <span class="RktVar">follow-links?</span> is <span class="RktVal">#f</span>, then the result list
|
||
|
|
includes paths to link and the links are not followed.</p><p class="SHistory">Changed in version 6.3.0.11 of package <span class="stt">base</span>: Added the <span class="RktPn">#:path-filter</span> argument.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._fold-files))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._fold-files%29%29" class="RktValDef RktValLink" data-pltdoc="x">fold-files</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">proc</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">init-val</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktVar">start-path</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">follow-links?</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span></td></tr></table></blockquote></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="argcontract"><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">proc</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">:</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">file</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">dir</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">link</span><span class="RktPn">)</span><span class="hspace"> <
|
||
|
|
<span class="RktVar">proc</span> on each discovered file, directory, and link. If
|
||
|
|
<span class="RktVar">start-path</span> is <span class="RktVal">#f</span>, then the traversal starts from
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span><span class="RktPn">)</span>.</div></p><p>The <span class="RktVar">proc</span> procedure is called with three arguments for each
|
||
|
|
file, directory, or link:</p><ul><li><p>If <span class="RktVar">start-path</span> is <span class="RktVal">#f</span>, the first argument is a
|
||
|
|
pathname string that is relative to the current directory. Otherwise,
|
||
|
|
the first argument is a pathname that starts with
|
||
|
|
<span class="RktVar">start-path</span>. Consequently, supplying
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span><span class="RktPn">)</span> for <span class="RktVar">start-path</span> is different
|
||
|
|
from supplying <span class="RktVal">#f</span>, because <span class="RktVar">proc</span> receives complete
|
||
|
|
paths in the former case and relative paths in the latter. Another
|
||
|
|
difference is that <span class="RktVar">proc</span> is not called for the current
|
||
|
|
directory when <span class="RktVar">start-path</span> is <span class="RktVal">#f</span>.</p></li><li><p>The second argument is a symbol, either <span class="RktVal">'</span><span class="RktVal">file</span>,
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">dir</span>, or <span class="RktVal">'</span><span class="RktVal">link</span>. The second argument can be
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">link</span> when <span class="RktVar">follow-links?</span> is <span class="RktVal">#f</span>,
|
||
|
|
in which case the filesystem traversal does not follow links. If
|
||
|
|
<span class="RktVar">follow-links?</span> is <span class="RktVal">#t</span>, then <span class="RktVar">proc</span>
|
||
|
|
will only get a <span class="RktVal">'</span><span class="RktVal">link</span> as a second argument when it
|
||
|
|
encounters a dangling symbolic link (one that does not resolve to an
|
||
|
|
existing file or directory).</p></li><li><p>The third argument is the accumulated result. For the first
|
||
|
|
call to <span class="RktVar">proc</span>, the third argument is <span class="RktVar">init-val</span>. For the
|
||
|
|
second call to <span class="RktVar">proc</span> (if any), the third argument is the result
|
||
|
|
from the first call, and so on. The result of the last call to
|
||
|
|
<span class="RktVar">proc</span> is the result of <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._fold-files%29%29" class="RktValLink" data-pltdoc="x">fold-files</a></span>.</p></li></ul><p>The <span class="RktVar">proc</span> argument is used in an analogous way to the
|
||
|
|
procedure argument of <span class="RktSym"><a href="pairs.html#%28def._%28%28lib._racket%2Fprivate%2Flist..rkt%29._foldl%29%29" class="RktValLink" data-pltdoc="x">foldl</a></span>, where its result is used as the
|
||
|
|
new accumulated result. There is an exception for the case of a
|
||
|
|
directory (when the second argument is <span class="RktVal">'</span><span class="RktVal">dir</span>): in this case
|
||
|
|
the procedure may return two values, the second indicating whether the
|
||
|
|
recursive scan should include the given directory or not. If it
|
||
|
|
returns a single value, the directory is scanned. In the cases of
|
||
|
|
files or links (when the second argument is <span class="RktVal">'</span><span class="RktVal">file</span> or
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">link</span>), a second value is permitted but ignored.</p><p>If the <span class="RktVar">start-path</span> is provided but no such path exists, or if
|
||
|
|
paths disappear during the scan, then an exception is raised.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._make-directory*))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-directory%2A%29%29" class="RktValDef RktValLink" data-pltdoc="x">make-directory*</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Creates directory specified by <span class="RktVar">path</span>, creating intermediate
|
||
|
|
directories as necessary, and never failing if <span class="RktVar">path</span> exists
|
||
|
|
already.</div></p><p>If <span class="RktVar">path</span> is a relative path and the current directory does not
|
||
|
|
exist, then <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-directory%2A%29%29" class="RktValLink" data-pltdoc="x">make-directory*</a></span> will not create the current
|
||
|
|
directory, because it considers only explicit elements of
|
||
|
|
<span class="RktVar">path</span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._make-parent-directory*))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-parent-directory%2A%29%29" class="RktValDef RktValLink" data-pltdoc="x">make-parent-directory*</a></span></span><span class="hspace"> </span><span class="RktVar">path</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="void.html#%28def._%28%28quote._~23~25kernel%29._void~3f%29%29" class="RktValLink" data-pltdoc="x">void?</a></span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">path</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Creates the parent directory of the path specified by <span class="RktVar">path</span>,
|
||
|
|
creating intermediate directories as necessary, and never failing if
|
||
|
|
an ancestor of <span class="RktVar">path</span> exists already.</div></p><p>If <span class="RktVar">path</span> is a filesystem root or a relative path with a single
|
||
|
|
path element, then no directory is created. Like
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-directory%2A%29%29" class="RktValLink" data-pltdoc="x">make-directory*</a></span>, if <span class="RktVar">path</span> is a relative path and the
|
||
|
|
current directory does not exist, then <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-parent-directory%2A%29%29" class="RktValLink" data-pltdoc="x">make-parent-directory*</a></span>
|
||
|
|
will not create it.</p><p class="SHistory">Added in version 6.1.1.3 of package <span class="stt">base</span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._make-temporary-file))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-file%29%29" class="RktValDef RktValLink" data-pltdoc="x">make-temporary-file</a></span></span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktVar">template</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:copy-from</span><span class="hspace"> </span><span class="RktVar">copy-from</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:base-dir</span><span class="hspace"> </span><span class="RktVar">base-dir</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">compat-copy-from</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">compat-base-dir</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._complete-path~3f%29%29" class="RktValLink" data-pltdoc="x">complete-path?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">template</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">"rkttmp~a"</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">copy-from</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">dir
|
||
|
|
Instead of merely generating a fresh file name, the file is
|
||
|
|
actually created; this prevents other threads or processes from
|
||
|
|
picking the same temporary name.</div></p><p>The <span class="RktVar">template</span> argument must be a format string
|
||
|
|
suitable for use with <span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._format%29%29" class="RktValLink" data-pltdoc="x">format</a></span> and one additional
|
||
|
|
string argument (which will contain only digits). By
|
||
|
|
default, if <span class="RktVar">template</span> produces a relative path, it
|
||
|
|
is combined with the result of
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">temp-dir</span><span class="RktPn">)</span> using
|
||
|
|
<span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._build-path%29%29" class="RktValLink" data-pltdoc="x">build-path</a></span>; alternatively, <span class="RktVar">template</span> may
|
||
|
|
produce an absolute path, in which case
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">temp-dir</span><span class="RktPn">)</span> is not consulted. If
|
||
|
|
<span class="RktVar">base-dir</span> is provided and non-<span class="RktVal">#false</span>,
|
||
|
|
<span class="RktVar">template</span> must not produce a <a href="Manipulating_Paths.html#%28tech._complete%29" class="techoutside" data-pltdoc="x"><span class="techinside">complete</span></a> path,
|
||
|
|
and <span class="RktVar">base-dir</span> will be used instead of
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">temp-dir</span><span class="RktPn">)</span>. Using
|
||
|
|
<span class="RktVar">base-dir</span> is generally more reliable than including
|
||
|
|
directory components in <span class="RktVar">template</span>: it avoids subtle
|
||
|
|
bugs from manipulating paths as string and eleminates the
|
||
|
|
need to sanitize <span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._format%29%29" class="RktValLink" data-pltdoc="x">format</a></span> escape sequences.</p><p>On Windows, <span class="RktVar">template</span> may produce an absolute path
|
||
|
|
which is not a complete path (see <a href="windowspaths.html" data-pltdoc="x">Windows Paths</a>)
|
||
|
|
when <span class="RktVar">base-dir</span> is absent or <span class="RktVal">#f</span> (in which
|
||
|
|
case it will be resolved relative to
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29" class="RktValLink" data-pltdoc="x">current-directory</a></span><span class="RktPn">)</span>) or if <span class="RktVar">base-dir</span> is a
|
||
|
|
drive specification (in which case it will be used as with
|
||
|
|
<span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._build-path%29%29" class="RktValLink" data-pltdoc="x">build-path</a></span>). If <span class="RktVar">base-dir</span> is any other kind
|
||
|
|
of path, it is an error for <span class="RktVar">template</span> to produce an
|
||
|
|
absolute path.</p><p>When the <span class="RktVar">template</span> argument is not provided, if
|
||
|
|
there is source location information for the callsite of
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-file%29%29" class="RktValLink" data-pltdoc="x">make-temporary-file</a></span>, a template string is generated
|
||
|
|
based on the source location: the default is
|
||
|
|
<span class="RktVal">"rkttmp~a"</span> only when no source location information
|
||
|
|
is available (e.g<span class="Sendabbrev">.</span> if <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-file%29%29" class="RktValLink" data-pltdoc="x">make-temporary-file</a></span> is used
|
||
|
|
in a higher-order position).</p><p>If <span class="RktVar">copy-from</span> is provided as path, the temporary file
|
||
|
|
is created as a copy of the named file (using <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._copy-file%29%29" class="RktValLink" data-pltdoc="x">copy-file</a></span>). If
|
||
|
|
<span class="RktVar">copy-from</span> is <span class="RktVal">#f</span>, the temporary file is
|
||
|
|
created as empty. As a special case, for backwards compatibility,
|
||
|
|
if <span class="RktVar">copy-from</span> is <span class="RktVal">'</span><span class="RktVal">directory</span>,
|
||
|
|
then the temporary “file” is created as a directory:
|
||
|
|
for clarity, prefer <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-directory%29%29" class="RktValLink" data-pltdoc="x">make-temporary-directory</a></span> for creating
|
||
|
|
temporary directories.</p><p>When a temporary file is created, it is not opened for reading or
|
||
|
|
writing when the path is returned. The client program calling
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-file%29%29" class="RktValLink" data-pltdoc="x">make-temporary-file</a></span> is expected to open the file with the
|
||
|
|
desired access and flags (probably using the <span class="RktVal">'</span><span class="RktVal">truncate</span> flag;
|
||
|
|
see <span class="RktSym"><a href="file-ports.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._open-output-file%29%29" class="RktValLink" data-pltdoc="x">open-output-file</a></span>) and to delete it when it is no longer
|
||
|
|
needed.</p><p>The by-position arguments <span class="RktVar">compat-copy-from</span> and
|
||
|
|
<span class="RktVar">compat-base-dir</span> are for backwards compatibility:
|
||
|
|
if provided, they take precedence over the <span class="RktPn">#:copy-from</span> and
|
||
|
|
<span class="RktPn">#:base-dir</span> keyword variants.
|
||
|
|
Supplying by-position arguments prevents <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-file%29%29" class="RktValLink" data-pltdoc="x">make-temporary-file</a></span>
|
||
|
|
from generating a <span class="RktVar">template</span> using the source location.</p><p class="SHistory">Changed in version 8.4.0.3 of package <span class="stt">base</span>: Added the <span class="RktPn">#:copy-from</span> and <span class="RktPn">#:base-dir</span> arguments.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._make-temporary-directory))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-directory%29%29" class="RktValDef RktValLink" data-pltdoc="x">make-temporary-directory</a></span></span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktVar">template</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:base-dir</span><span class="hspace"> </span><span class="RktVar">base-dir</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._complete-path~3f%29%29" class="RktValLink" data-pltdoc="x">complete-path?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">template</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="strings.html#%28def._%28%28quote._~23~25kernel%29._string~3f%29%29" class="RktValLink" data-pltdoc="x">string?</a></span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">"rkttmp~a"</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">base-dir</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="RktPn">)</span><span class="hspace"> </span>=<span class="hspace"> </span><span class="RktVal">#f</span></td></tr></table></blockquote></div><div class="SIntrapara">Like <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-file%29%29" class="RktValLink" data-pltdoc="x">make-temporary-file</a></span>, but
|
||
|
|
creates a directory, rather than a regular file.</div></p><p>As with <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-file%29%29" class="RktValLink" data-pltdoc="x">make-temporary-file</a></span>, if the
|
||
|
|
<span class="RktVar">template</span> argument is not provided, a template
|
||
|
|
string is generated from the source location of the call to
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-directory%29%29" class="RktValLink" data-pltdoc="x">make-temporary-directory</a></span> when possible: the default
|
||
|
|
is <span class="RktVal">"rkttmp~a"</span> only when no source location
|
||
|
|
information is available.</p><p class="SHistory">Added in version 8.4.0.3 of package <span class="stt">base</span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><table cellspacing="0" cellpadding="0" class="together"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._make-temporary-file*))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-file%2A%29%29" class="RktValDef RktValLink" data-pltdoc="x">make-temporary-file*</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">prefix</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">suffix</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:copy-from</span><span class="hspace"> </span><span class="RktVar">copy-from</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:base-dir</span><span class="hspace"> </span><span class="RktVar">base-dir</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._and%2Fc%29%29" class="RktValLink" data-pltdoc="x">and/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._complete-path~3f%29%29" class="RktValLink" data-pltdoc="x">complete-path?</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">prefix</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._bytes~3f%29%29" class="RktValLink" data-pltdoc="x">bytes?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">suffix</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._bytes~3f%29%29" class="RktValLink" data-pltdoc="x">bytes?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">copy-from</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="RktPn">)</span><span class="hspace"> </s
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-directory%29%29" class="RktValLink" data-pltdoc="x">make-temporary-directory</a></span>, respectively, but, rather
|
||
|
|
than using a template for <span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._format%29%29" class="RktValLink" data-pltdoc="x">format</a></span>, the path is based
|
||
|
|
on <span class="RktPn">(</span><span class="RktSym"><a href="bytestrings.html#%28def._%28%28quote._~23~25kernel%29._bytes-append%29%29" class="RktValLink" data-pltdoc="x">bytes-append</a></span><span class="stt"> </span><span class="RktVar">prefix</span><span class="stt"> </span><span class="RktSym">generated</span><span class="stt"> </span><span class="RktVar">suffix</span><span class="RktPn">)</span>, where
|
||
|
|
<span class="RktSym">generated</span> is a byte string chosen by the
|
||
|
|
implementation to produce a unique path. If there is source
|
||
|
|
location information for the callsite of
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-file%2A%29%29" class="RktValLink" data-pltdoc="x">make-temporary-file*</a></span> or
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-temporary-directory%2A%29%29" class="RktValLink" data-pltdoc="x">make-temporary-directory*</a></span>, <span class="RktSym">generated</span> will
|
||
|
|
incorporate that information. The resulting path is combined
|
||
|
|
with <span class="RktVar">base-dir</span> as with <span class="RktSym">make-temorary-file</span>.</div></p><p class="SHistory">Added in version 8.4.0.3 of package <span class="stt">base</span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top" colspan="3"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._call-with-atomic-output-file))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-atomic-output-file%29%29" class="RktValDef RktValLink" data-pltdoc="x">call-with-atomic-output-file</a></span></span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">file</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">proc</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:security-guard</span><span class="hspace"> </span><span class="RktVar">security-guard</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:rename-fail-handler</span><span class="hspace"> </span><span class="RktVar">rename-fail-handler</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">file</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">proc</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">[</span><span class="RktSym">port</span><span class="hspace"> </span><span class="RktSym"><a href="port-ops.html#%28def._%28%28quote._~23~25kernel%29._output-port~3f%29%29" class="RktValLink" data-pltdoc="x">output-port?</a></span><span class="RktPn">]</span><span class="hspace"> </span><span class="RktPn">[</span><span class="RktSym">tmp-path</span><span class="hspace"> </span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path~3f%29%29" class="RktValLink" data-pltdoc="x">path?</a></span><span class="RktPn">]</span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="RktPn"> .</span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29
|
||
|
|
<span class="RktVar">file</span>, calls <span class="RktVar">proc</span> to write to the temporary file, and
|
||
|
|
then atomically (except on Windows) moves the temporary file in place of <span class="RktVar">file</span>.
|
||
|
|
The move simply uses <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._rename-file-or-directory%29%29" class="RktValLink" data-pltdoc="x">rename-file-or-directory</a></span> on Unix
|
||
|
|
and Mac OS, and it uses <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._rename-file-or-directory%29%29" class="RktValLink" data-pltdoc="x">rename-file-or-directory</a></span> on Windows
|
||
|
|
if <span class="RktVar">rename-fail-handler</span> is provided; otherwise, on Windows,
|
||
|
|
the moves uses an extra rename step (see below) on Windows
|
||
|
|
to avoid problems due to concurrent readers of <span class="RktVar">file</span>.</div></p><p>The <span class="RktVar">proc</span> function is called with an output port for the
|
||
|
|
temporary file, plus the path of the temporary file. The result of
|
||
|
|
<span class="RktVar">proc</span> is the result of <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-atomic-output-file%29%29" class="RktValLink" data-pltdoc="x">call-with-atomic-output-file</a></span>.</p><p>The <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-atomic-output-file%29%29" class="RktValLink" data-pltdoc="x">call-with-atomic-output-file</a></span> function arranges to delete
|
||
|
|
temporary files on exceptions.</p><p>Windows prevents programs from deleting or replacing files that are
|
||
|
|
open, but it allows renaming of open files. Therefore, on Windows,
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-atomic-output-file%29%29" class="RktValLink" data-pltdoc="x">call-with-atomic-output-file</a></span> by default creates a second
|
||
|
|
temporary file <span class="RktVar">extra-tmp-file</span>, renames <span class="RktVar">file</span> to
|
||
|
|
<span class="RktVar">extra-tmp-file</span>, renames the temporary file written by
|
||
|
|
<span class="RktVar">proc</span> to <span class="RktVar">file</span>, and finally deletes
|
||
|
|
<span class="RktVar">extra-tmp-file</span>. Since that process is not atomic, however,
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._rename-file-or-directory%29%29" class="RktValLink" data-pltdoc="x">rename-file-or-directory</a></span> is used if
|
||
|
|
<span class="RktVar">rename-fail-handler</span> is provided, where
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._rename-file-or-directory%29%29" class="RktValLink" data-pltdoc="x">rename-file-or-directory</a></span> has some chance of being atomic,
|
||
|
|
since that the source and destination of the moves will be in the same
|
||
|
|
directory; any filesystem exception while attempting to rename the
|
||
|
|
file is send to <span class="RktVar">rename-fail-handler</span>, which can
|
||
|
|
re-<span class="RktSym"><a href="exns.html#%28def._%28%28quote._~23~25kernel%29._raise%29%29" class="RktValLink" data-pltdoc="x">raise</a></span> the exception or simply return to try again, perhaps
|
||
|
|
after a delay. In addition to a filesystem exception, the
|
||
|
|
<span class="RktVar">rename-fail-handler</span> procedure also receives the temporary
|
||
|
|
file path to be moved to <span class="RktSym">path</span>. The
|
||
|
|
<span class="RktVar">rename-fail-handler</span> argument is used only on Windows.</p><p class="SHistory">Changed in version 7.1.0.6 of package <span class="stt">base</span>: Added the <span class="RktPn">#:rename-fail-handler</span> argument.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._get-preference))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._get-preference%29%29" class="RktValDef RktValLink" data-pltdoc="x">get-preference</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">name</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktVar">failure-thunk</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">flush-mode</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">filename</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:use-lock?</span><span class="hspace"> </span><span class="RktVar">use-lock?</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:timeout-lock-there</span><span class="hspace"> </span><span class="RktVar">timeout-lock-there</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:lock-there</span><span class="hspace"> </span><span class="RktVar">lock-there</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" c
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">pref-file</span><span class="RktPn">)</span>, or by <span class="RktVar">filename</span> if it
|
||
|
|
is provided and is not <span class="RktVal">#f</span>. In the former case, if the
|
||
|
|
preference file doesn’t exist, <span class="RktSym">get-preferences</span> attempts to
|
||
|
|
read an <a href="Filesystem.html#%28elem._old-prefs%29" data-pltdoc="x">old preferences file</a>, and then a
|
||
|
|
<span class="stt">"racket-prefs.rktd"</span> file in the configuration directory
|
||
|
|
(as reported by <span class="RktSym"><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=raco&rel=dirs.html%23%2528def._%2528%2528lib._setup%252Fdirs..rkt%2529._find-config-dir%2529%2529&version=8.6" class="RktValLink Sq" data-pltdoc="x">find-config-dir</a></span>), instead. If none of those
|
||
|
|
files exists, the preference set is empty.</div></p><p>The preference file should contain a list of symbol–value lists
|
||
|
|
written with the default parameter settings. Keys
|
||
|
|
starting with <span class="RktSym">racket:</span>, <span class="RktSym">mzscheme:</span>, <span class="RktSym">mred:</span>,
|
||
|
|
and <span class="RktSym">plt:</span> in any letter case are reserved for use by Racket
|
||
|
|
implementors. If the preference file does not contain a list
|
||
|
|
of symbol–value lists, an error is logged via <span class="RktSym"><a href="logging.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._log-error%29%29" class="RktStxLink" data-pltdoc="x">log-error</a></span>
|
||
|
|
and <span class="RktVar">failure-thunk</span> is called.</p><p>The result of <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._get-preference%29%29" class="RktValLink" data-pltdoc="x">get-preference</a></span> is the value associated with
|
||
|
|
<span class="RktVar">name</span> if it exists in the association list, or the result of
|
||
|
|
calling <span class="RktVar">failure-thunk</span> otherwise.</p><p>Preference settings are cached (weakly) across calls to
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._get-preference%29%29" class="RktValLink" data-pltdoc="x">get-preference</a></span>, using <span class="RktPn">(</span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._path-~3ecomplete-path%29%29" class="RktValLink" data-pltdoc="x">path->complete-path</a></span><span class="stt"> </span><span class="RktVar">filename</span><span class="RktPn">)</span>
|
||
|
|
as a cache key. If <span class="RktVar">flush-mode</span> is provided as <span class="RktVal">#f</span>, the
|
||
|
|
cache is used instead of re-consulting the preferences file. If
|
||
|
|
<span class="RktVar">flush-mode</span> is provided as <span class="RktVal">'</span><span class="RktVal">timestamp</span> (the default),
|
||
|
|
then the cache is used only if the file has a timestamp that is the
|
||
|
|
same as the last time the file was read. Otherwise, the file is
|
||
|
|
re-consulted.</p><p>On platforms for which <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._preferences-lock-file-mode%29%29" class="RktValLink" data-pltdoc="x">preferences-lock-file-mode</a></span> returns
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">file-lock</span> and when <span class="RktVar">use-lock?</span> is true,
|
||
|
|
preference-file reading is guarded by a lock; multiple readers can
|
||
|
|
share the lock, but writers take the lock exclusively. If the
|
||
|
|
preferences file cannot be read because the lock is unavailable,
|
||
|
|
<span class="RktVar">lock-there</span> is called on the path of the lock file; if
|
||
|
|
<span class="RktVar">lock-there</span> is <span class="RktVal">#f</span>, an exception is raised. The
|
||
|
|
default <span class="RktVar">lock-there</span> handler retries about 5 times (with
|
||
|
|
increasing delays between each attempt) before trying
|
||
|
|
<span class="RktVar">timeout-lock-there</span>, and the default <span class="RktVar">timeout-lock-there</span>
|
||
|
|
triggers an exception.</p><p>See also <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._put-preferences%29%29" class="RktValLink" data-pltdoc="x">put-preferences</a></span>. For a more elaborate preference
|
||
|
|
system, see <span class="RktSym"><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=framework&rel=Preferences__Textual.html%23%2528def._%2528%2528lib._framework%252Fpreferences..rkt%2529._preferences%7E3aget%2529%2529&version=8.6" class="RktValLink Sq" data-pltdoc="x">preferences:get</a></span>.</p><p><a name="(elem._old-prefs)"></a><span style="font-weight: bold">Old preferences files</span>: When a
|
||
|
|
<span class="RktVar">filename</span> is not provided and the file indicated by
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">pref-file</span><span class="RktPn">)</span> does not exist, the following
|
||
|
|
paths are checked for compatibility with old versions of Racket:</p><ul><li><p>Windows: <span class="RktPn">(</span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._build-path%29%29" class="RktValLink" data-pltdoc="x">build-path</a></span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">pref-dir</span><span class="RktPn">)</span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">up</span><span class="stt"> </span><span class="RktVal">"PLT Scheme"</span><span class="stt"> </span><span class="RktVal">"plt-prefs.ss"</span><span class="RktPn">)</span></p></li><li><p>Mac OS: <span class="RktPn">(</span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._build-path%29%29" class="RktValLink" data-pltdoc="x">build-path</a></span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">pref-dir</span><span class="RktPn">)</span><span class="stt"> </span><span class="RktVal">"org.plt-scheme.prefs.ss"</span><span class="RktPn">)</span></p></li><li><p>Unix: <span class="RktPn">(</span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28quote._~23~25kernel%29._expand-user-path%29%29" class="RktValLink" data-pltdoc="x">expand-user-path</a></span><span class="stt"> </span><span class="RktVal">"~/.plt-scheme/plt-prefs.ss"</span><span class="RktPn">)</span></p></li></ul><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._put-preferences))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._put-preferences%29%29" class="RktValDef RktValLink" data-pltdoc="x">put-preferences</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">names</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">vals</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktVar">locked-proc</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">filename</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top
|
||
|
|
the preference file designated by <span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._find-system-path%29%29" class="RktValLink" data-pltdoc="x">find-system-path</a></span><span class="stt"> </span><span class="RktVal">'</span><span class="RktVal">pref-file</span><span class="RktPn">)</span>, or <span class="RktVar">filename</span> if it is supplied and not
|
||
|
|
<span class="RktVal">#f</span>.</div></p><p>The <span class="RktVar">names</span> argument supplies the preference names, and
|
||
|
|
<span class="RktVar">vals</span> must have the same length as <span class="RktVar">names</span>. Each
|
||
|
|
element of <span class="RktVar">vals</span> must be an instance of a built-in data type
|
||
|
|
whose <span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._write%29%29" class="RktValLink" data-pltdoc="x">write</a></span> output is <span class="RktSym"><a href="Reading.html#%28def._%28%28quote._~23~25kernel%29._read%29%29" class="RktValLink" data-pltdoc="x">read</a></span>able (i.e., the
|
||
|
|
<span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._print-unreadable%29%29" class="RktValLink" data-pltdoc="x">print-unreadable</a></span> parameter is set to <span class="RktVal">#f</span> while
|
||
|
|
writing preferences).</p><p>Current preference values are read from the preference file before
|
||
|
|
updating, and a write lock is held starting before the file
|
||
|
|
read, and lasting until after the preferences file is updated. The
|
||
|
|
lock is implemented by the existence of a file in the same directory
|
||
|
|
as the preference file; see <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._preferences-lock-file-mode%29%29" class="RktValLink" data-pltdoc="x">preferences-lock-file-mode</a></span> for
|
||
|
|
more information. If the directory of the preferences file does
|
||
|
|
not already exist, it is created.</p><p>If the write lock is already held, then
|
||
|
|
<span class="RktVar">locked-proc</span> is called with a single argument: the path of the lock
|
||
|
|
file. The default <span class="RktVar">locked-proc</span> (used when the <span class="RktVar">locked-proc</span>
|
||
|
|
argument is <span class="RktVal">#f</span>) reports an error; an alternative
|
||
|
|
thunk might wait a while and try again, or give the user the choice to
|
||
|
|
delete the lock file (in case a previous update attempt encountered
|
||
|
|
disaster and locks are implemented by the presence of the lock file).</p><p>If <span class="RktVar">filename</span> is <span class="RktVal">#f</span> or not supplied, and the
|
||
|
|
preference file does not already exist, then values read from the
|
||
|
|
<span class="stt">"defaults"</span> collection (if any) are written for preferences
|
||
|
|
that are not mentioned in <span class="RktVar">names</span>.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._preferences-lock-file-mode))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._preferences-lock-file-mode%29%29" class="RktValDef RktValLink" data-pltdoc="x">preferences-lock-file-mode</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="data-structure-contracts.html#%28def._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._or%2Fc%29%29" class="RktValLink" data-pltdoc="x">or/c</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">exists</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">file-lock</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Reports the way that the lock file is used to implement
|
||
|
|
preference-file locking on the current platform.</div></p><p>The <span class="RktVal">'</span><span class="RktVal">exists</span> mode is currently used on all platforms except
|
||
|
|
Windows. In <span class="RktVal">'</span><span class="RktVal">exists</span> mode, the existence of the lock file
|
||
|
|
indicates that a write lock is held, and readers need no lock (because
|
||
|
|
the preferences file is atomically updated via
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._rename-file-or-directory%29%29" class="RktValLink" data-pltdoc="x">rename-file-or-directory</a></span>).</p><p>The <span class="RktVal">'</span><span class="RktVal">file-lock</span> mode is currently used on Windows. In
|
||
|
|
<span class="RktVal">'</span><span class="RktVal">file-lock</span> mode, shared and exclusive locks (in the sense of
|
||
|
|
<span class="RktSym"><a href="file-ports.html#%28def._%28%28quote._~23~25kernel%29._port-try-file-lock~3f%29%29" class="RktValLink" data-pltdoc="x">port-try-file-lock?</a></span>) on the lock file reflect reader and
|
||
|
|
writer locks on the preference-file content. (The preference file
|
||
|
|
itself is not locked, because a lock would interfere with replacing
|
||
|
|
the file via <span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._rename-file-or-directory%29%29" class="RktValLink" data-pltdoc="x">rename-file-or-directory</a></span>.)</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._make-handle-get-preference-locked))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-handle-get-preference-locked%29%29" class="RktValDef RktValLink" data-pltdoc="x">make-handle-get-preference-locked</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">delay</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">name</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktVar">failure-thunk</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">flush-mode</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">filename</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:lock-there</span><span class="hspace"> </span><span class="RktVar">lock-there</span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:max-delay</span><span class="hspace"> </span><span class="RktVar">max-delay</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Manipulating_Paths.html#%28def._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._path-string~3f%29%29" class="RktValLink" data-pltdoc="x">path-string?</a></span><span class="hspace"> </span><span class="RktPn">. </span><span class="RktSym"><a href="function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29" class="RktStxLink" data-pltdoc="x"><span class="nobreak">-></span></a></span><span class="RktPn"> .</span><span class="hspace"> </span><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">delay</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="number-types.html#%28def._%28%28quote._~23~25kernel%29._real~3f%29%29" class="RktValLink" data-pltdoc="x">real?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">name</span><span class="hspace"> </span>:<span class="hsp
|
||
|
|
argument to <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._get-preference%29%29" class="RktValLink" data-pltdoc="x">get-preference</a></span>, where the <span class="RktVar">name</span>,
|
||
|
|
<span class="RktVar">failure-thunk</span>, <span class="RktVar">flush-mode</span>, and <span class="RktVar">filename</span>
|
||
|
|
are all passed on to <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._get-preference%29%29" class="RktValLink" data-pltdoc="x">get-preference</a></span> by the result procedure
|
||
|
|
to retry the preferences lookup.</div></p><p>Before calling <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._get-preference%29%29" class="RktValLink" data-pltdoc="x">get-preference</a></span>, the result procedure uses
|
||
|
|
<span class="RktPn">(</span><span class="RktSym"><a href="threads.html#%28def._%28%28quote._~23~25kernel%29._sleep%29%29" class="RktValLink" data-pltdoc="x">sleep</a></span><span class="stt"> </span><span class="RktVar">delay</span><span class="RktPn">)</span> to pause. Then, if <span class="RktPn">(</span><span class="RktSym"><a href="generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._%2A%29%29" class="RktValLink" data-pltdoc="x">*</a></span><span class="stt"> </span><span class="RktVal">2</span><span class="stt"> </span><span class="RktVar">delay</span><span class="RktPn">)</span> is less
|
||
|
|
than <span class="RktVar">max-delay</span>, the result procedure calls
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-handle-get-preference-locked%29%29" class="RktValLink" data-pltdoc="x">make-handle-get-preference-locked</a></span> to generate a new retry
|
||
|
|
procedure to pass to <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._get-preference%29%29" class="RktValLink" data-pltdoc="x">get-preference</a></span>, but with a
|
||
|
|
<span class="RktVar">delay</span> of <span class="RktPn">(</span><span class="RktSym"><a href="generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._%2A%29%29" class="RktValLink" data-pltdoc="x">*</a></span><span class="stt"> </span><span class="RktVal">2</span><span class="stt"> </span><span class="RktVar">delay</span><span class="RktPn">)</span>. If <span class="RktPn">(</span><span class="RktSym"><a href="generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._%2A%29%29" class="RktValLink" data-pltdoc="x">*</a></span><span class="stt"> </span><span class="RktVal">2</span><span class="stt"> </span><span class="RktVar">delay</span><span class="RktPn">)</span> is not
|
||
|
|
less than <span class="RktVar">max-delay</span>, then <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._get-preference%29%29" class="RktValLink" data-pltdoc="x">get-preference</a></span> is called
|
||
|
|
with the given <span class="RktVar">lock-there</span>, instead.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><table cellspacing="0" cellpadding="0" class="prototype RForeground"><tr><td valign="top"><span class="RktPn">(</span><a name="(def._((lib._racket/file..rkt)._call-with-file-lock/timeout))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-file-lock%2Ftimeout%29%29" class="RktValDef RktValLink" data-pltdoc="x">call-with-file-lock/timeout</a></span></span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">filename</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">kind</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">thunk</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktVar">failure-thunk</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span><span class="RktOpt">[</span></td><td valign="top"><span class="RktPn">#:lock-file</span><span class="hspace"> </span><span class="RktVar">lock-file</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:delay</span><span class="hspace"> </span><span class="RktVar">delay</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td></tr><tr><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktPn">#:max-delay</span><span class="hspace"> </span><span class="RktVar">max-delay</span><span class="RktOpt">]</span><span class="RktPn">)</span></td><td valign="top"><span class="hspace"> </span></td><td valign="top">→</td><td valign="top"><span class="hspace"> </span></td><td valign="top"><span class="RktSym"><a href="data-structure-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fprivate%2Fmisc..rkt%29._any%29%29" class="RktStxLink" data-pltdoc="x">any</a></span></td></tr></table></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">filename</spa
|
||
|
|
<span class="RktVar">thunk</span>. The <span class="RktVar">filename</span> argument specifies a file path
|
||
|
|
prefix that is used only to generate the lock filename when
|
||
|
|
<span class="RktVar">lock-file</span> is <span class="RktVal">#f</span>. Specifically, when
|
||
|
|
<span class="RktVar">lock-file</span> is <span class="RktVal">#f</span>, then
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-file-lock%2Ftimeout%29%29" class="RktValLink" data-pltdoc="x">call-with-file-lock/timeout</a></span> uses <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-lock-file-name%29%29" class="RktValLink" data-pltdoc="x">make-lock-file-name</a></span>
|
||
|
|
to build the lock filename. If the lock file does not yet exist, it is
|
||
|
|
created; beware that the lock file is <span class="emph">not</span> deleted by
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-file-lock%2Ftimeout%29%29" class="RktValLink" data-pltdoc="x">call-with-file-lock/timeout</a></span>.</div></p><p>When <span class="RktVar">thunk</span> returns,
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-file-lock%2Ftimeout%29%29" class="RktValLink" data-pltdoc="x">call-with-file-lock/timeout</a></span> releases the lock, returning the result of
|
||
|
|
<span class="RktVar">thunk</span>. The <span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-file-lock%2Ftimeout%29%29" class="RktValLink" data-pltdoc="x">call-with-file-lock/timeout</a></span> function will retry
|
||
|
|
after <span class="RktVar">delay</span> seconds and continue retrying with exponential backoff
|
||
|
|
until delay reaches <span class="RktVar">max-delay</span>. If
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-file-lock%2Ftimeout%29%29" class="RktValLink" data-pltdoc="x">call-with-file-lock/timeout</a></span> fails to obtain the lock,
|
||
|
|
<span class="RktVar">failure-thunk</span> is called in tail position. The <span class="RktVar">kind</span> argument
|
||
|
|
specifies whether the lock is <span class="RktVal">'</span><span class="RktVal">shared</span> or <span class="RktVal">'</span><span class="RktVal">exclusive</span>
|
||
|
|
in the sense of <span class="RktSym"><a href="file-ports.html#%28def._%28%28quote._~23~25kernel%29._port-try-file-lock~3f%29%29" class="RktValLink" data-pltdoc="x">port-try-file-lock?</a></span>.</p><p><div class="SIntrapara">Examples:</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-file-lock%2Ftimeout%29%29" class="RktValLink" data-pltdoc="x">call-with-file-lock/timeout</a></span><span class="hspace"> </span><span class="RktSym">filename</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">exclusive</span></td></tr><tr><td><span class="hspace"> </span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._printf%29%29" class="RktValLink" data-pltdoc="x">printf</a></span><span class="hspace"> </span><span class="RktVal">"File is locked\n"</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Writing.html#%28def._%28%28quote._~23~25kernel%29._printf%29%29" class="RktValLink" data-pltdoc="x">printf</a></span><span class="hspace"> </span><span class="RktVal">"Failed to obtain lock for file\n"</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></td></tr><tr><td><p><span class="RktOut">File is locked</span></p></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-file-lock%2Ftimeout%29%29" class="RktValLink" data-pltdoc="x">call-with-file-lock/timeout</a></span><span class="hspace"> </span><span class="RktVal">#f</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">exclusive</span></td></tr><tr><td><span class="hspace"> </span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lambda</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._call-with-file-lock%2Ftimeout%29%29" class="RktValLink" data-pltdoc="x">call-with-file-lock/timeout</a></span><span class="hspace"> </span><span class="RktSym">filename</span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">shared</span></td></tr><tr><td><span class="hspace"> </span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="lambda.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._lambda%29%29" class="RktStxLink" data-pltdoc="x">lam
|
||
|
|
(i.e., when <span class="RktSym"><a href="https://download.racket-lang.org/releases/8.6/doc/local-redirect/index.html?doc=raco&rel=cross-system.html%23%2528def._%2528%2528lib._setup%252Fcross-system..rkt%2529._cross-system-type%2529%2529&version=8.6" class="RktValLink Sq" data-pltdoc="x">cross-system-type</a></span> reports <span class="RktVal">'</span><span class="RktVal">windows</span>) or
|
||
|
|
<span class="RktVal">".LOCK"</span> on other platforms to the file portion of the path.</div></p><p><div class="SIntrapara">Example:</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="stt">> </span><span class="RktPn">(</span><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._make-lock-file-name%29%29" class="RktValLink" data-pltdoc="x">make-lock-file-name</a></span><span class="hspace"> </span><span class="RktVal">"/home/george/project/important-file"</span><span class="RktPn">)</span></td></tr><tr><td><p><span class="RktRes">#<path:/home/george/project/.LOCKimportant-file></span></p></td></tr></table></blockquote></div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><table cellspacing="0" cellpadding="0" class="together"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>value</p></div></div><p class="RForeground"><a name="(def._((lib._racket/file..rkt)._file-type-bits))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._file-type-bits%29%29" class="RktValDef RktValLink" data-pltdoc="x">file-type-bits</a></span></span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktVal">#o170000</span></p></blockquote></td></tr></table></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="together"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>value</p></div></div><p class="RForeground"><a name="(def._((lib._racket/file..rkt)._socket-type-bits))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._socket-type-bits%29%29" class="RktValDef RktValLink" data-pltdoc="x">socket-type-bits</a></span></span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktVal">#o140000</span></p></blockquote></td></tr></table></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="together"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>value</p></div></div><p class="RForeground"><a name="(def._((lib._racket/file..rkt)._symbolic-link-type-bits))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._symbolic-link-type-bits%29%29" class="RktValDef RktValLink" data-pltdoc="x">symbolic-link-type-bits</a></span></span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktVal">#o120000</span></p></blockquote></td></tr></table></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="together"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>value</p></div></div><p class="RForeground"><a name="(def._((lib._racket/file..rkt)._regular-file-type-bits))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#%28def._%28%28lib._racket%2Ffile..rkt%29._regular-file-type-bits%29%29" class="RktValDef RktValLink" data-pltdoc="x">regular-file-type-bits</a></span></span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktVal">#o100000</span></p></blockquote></td></tr></table></td></tr><tr><td><table cellspacing="0" cellpadding="0" class="together"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>value</p></div></div><p class="RForeground"><a name="(def._((lib._racket/file..rkt)._block-device-type-bits))"></a><span title="Provided from: racket/file, racket | Package: base"><span class="RktSym"><a href="Filesystem.html#
|
||
|
|
<span class="RktSym"><a href="Filesystem.html#%28def._%28%28quote._~23~25kernel%29._file-or-directory-stat%29%29" class="RktValLink" data-pltdoc="x">file-or-directory-stat</a></span> and bitwise operations such as
|
||
|
|
<span class="RktSym"><a href="generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._bitwise-ior%29%29" class="RktValLink" data-pltdoc="x">bitwise-ior</a></span>, and <span class="RktSym"><a href="generic-numbers.html#%28def._%28%28quote._~23~25kernel%29._bitwise-and%29%29" class="RktValLink" data-pltdoc="x">bitwise-and</a></span>.</div></p><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" id="searchbox" type="text" tabindex="1" placeholder="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "8.6", "../");"/></form> <a href="https://docs.racket-lang.org/index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("8.6");">top</a><span class="tocsettoggle"> <a href="javascript:void(0);" title="show/hide table of contents" onclick="TocsetToggle();">contents</a></span></span><span class="navright"> <a href="windowspaths.html" title="backward to "15.1.4 Windows Paths"" data-pltdoc="x">← prev</a> <a href="os.html" title="up to "15 Operating System"" data-pltdoc="x">up</a> <a href="networking.html" title="forward to "15.3 Networking"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|