file-contents

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.