281 lines
18 KiB
HTML
281 lines
18 KiB
HTML
|
<!DOCTYPE html>
|
||
|
|
<html>
|
||
|
|
<!-- Created by GNU Texinfo 7.1, https://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<!-- This manual documents Guile version 3.0.10.
|
||
|
|
|
||
|
|
Copyright (C) 1996-1997, 2000-2005, 2009-2023 Free Software Foundation,
|
||
|
|
Inc.
|
||
|
|
|
||
|
|
Copyright (C) 2021 Maxime Devos
|
||
|
|
|
||
|
|
Copyright (C) 2024 Tomas Volf
|
||
|
|
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
|
|
any later version published by the Free Software Foundation; with no
|
||
|
|
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
|
||
|
|
copy of the license is included in the section entitled "GNU Free
|
||
|
|
Documentation License." -->
|
||
|
|
<title>File Ports (Guile Reference Manual)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="File Ports (Guile Reference Manual)">
|
||
|
|
<meta name="keywords" content="File Ports (Guile Reference Manual)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content=".texi2any-real">
|
||
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
||
|
|
|
||
|
|
<link href="index.html" rel="start" title="Top">
|
||
|
|
<link href="Concept-Index.html" rel="index" title="Concept Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Port-Types.html" rel="up" title="Port Types">
|
||
|
|
<link href="Bytevector-Ports.html" rel="next" title="Bytevector Ports">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
span:hover a.copiable-link {visibility: visible}
|
||
|
|
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
<link rel="stylesheet" type="text/css" href="https://www.gnu.org/software/gnulib/manual.css">
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<div class="subsubsection-level-extent" id="File-Ports">
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Bytevector-Ports.html" accesskey="n" rel="next">Bytevector Ports</a>, Up: <a href="Port-Types.html" accesskey="u" rel="up">Types of Port</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<h4 class="subsubsection" id="File-Ports-1"><span>6.12.10.1 File Ports<a class="copiable-link" href="#File-Ports-1"> ¶</a></span></h4>
|
||
|
|
<a class="index-entry-id" id="index-File-port"></a>
|
||
|
|
<a class="index-entry-id" id="index-Port_002c-file"></a>
|
||
|
|
|
||
|
|
<p>The following procedures are used to open file ports.
|
||
|
|
See also <a class="ref" href="Ports-and-File-Descriptors.html">open</a>, for an interface
|
||
|
|
to the Unix <code class="code">open</code> system call.
|
||
|
|
</p>
|
||
|
|
<p>All file access uses the “LFS” large file support functions when
|
||
|
|
available, so files bigger than 2 gibibytes (<em class="math">2^31</em> bytes) can be
|
||
|
|
read and written on a 32-bit system.
|
||
|
|
</p>
|
||
|
|
<p>Most systems have limits on how many files can be open, so it’s
|
||
|
|
strongly recommended that file ports be closed explicitly when no
|
||
|
|
longer required (see <a class="pxref" href="Ports.html">Ports</a>).
|
||
|
|
</p>
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-open_002dfile"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">open-file</strong> <var class="def-var-arguments">filename mode [#:guess-encoding=#f] [#:encoding=#f]</var><a class="copiable-link" href="#index-open_002dfile"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-scm_005fopen_005ffile_005fwith_005fencoding"><span class="category-def">C Function: </span><span><strong class="def-name">scm_open_file_with_encoding</strong> <var class="def-var-arguments">(filename, mode, guess_encoding, encoding)</var><a class="copiable-link" href="#index-scm_005fopen_005ffile_005fwith_005fencoding"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-scm_005fopen_005ffile"><span class="category-def">C Function: </span><span><strong class="def-name">scm_open_file</strong> <var class="def-var-arguments">(filename, mode)</var><a class="copiable-link" href="#index-scm_005fopen_005ffile"> ¶</a></span></dt>
|
||
|
|
<dd><p>Open the file whose name is <var class="var">filename</var>, and return a port
|
||
|
|
representing that file. The attributes of the port are
|
||
|
|
determined by the <var class="var">mode</var> string. The way in which this is
|
||
|
|
interpreted is similar to C stdio. The first character must be
|
||
|
|
one of the following:
|
||
|
|
</p>
|
||
|
|
<dl class="table">
|
||
|
|
<dt>‘<samp class="samp">r</samp>’</dt>
|
||
|
|
<dd><p>Open an existing file for input.
|
||
|
|
</p></dd>
|
||
|
|
<dt>‘<samp class="samp">w</samp>’</dt>
|
||
|
|
<dd><p>Open a file for output, creating it if it doesn’t already exist
|
||
|
|
or removing its contents if it does.
|
||
|
|
</p></dd>
|
||
|
|
<dt>‘<samp class="samp">a</samp>’</dt>
|
||
|
|
<dd><p>Open a file for output, creating it if it doesn’t already
|
||
|
|
exist. All writes to the port will go to the end of the file.
|
||
|
|
The "append mode" can be turned off while the port is in use
|
||
|
|
see <a class="pxref" href="Ports-and-File-Descriptors.html">fcntl</a>
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>The following additional characters can be appended:
|
||
|
|
</p>
|
||
|
|
<dl class="table">
|
||
|
|
<dt>‘<samp class="samp">b</samp>’</dt>
|
||
|
|
<dd><p>Open the underlying file in binary mode, if supported by the system.
|
||
|
|
Also, open the file using the binary-compatible character encoding
|
||
|
|
"ISO-8859-1", ignoring the default port encoding.
|
||
|
|
</p></dd>
|
||
|
|
<dt>‘<samp class="samp">+</samp>’</dt>
|
||
|
|
<dd><p>Open the port for both input and output. E.g., <code class="code">r+</code>: open
|
||
|
|
an existing file for both input and output.
|
||
|
|
</p></dd>
|
||
|
|
<dt>‘<samp class="samp">e</samp>’</dt>
|
||
|
|
<dd><p>Mark the underlying file descriptor as close-on-exec, as per the
|
||
|
|
<code class="code">O_CLOEXEC</code> flag.
|
||
|
|
</p></dd>
|
||
|
|
<dt>‘<samp class="samp">0</samp>’</dt>
|
||
|
|
<dd><p>Create an "unbuffered" port. In this case input and output
|
||
|
|
operations are passed directly to the underlying port
|
||
|
|
implementation without additional buffering. This is likely to
|
||
|
|
slow down I/O operations. The buffering mode can be changed
|
||
|
|
while a port is in use (see <a class="pxref" href="Buffering.html">Buffering</a>).
|
||
|
|
</p></dd>
|
||
|
|
<dt>‘<samp class="samp">l</samp>’</dt>
|
||
|
|
<dd><p>Add line-buffering to the port. The port output buffer will be
|
||
|
|
automatically flushed whenever a newline character is written.
|
||
|
|
</p></dd>
|
||
|
|
<dt>‘<samp class="samp">b</samp>’</dt>
|
||
|
|
<dd><p>Use binary mode, ensuring that each byte in the file will be read as one
|
||
|
|
Scheme character.
|
||
|
|
</p>
|
||
|
|
<p>To provide this property, the file will be opened with the 8-bit
|
||
|
|
character encoding "ISO-8859-1", ignoring the default port encoding.
|
||
|
|
See <a class="xref" href="Ports.html">Ports</a>, for more information on port encodings.
|
||
|
|
</p>
|
||
|
|
<p>Note that while it is possible to read and write binary data as
|
||
|
|
characters or strings, it is usually better to treat bytes as octets,
|
||
|
|
and byte sequences as bytevectors. See <a class="xref" href="Binary-I_002fO.html">Binary I/O</a>, for more.
|
||
|
|
</p>
|
||
|
|
<p>This option had another historical meaning, for DOS compatibility: in
|
||
|
|
the default (textual) mode, DOS reads a CR-LF sequence as one LF byte.
|
||
|
|
The <code class="code">b</code> flag prevents this from happening, adding <code class="code">O_BINARY</code>
|
||
|
|
to the underlying <code class="code">open</code> call. Still, the flag is generally useful
|
||
|
|
because of its port encoding ramifications.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Unless binary mode is requested, the character encoding of the new port
|
||
|
|
is determined as follows: First, if <var class="var">guess-encoding</var> is true, the
|
||
|
|
<code class="code">file-encoding</code> procedure is used to guess the encoding of the file
|
||
|
|
(see <a class="pxref" href="Character-Encoding-of-Source-Files.html">Character Encoding of Source Files</a>). If <var class="var">guess-encoding</var>
|
||
|
|
is false or if <code class="code">file-encoding</code> fails, <var class="var">encoding</var> is used unless
|
||
|
|
it is also false. As a last resort, the default port encoding is used.
|
||
|
|
See <a class="xref" href="Ports.html">Ports</a>, for more information on port encodings. It is an error to
|
||
|
|
pass a non-false <var class="var">guess-encoding</var> or <var class="var">encoding</var> if binary mode
|
||
|
|
is requested.
|
||
|
|
</p>
|
||
|
|
<p>If a file cannot be opened with the access requested, <code class="code">open-file</code>
|
||
|
|
throws an exception.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<a class="index-entry-id" id="index-open_002dinput_002dfile-2"></a>
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-open_002dinput_002dfile"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">open-input-file</strong> <var class="def-var-arguments">filename [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]</var><a class="copiable-link" href="#index-open_002dinput_002dfile"> ¶</a></span></dt>
|
||
|
|
<dd>
|
||
|
|
<p>Open <var class="var">filename</var> for input. If <var class="var">binary</var> is true, open the port
|
||
|
|
in binary mode, otherwise use text mode. <var class="var">encoding</var> and
|
||
|
|
<var class="var">guess-encoding</var> determine the character encoding as described above
|
||
|
|
for <code class="code">open-file</code>. Equivalent to
|
||
|
|
</p><div class="example lisp">
|
||
|
|
<pre class="lisp-preformatted">(open-file <var class="var">filename</var>
|
||
|
|
(if <var class="var">binary</var> "rb" "r")
|
||
|
|
#:guess-encoding <var class="var">guess-encoding</var>
|
||
|
|
#:encoding <var class="var">encoding</var>)
|
||
|
|
</pre></div>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<a class="index-entry-id" id="index-open_002doutput_002dfile-2"></a>
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-open_002doutput_002dfile"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">open-output-file</strong> <var class="def-var-arguments">filename [#:encoding=#f] [#:binary=#f]</var><a class="copiable-link" href="#index-open_002doutput_002dfile"> ¶</a></span></dt>
|
||
|
|
<dd>
|
||
|
|
<p>Open <var class="var">filename</var> for output. If <var class="var">binary</var> is true, open the port
|
||
|
|
in binary mode, otherwise use text mode. <var class="var">encoding</var> specifies the
|
||
|
|
character encoding as described above for <code class="code">open-file</code>. Equivalent
|
||
|
|
to
|
||
|
|
</p><div class="example lisp">
|
||
|
|
<pre class="lisp-preformatted">(open-file <var class="var">filename</var>
|
||
|
|
(if <var class="var">binary</var> "wb" "w")
|
||
|
|
#:encoding <var class="var">encoding</var>)
|
||
|
|
</pre></div>
|
||
|
|
</dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-call_002dwith_002dinput_002dfile"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">call-with-input-file</strong> <var class="def-var-arguments">filename proc [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]</var><a class="copiable-link" href="#index-call_002dwith_002dinput_002dfile"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-call_002dwith_002doutput_002dfile"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">call-with-output-file</strong> <var class="def-var-arguments">filename proc [#:encoding=#f] [#:binary=#f]</var><a class="copiable-link" href="#index-call_002dwith_002doutput_002dfile"> ¶</a></span></dt>
|
||
|
|
<dd><a class="index-entry-id" id="index-call_002dwith_002dinput_002dfile-2"></a>
|
||
|
|
<a class="index-entry-id" id="index-call_002dwith_002doutput_002dfile-2"></a>
|
||
|
|
<p>Open <var class="var">filename</var> for input or output, and call <code class="code">(<var class="var">proc</var>
|
||
|
|
port)</code> with the resulting port. Return the value returned by
|
||
|
|
<var class="var">proc</var>. <var class="var">filename</var> is opened as per <code class="code">open-input-file</code> or
|
||
|
|
<code class="code">open-output-file</code> respectively, and an error is signaled if it
|
||
|
|
cannot be opened.
|
||
|
|
</p>
|
||
|
|
<p>When <var class="var">proc</var> returns, the port is closed. If <var class="var">proc</var> does not
|
||
|
|
return (e.g. if it throws an error), then the port might not be
|
||
|
|
closed automatically, though it will be garbage collected in the usual
|
||
|
|
way if not otherwise referenced.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-with_002dinput_002dfrom_002dfile"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">with-input-from-file</strong> <var class="def-var-arguments">filename thunk [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]</var><a class="copiable-link" href="#index-with_002dinput_002dfrom_002dfile"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-with_002doutput_002dto_002dfile"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">with-output-to-file</strong> <var class="def-var-arguments">filename thunk [#:encoding=#f] [#:binary=#f]</var><a class="copiable-link" href="#index-with_002doutput_002dto_002dfile"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-with_002derror_002dto_002dfile"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">with-error-to-file</strong> <var class="def-var-arguments">filename thunk [#:encoding=#f] [#:binary=#f]</var><a class="copiable-link" href="#index-with_002derror_002dto_002dfile"> ¶</a></span></dt>
|
||
|
|
<dd><a class="index-entry-id" id="index-with_002dinput_002dfrom_002dfile-2"></a>
|
||
|
|
<a class="index-entry-id" id="index-with_002doutput_002dto_002dfile-2"></a>
|
||
|
|
<p>Open <var class="var">filename</var> and call <code class="code">(<var class="var">thunk</var>)</code> with the new port
|
||
|
|
setup as respectively the <code class="code">current-input-port</code>,
|
||
|
|
<code class="code">current-output-port</code>, or <code class="code">current-error-port</code>. Return the
|
||
|
|
value returned by <var class="var">thunk</var>. <var class="var">filename</var> is opened as per
|
||
|
|
<code class="code">open-input-file</code> or <code class="code">open-output-file</code> respectively, and an
|
||
|
|
error is signaled if it cannot be opened.
|
||
|
|
</p>
|
||
|
|
<p>When <var class="var">thunk</var> returns, the port is closed and the previous setting
|
||
|
|
of the respective current port is restored.
|
||
|
|
</p>
|
||
|
|
<p>The current port setting is managed with <code class="code">dynamic-wind</code>, so the
|
||
|
|
previous value is restored no matter how <var class="var">thunk</var> exits (eg. an
|
||
|
|
exception), and if <var class="var">thunk</var> is re-entered (via a captured
|
||
|
|
continuation) then it’s set again to the <var class="var">filename</var> port.
|
||
|
|
</p>
|
||
|
|
<p>The port is closed when <var class="var">thunk</var> returns normally, but not when
|
||
|
|
exited via an exception or new continuation. This ensures it’s still
|
||
|
|
ready for use if <var class="var">thunk</var> is re-entered by a captured continuation.
|
||
|
|
Of course the port is always garbage collected and closed in the usual
|
||
|
|
way when no longer referenced anywhere.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-port_002dmode"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">port-mode</strong> <var class="def-var-arguments">port</var><a class="copiable-link" href="#index-port_002dmode"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-scm_005fport_005fmode"><span class="category-def">C Function: </span><span><strong class="def-name">scm_port_mode</strong> <var class="def-var-arguments">(port)</var><a class="copiable-link" href="#index-scm_005fport_005fmode"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return the port modes associated with the open port <var class="var">port</var>.
|
||
|
|
These will not necessarily be identical to the modes used when
|
||
|
|
the port was opened, since modes such as "append" which are
|
||
|
|
used only during port creation are not retained.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-port_002dfilename"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">port-filename</strong> <var class="def-var-arguments">port</var><a class="copiable-link" href="#index-port_002dfilename"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-scm_005fport_005ffilename"><span class="category-def">C Function: </span><span><strong class="def-name">scm_port_filename</strong> <var class="def-var-arguments">(port)</var><a class="copiable-link" href="#index-scm_005fport_005ffilename"> ¶</a></span></dt>
|
||
|
|
<dd><p>Return the filename associated with <var class="var">port</var>, or <code class="code">#f</code> if no
|
||
|
|
filename is associated with the port.
|
||
|
|
</p>
|
||
|
|
<p><var class="var">port</var> must be open; <code class="code">port-filename</code> cannot be used once the
|
||
|
|
port is closed.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-set_002dport_002dfilename_0021"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">set-port-filename!</strong> <var class="def-var-arguments">port filename</var><a class="copiable-link" href="#index-set_002dport_002dfilename_0021"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-scm_005fset_005fport_005ffilename_005fx"><span class="category-def">C Function: </span><span><strong class="def-name">scm_set_port_filename_x</strong> <var class="def-var-arguments">(port, filename)</var><a class="copiable-link" href="#index-scm_005fset_005fport_005ffilename_005fx"> ¶</a></span></dt>
|
||
|
|
<dd><p>Change the filename associated with <var class="var">port</var>, using the current input
|
||
|
|
port if none is specified. Note that this does not change the port’s
|
||
|
|
source of data, but only the value that is returned by
|
||
|
|
<code class="code">port-filename</code> and reported in diagnostic output.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
<dl class="first-deffn">
|
||
|
|
<dt class="deffn" id="index-file_002dport_003f"><span class="category-def">Scheme Procedure: </span><span><strong class="def-name">file-port?</strong> <var class="def-var-arguments">obj</var><a class="copiable-link" href="#index-file_002dport_003f"> ¶</a></span></dt>
|
||
|
|
<dt class="deffnx def-cmd-deffn" id="index-scm_005ffile_005fport_005fp"><span class="category-def">C Function: </span><span><strong class="def-name">scm_file_port_p</strong> <var class="def-var-arguments">(obj)</var><a class="copiable-link" href="#index-scm_005ffile_005fport_005fp"> ¶</a></span></dt>
|
||
|
|
<dd><p>Determine whether <var class="var">obj</var> is a port that is related to a file.
|
||
|
|
</p></dd></dl>
|
||
|
|
|
||
|
|
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<div class="nav-panel">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Bytevector-Ports.html">Bytevector Ports</a>, Up: <a href="Port-Types.html">Types of Port</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|