| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
Arguments: filespec &rest open-arguments
This function returns a vector containing the contents of the file specified by filespec. filespec may be a pathname, a string naming a file, or a stream open to a file.
The open-arguments arguments are the same as the
arguments to open, except the
direction keyword argument is ignored and the
if-does-not-exist keyword argument defaults
unconditionally to nil
(recall that in calls
to open, the default for
if-does-not-exist depends on the values of other
arguments).
The element-type argument to open specifies the type of
vector that will be created (which will be upgraded-array-element-type applied to the
specified element-type). If element-type is not
specified, it defaults to character
and the result
is a string. For a byte array containing the file contents, specify
(unsigned-byte 8)
. Basically, the function is
intended for element-types character
and
(unsigned-byte 8)
. Specifying other element types
will work but may produce an unspecialized array (element-type t)
which would not be suitable as data when setf'ing this function.
If file-contents is being
called to simply hold the contents of a file, for example for later
writing out, then element-type should be
(unsigned-byte 8)
rather than
character
. Using character
involves an external-format overhead, and you have to be sure to
specify the same external-format when writing the file as was used
when reading the file. (unsigned-byte 8)
avoids
both problems. Note further when using character
:
if you don't specify an external-format (as the value of the
external-format to open included among
open-arguments) when calling file-contents, then the default
external-format (which comes from the current *locale*
setting) may not correctly represent
all characters.
The behavior if the file specified by filespec
does not exist is determined by the
if-does-not-exist argument (to open and thus to this
function). For this function, that argument defaults to nil
so nil
is returned if the file does not exist and
if-does-not-exist is unspecified.
This function is setf'able. The setf function has argument list
Arguments: vector pathname &rest open-arguments
The standard setf form is, of course:
(setf (file-contents pathname) vector)
The setf function also accepts keyword/value pairs suitable to be
passed to the function open, but direction and
element-type are not accepted. The
element-type passed to open is the array-element-type of
vector. Warning: if the element-type of
the vector is not suitable as an element-type for open, the call to open will
fail. t
is not suitable as an element-type to
open. character
and
(unsigned-byte 8)
are both, of course, suitable.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |