Function | Package: excl | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version

## 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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version