378 lines
15 KiB
Racket
378 lines
15 KiB
Racket
#lang scribble/doc
|
|
@(require "mz.rkt" racket/file)
|
|
|
|
@(begin
|
|
;; ignore expressions at the top-level so that they don't print #<void>
|
|
(define-syntax ignore
|
|
(syntax-rules ()
|
|
[(_ expr) (define x expr)]))
|
|
|
|
;; hacky?
|
|
(define file-eval
|
|
(lambda ()
|
|
(let ([the-eval (make-base-eval)])
|
|
(the-eval '(require (for-syntax racket/base)
|
|
racket/file))
|
|
(the-eval '(define some-file (make-temporary-file)))
|
|
(the-eval '(define some-other-file (make-temporary-file)))
|
|
the-eval)))
|
|
|
|
(define-syntax file-examples
|
|
(syntax-rules ()
|
|
[(_ expr ...)
|
|
(let [(my-eval (file-eval))]
|
|
(define (clean)
|
|
(my-eval '(for [(i (list some-file some-other-file))]
|
|
(when (file-exists? i)
|
|
(delete-file i)))))
|
|
(clean)
|
|
(begin0
|
|
(defexamples #:eval my-eval
|
|
expr ...)
|
|
(clean)))]))
|
|
|
|
"")
|
|
|
|
@title[#:tag "file-ports"]{File Ports}
|
|
|
|
A port created by @racket[open-input-file], @racket[open-output-file],
|
|
@racket[subprocess], and related functions is a @deftech{file-stream
|
|
port}. The initial input, output, and error ports in @exec{racket}
|
|
are also file-stream ports. The @racket[file-stream-port?] predicate
|
|
recognizes file-stream ports.
|
|
|
|
When an input or output file-stream port is created, it is placed into
|
|
the management of the current custodian (see
|
|
@secref["custodians"]).
|
|
|
|
@defproc[(open-input-file [path path-string?]
|
|
[#:mode mode-flag (or/c 'binary 'text) 'binary])
|
|
input-port?]{
|
|
|
|
Opens the file specified by @racket[path] for input. The
|
|
@racket[mode-flag] argument specifies how the file's bytes are
|
|
translated on input:
|
|
|
|
@itemize[
|
|
|
|
@item{@indexed-racket['binary] --- bytes are returned from the port
|
|
exactly as they are read from the file.}
|
|
|
|
@item{@indexed-racket['text] --- return and linefeed bytes (10 and
|
|
13) as read from the file are filtered by the port in a platform
|
|
specific manner:
|
|
|
|
@itemize[
|
|
|
|
@item{@|AllUnix|: no filtering occurs.}
|
|
|
|
@item{Windows: a return-linefeed combination from a file is returned
|
|
by the port as a single linefeed; no filtering occurs for
|
|
return bytes that are not followed by a linefeed, or for a
|
|
linefeed that is not preceded by a return.}
|
|
]}
|
|
]
|
|
|
|
On Windows, @racket['text] mode works only with regular files;
|
|
attempting to use @racket['text] with other kinds of files triggers an
|
|
@racket[exn:fail:filesystem] exception.
|
|
|
|
Otherwise, the file specified by @racket[path] need not be a regular
|
|
file. It might be a device that is connected through the filesystem, such
|
|
as @filepath{aux} on Windows or @filepath{/dev/null} on Unix. In all
|
|
cases, the port is buffered by default.
|
|
|
|
The port produced by @racket[open-input-file] should be explicitly
|
|
closed, either though @racket[close-input-port] or indirectly via
|
|
@racket[custodian-shutdown-all], to release the OS-level file
|
|
handle. The input port will not be closed automatically if it is
|
|
otherwise available for garbage collection (see
|
|
@secref["gc-model"]); a @tech{will} could be associated with an input port
|
|
to close it more automatically (see @secref["willexecutor"]).
|
|
|
|
A @tech{path} value that is the @tech{cleanse}d version of
|
|
@racket[path] is used as the name of the opened port.
|
|
|
|
@file-examples[
|
|
;; put some text in a file
|
|
(with-output-to-file some-file
|
|
(lambda () (printf "hello world")))
|
|
(define in (open-input-file some-file))
|
|
(read-string 11 in)
|
|
(close-input-port in)
|
|
]}
|
|
|
|
@defproc[(open-output-file [path path-string?]
|
|
[#:mode mode-flag (or/c 'binary 'text) 'binary]
|
|
[#:exists exists-flag (or/c 'error 'append 'update 'can-update
|
|
'replace 'truncate
|
|
'must-truncate 'truncate/replace) 'error])
|
|
output-port?]{
|
|
|
|
Opens the file specified by @racket[path] for output. The
|
|
@racket[mode-flag] argument specifies how bytes written to the port
|
|
are translated when written to the file:
|
|
|
|
@itemize[
|
|
|
|
@item{@racket['binary] --- bytes are written to the file exactly
|
|
as written to the port.}
|
|
|
|
@item{@racket['text] --- on Windows, a linefeed byte (10) written
|
|
to the port is translated to a return-linefeed combination in the
|
|
file; no filtering occurs for returns.}
|
|
|
|
]
|
|
|
|
On Windows, @racket['text] mode works only with regular files;
|
|
attempting to use @racket['text] with other kinds of files triggers an
|
|
@racket[exn:fail:filesystem] exception.
|
|
|
|
The @racket[exists-flag] argument specifies how to handle/require
|
|
files that already exist:
|
|
|
|
@itemize[
|
|
|
|
@item{@indexed-racket['error] --- raise @racket[exn:fail:filesystem]
|
|
if the file exists.}
|
|
|
|
@item{@indexed-racket['replace] --- remove the old file, if it
|
|
exists, and write a new one.}
|
|
|
|
@item{@indexed-racket['truncate] --- remove all old data, if the file
|
|
exists.}
|
|
|
|
@item{@indexed-racket['must-truncate] --- remove all old data in an
|
|
existing file; if the file does not exist, the
|
|
@exnraise[exn:fail:filesystem].}
|
|
|
|
@item{@indexed-racket['truncate/replace] --- try @racket['truncate];
|
|
if it fails (perhaps due to file permissions), try
|
|
@racket['replace].}
|
|
|
|
@item{@indexed-racket['update] --- open an existing file without
|
|
truncating it; if the file does not exist, the
|
|
@exnraise[exn:fail:filesystem]. Use @racket[file-position]
|
|
to change the current read/write position.}
|
|
|
|
@item{@indexed-racket['can-update] --- open an existing file without
|
|
truncating it, or create the file if it does not exist.}
|
|
|
|
@item{@indexed-racket['append] --- append to the end of the file,
|
|
whether it already exists or not; on Windows,
|
|
@racket['append] is equivalent to @racket['update], except that
|
|
the file is not required to exist, and the file position is
|
|
immediately set to the end of the file after opening it.}
|
|
|
|
]
|
|
|
|
The file specified by @racket[path] need not be a regular file. It
|
|
might be a device that is connected through the filesystem, such as
|
|
@filepath{aux} on Windows or @filepath{/dev/null} on Unix. The output
|
|
port is block-buffered by default, unless the file corresponds to a
|
|
terminal, in which case it is line-buffered by default.
|
|
|
|
The port produced by @racket[open-output-file] should be explicitly
|
|
closed, either though @racket[close-output-port] or indirectly via
|
|
@racket[custodian-shutdown-all], to release the OS-level file
|
|
handle. The output port will not be closed automatically if it is
|
|
otherwise available for garbage collection (see
|
|
@secref["gc-model"]); a @tech{will} could be associated with an output port
|
|
to close it more automatically (see @secref["willexecutor"]).
|
|
|
|
A @tech{path} value that is the @tech{cleanse}d version of
|
|
@racket[path] is used as the name of the opened port.
|
|
|
|
@file-examples[
|
|
(define out (open-output-file some-file))
|
|
(write "hello world" out)
|
|
(close-output-port out)
|
|
]}
|
|
|
|
@defproc[(open-input-output-file [path path-string?]
|
|
[#:mode mode-flag (or/c 'binary 'text) 'binary]
|
|
[#:exists exists-flag (or/c 'error 'append 'update 'can-update
|
|
'replace 'truncate 'truncate/replace) 'error])
|
|
(values input-port? output-port?)]{
|
|
|
|
Like @racket[open-output-file], but producing two values: an input
|
|
port and an output port. The two ports are connected in that they
|
|
share the underlying file descriptor. This procedure is intended for use
|
|
with special devices that can be opened by only one process, such as
|
|
@filepath{COM1} in Windows. For regular files, sharing the file descriptor can be
|
|
confusing. For example, using one port does not automatically flush
|
|
the other port's buffer, and reading or writing in one port moves the
|
|
file position (if any) for the other port. For regular files, use
|
|
separate @racket[open-input-file] and @racket[open-output-file] calls
|
|
to avoid confusion.}
|
|
|
|
@defproc[(call-with-input-file [path path-string?]
|
|
[proc (input-port? . -> . any)]
|
|
[#:mode mode-flag (or/c 'binary 'text) 'binary])
|
|
any]{
|
|
Calls @racket[open-input-file] with the @racket[path] and
|
|
@racket[mode-flag] arguments, and passes the resulting port
|
|
to @racket[proc]. The result of @racket[proc] is the result of the
|
|
@racket[call-with-input-file] call, but the newly opened port is closed
|
|
when @racket[proc] returns.
|
|
|
|
@file-examples[
|
|
(with-output-to-file some-file
|
|
(lambda () (printf "text in a file")))
|
|
(call-with-input-file some-file
|
|
(lambda (in) (read-string 14 in)))
|
|
]}
|
|
|
|
@defproc[(call-with-output-file [path path-string?]
|
|
[proc (output-port? . -> . any)]
|
|
[#:mode mode-flag (or/c 'binary 'text) 'binary]
|
|
[#:exists exists-flag (or/c 'error 'append 'update
|
|
'replace 'truncate 'truncate/replace) 'error])
|
|
any]{
|
|
Analogous to @racket[call-with-input-file], but passing @racket[path],
|
|
@racket[mode-flag] and @racket[exists-flag] to
|
|
@racket[open-output-file].
|
|
|
|
@file-examples[
|
|
(call-with-output-file some-file
|
|
(lambda (out)
|
|
(write 'hello out)))
|
|
(call-with-input-file some-file
|
|
(lambda (in)
|
|
(read-string 5 in)))
|
|
]}
|
|
|
|
@defproc[(call-with-input-file* [path path-string?]
|
|
[proc (input-port? . -> . any)]
|
|
[#:mode mode-flag (or/c 'binary 'text) 'binary])
|
|
any]{
|
|
Like @racket[call-with-input-file], but the newly opened port is
|
|
closed whenever control escapes the dynamic extent of the
|
|
@racket[call-with-input-file*] call, whether through @racket[proc]'s
|
|
return, a continuation application, or a prompt-based abort.}
|
|
|
|
@defproc[(call-with-output-file* [path path-string?]
|
|
[proc (output-port? . -> . any)]
|
|
[#:mode mode-flag (or/c 'binary 'text) 'binary]
|
|
[#:exists exists-flag (or/c 'error 'append 'update
|
|
'replace 'truncate 'truncate/replace) 'error])
|
|
any]{
|
|
Like @racket[call-with-output-file], but the newly opened port is
|
|
closed whenever control escapes the dynamic extent of the
|
|
@racket[call-with-output-file*] call, whether through @racket[proc]'s
|
|
return, a continuation application, or a prompt-based abort.}
|
|
|
|
@defproc[(with-input-from-file [path path-string?]
|
|
[thunk (-> any)]
|
|
[#:mode mode-flag (or/c 'binary 'text) 'binary])
|
|
any]{
|
|
Like @racket[call-with-input-file*], but instead of passing the newly
|
|
opened port to the given procedure argument, the port is installed as
|
|
the current input port (see @racket[current-input-port]) using
|
|
@racket[parameterize] around the call to @racket[thunk].
|
|
|
|
@file-examples[
|
|
(with-output-to-file some-file
|
|
(lambda () (printf "hello")))
|
|
(with-input-from-file some-file
|
|
(lambda () (read-string 5)))
|
|
]}
|
|
|
|
@defproc[(with-output-to-file [path path-string?]
|
|
[thunk (-> any)]
|
|
[#:mode mode-flag (or/c 'binary 'text) 'binary]
|
|
[#:exists exists-flag (or/c 'error 'append 'update
|
|
'replace 'truncate 'truncate/replace) 'error])
|
|
any]{
|
|
Like @racket[call-with-output-file*], but instead of passing the newly
|
|
opened port to the given procedure argument, the port is installed as
|
|
the current output port (see @racket[current-output-port]) using
|
|
@racket[parameterize] around the call to @racket[thunk].
|
|
|
|
@file-examples[
|
|
(with-output-to-file some-file
|
|
(lambda () (printf "hello")))
|
|
(with-input-from-file some-file
|
|
(lambda () (read-string 5)))
|
|
]}
|
|
|
|
|
|
@defproc[(port-try-file-lock? [port file-stream-port?]
|
|
[mode (or/c 'shared 'exclusive)])
|
|
boolean?]{
|
|
|
|
Attempts to acquire a lock on the file using the current platform's
|
|
facilities for file locking. Multiple processes can acquire a
|
|
@racket['shared] lock on a file, but at most one process can hold an
|
|
@racket['exclusive] lock, and @racket['shared] and @racket['exclusive]
|
|
locks are mutually exclusive. When @racket[mode] is @racket['shared],
|
|
then @racket[port] must be an input port; when @racket[mode] is
|
|
@racket['exclusive], then @racket[port] must be an output port.
|
|
|
|
The result is @racket[#t] if the requested lock is acquired,
|
|
@racket[#f] otherwise. When a lock is acquired, it is held until
|
|
either it is released with @racket[port-file-unlock] or the port is closed
|
|
(perhaps because the process terminates).
|
|
|
|
Depending on the platform, locks may be merely advisory (i.e., locks
|
|
affect only the ability of processes to acquire locks) or they may
|
|
correspond to mandatory locks that prevent reads and writes to the
|
|
locked file. Specifically, locks are mandatory on Windows and advisory
|
|
on other platforms. Multiple tries for a @racket['shared] lock on a
|
|
single port can succeed; on Unix and Mac OS X, a single
|
|
@racket[port-file-unlock] release the lock, while on other Windows, a
|
|
@racket[port-file-unlock] is needed for each successful
|
|
@racket[port-try-file-lock?]. On Unix and Mac OS X, multiple tries for
|
|
a @racket['exclusive] lock can succeed and a single
|
|
@racket[port-file-unlock] releases the lock, while on Windows, a try
|
|
for an @racket['exclusive] lock fails for a given port if the port
|
|
already holds the lock.
|
|
|
|
A lock acquired for an input port from @racket[open-input-output-file]
|
|
can be released through @racket[port-file-unlock] on the corresponding
|
|
output port, and vice versa. If the output port from
|
|
@racket[open-input-output-file] holds an @racket['exclusive] lock, the
|
|
corresponding input port can still acquire a @racket['shared] lock,
|
|
even multiple times; on Windows, a @racket[port-file-unlock] is needed
|
|
for each successful lock try, while a single @racket[port-file-unlock]
|
|
balances the lock tries on Unix and Mac OS X. A @racket['shared] lock on
|
|
an input port can be upgraded to an @racket['exclusive] lock through the
|
|
corresponding output port on Unix and Mac OS X, in which case a single
|
|
@racket[port-file-unlock] (on either port) releases the lock, while
|
|
such upgrades are not allowed on Windows.
|
|
|
|
Locking is normally supported only for file ports, and attempting to
|
|
acquire a lock with other kinds of file-stream ports raises an
|
|
@racket[exn:fail:filesystem] exception.}
|
|
|
|
|
|
@defproc[(port-file-unlock [port file-stream-port?])
|
|
void?]{
|
|
|
|
Releases a lock held by the current process on the file of
|
|
@racket[port].}
|
|
|
|
|
|
@defproc[(port-file-identity [port file-stream-port?]) exact-positive-integer?]{
|
|
|
|
@index['("inode")]{Returns} a number that represents
|
|
the identity of the device and file read or written by
|
|
@racket[port]. For two ports whose open times overlap, the
|
|
result of @racket[port-file-identity] is the same for both ports if
|
|
and only if the ports access the same device and file. For ports whose
|
|
open times do not overlap, no guarantee can be provided for the port
|
|
identities (even if the ports actually access the same file)---except
|
|
as can be inferred through relationships with other ports. If
|
|
@racket[port] is closed, the @exnraise[exn:fail]. On
|
|
Windows 95, 98, and Me, if @racket[port] is connected to a
|
|
pipe instead of a file, the @exnraise[exn:fail:filesystem].
|
|
|
|
@file-examples[
|
|
(define file1 (open-output-file some-file))
|
|
(define file2 (open-output-file some-other-file))
|
|
(port-file-identity file1)
|
|
(port-file-identity file2)
|
|
(close-output-port file1)
|
|
(close-output-port file2)
|
|
]}
|