FunctionPackage: exclToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 9.0
Unrevised from 8.2 to 9.0.
8.2 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-2012, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 9.0. This page was not revised from the 8.2 page.
Created 2012.5.30.

Allegro CL version 9.0
Unrevised from 8.2 to 9.0.
8.2 version