The module file
provides an interface to the file system.
Most functions have a name argument such as a file name or directory
name, which is either an atom, a string, or a deep list of
characters, lists, and atoms. The filename
module accepts
filenames in the same format.
A path is a list of directory names. If
the functions are successful, they return ok
, or {ok,
Value}
.
If an error occurs, the return value has the format
{error, Reason}
.
Reason
is an atom which is named from the Posix error codes used
in Unix, and in the runtime libraries of most C compilers.
In the following descriptions of functions, the most typical error codes are listed.
By matching the error code, applications can use this information for error recovery. To produce a readable error string, use format_error/1
.
On operating systems with thread support (Solaris and Windows), it is
possible to let file operations be performed in threads of their own,
allowing other Erlang processes to continue executing in parallel with
the file operations. See the command-line option +A
in the manual
page for erl
.
Change group of a file. See write_file_info/2
.
Change owner of a file. See write_file_info/2
.
change_owner(Filename, Uid, Gid)
Change owner and group of a file. See write_file_info/2
.
Change the modification and access times of a file.
See write_file_info/2
.
change_time(Filename, Mtime, Atime)
Change the modification and access times of a file.
See write_file_info/2
.
Closes the file referenced by IoDevice
. It mostly
returns ok
, expect for some severe errors such as out
of memory.
Note that if the option delayed_write
was
used when opening the file, close/1
might return an
old write error and not even try to close the file. See
open/2
.
Opens file Filename
and reads all the Erlang terms in
it. Returns one of the following:
{ok, TermList}
{error, Atom}
Atom
is a Posix error code.
See the description of open/2
for a list
of typical error codes.
{error, {Line, Mod, Term}}
format_error/1
function to convert
the three-element tuple to an English description of
the error.
Copies the contents of Source
to
Destination
. Source
and Destination
are
either filenames or open file references from e.g
open/2
.
The same as copy/3
but with infinite byte count.
copy(Source, Destination, ByteCount)
Copies ByteCount
bytes from Source
to
Destination
. Source
and Destination
are
either filenames or open file references from e.g
open/2
.
If Source
is a tuple {Filename, ModeList}
where ModeList
is a mode list as for open/2
,
the source is opened with read
mode prepended to the
mode list before the copy, and closed when done.
If Source
is a filename, it is interpreted as
{Source, []}
. The file is thereby read from the beginning.
If Destination
is a tuple {Filename, ModeList}
where ModeList
is a mode list as for open/2
,
the destination is opened with write
mode prepended to the
mode list before the copy, and closed when done.
If Destination
is a filename, it is interpreted as
{Destination, []}
. This implies that the previous
file contents are overwritten.
If both Source
and Destination
are filenames
or {Filename, ModeList}
tuples, the files are opened
with [raw, read, binary]
and
[raw, write, binary]
prepended to their mode lists,
respectively, to optimize the copy.
Returns {ok, BytesCopied}
where BytesCopied
is
the number of bytes that actually was copied, which may be
less than ByteCount
if end of file was encountered on the
source. If the operation fails, {error, Reason}
is
returned.
Typical error reasons: As for open/2
if a file had to
be opened, and as for read/2
and write/2
.
Tries to delete the directory DirName
. The directory
must be empty before it can be deleted. Returns ok
if
successful.
Typical error reasons are:
eacces
DirName
.
eexist
enoent
enotdir
DirName
is not a directory. On some platforms,
enoent
is returned instead.
einval
eacces
is returned instead.
Tries to delete the file Filename
. Returns ok
if successful.
Typical error reasons are:
enoent
eacces
eperm
enotdir
enoent
is returned instead.
Opens the file Filename
and evaluates all the
expression sequences in it.
It returns one of the following:
ok
{error, Atom}
Atom
is a Posix error code.
See the description of open/2
for a list
of typical error codes.
{error, {Line, Mod, Term}}
format_error/1
function to convert
the three-element tuple to an English description of
the error.
The same as eval/1
but the variable bindings
Bindings
are used in the evaluation. See
erl_eval(3) about variable bindings.
This function is obsolete.
Use |
Retrieves information about a file. Returns {ok,
FileInfo}
if successful, otherwise {error,
Reason}
. FileInfo
is a tuple with the following
fields:
{Size,Type,Access,AccessTime,ModifyTime,UnUsed1,UnUsed2}
Size
Type
device
, directory
,
regular
, or other
.
Access
read
, write
, read_write
, or none
.
AccessTime
{Year, Month, Day, Hour, Minute, Second}
.
ModifyTime
{Year, Month, Day, Hour, Minute, Second}
.
UnUsed1, UnUsed2
unused
.
Typical error reasons: Same as for read_file_info/1
.
Given the error reason returned by any function in this module, it returns a descriptive string of the error in English.
Returns {ok, CurDir}
, where CurDir
(a string)
is the current working directory of the file server.
In rare circumstances, this function can fail on Unix. It may happen if read permission does not exist for the parent directories of the current directory. |
Typical error reasons are:
eacces
Drive
should be of the form "Letter
:
",
for example "c:".
Returns {ok, CurDir}
or {error, Reason}
,
where CurDir
(a string) is the current working directory
of the drive specified.
This function returns {error, enotsup}
on platforms
which have no concept of current drive
(Unix, for example).
Typical error reasons are:
enotsup
eacces
einval
Drive
is invalid.
ipread_s32bu_p32bu(IoDevice, Location, MaxSize)
Specialised indirect read function for Dets. Equivalent to
pread/3
of a header from Location
followed
by another pread/3
of the buffer specified by the
header.
This function is not intended to be used by others than Dets. It is therefore not well documented. |
Lists all the files in a directory.
Returns {ok, FilenameList}
if successful.
Otherwise, it returns {error, Reason}
.
FilenameList
is a list of
the names of all the files in the directory.
Each name is a string. The names are not sorted.
Typical error reasons are:
eacces
DirName
or
one of its parent directories.
enoent
Tries to create the directory DirName
. Missing parent
directories are NOT created. Returns ok
if
successful.
Typical error reasons are:
eacces
DirName
.
eexist
DirName
.
enoent
DirName
does not exist.
enospc
enotdir
DirName
is not a directory. On some platforms,
enoent
is returned instead.
Makes a hard link from Existing
to New
,
on platforms that support links (Unix).
This function returns ok
if the link was successfully created,
or {error,Reason}
.
On platforms that do not support links, {error,enotsup}
will
be returned.
Typical error reasons:
eacces
Existing
or New
.
eexist
new
already exists.
enotsup
This function creates a symbolic link Name2
to the
file or directory Name1
, on platforms that support
symbolic links (most Unix systems).
Name1
need not exist.
This function returns ok
if the link was successfully created,
or {error,Reason}
.
On platforms that do not support symbolic links, {error,enotsup}
will
be returned.
Typical error reasons:
eacces
Existing
or New
.
eexist
new
already exists.
enotsup
Opens the file Filename
in the mode determined by
ModeList
.
ModeList
may contain one or more of the following items:
read
write
read
).
append
append
will take place at the end of the file.
raw
raw
option allows faster access to a file,
because no Erlang process is needed to handle the file.
However, a file opened in this way has the following limitations:
io
module cannot be used,
because they can only talk to an Erlang process.
Instead, use the read/2
and write/2
functions.
binary
raw
option
is specified as well.
When specified, read operations on the file using the read/2
function will return binaries rather than lists.
{delayed_write, Size, Delay}
write/2
calls is buffered until there are at least
Size
bytes buffered,
or until the oldest buffered data is Delay
milliseconds old. Then all buffered data is written in
one operating system call. The buffered data is also
flushed before some other file operation than
write/2
is executed.write/2
calls should be for sizes significantly
less than Size
, and not interspersed by to many
other file operations, for this to happen.write/2
calls may prematurely be reported as successful, and if
a write error should actually occur the error is
reported as the result of the next file operation, which
is not executed.delayed_write
is used, after a number
of write/2
calls, close/1
might return
{error, enospc}
because there was not enough
space on the disc for previously written data, and
close/1
should probably be called again since the
file is still open.delayed_write
{delayed_write, Size, Delay}
with reasonable default values for Size
and
Delay
. (Roughly some 64 KBytes, 2 seconds){read_ahead, Size}
read/2
calls are for significantly less than
Size
bytes, read operations towards the operating
system are still performed for blocks of Size
bytes. The extra data is buffered and returned in subsequent
read/2
calls, giving a performance gain since the
number of operating system calls is reduced.read/2
calls are for sizes not significantly
less than, or even greater than Size
bytes, no
performance gain can be expected.read_ahead
{read_ahead, Size}
with a
reasonable default value for Size
.
(Roughly some 64 KBytes)compressed
read_file_info/1
will most probably not match the
number of bytes that can be read from a compressed file.
If both read
and write
are specified, the file
is created if it does not exists. It is not truncated
if it exists.
Returns:
{ok, IoDevice}
IoDevice
is a reference to the file.
{error, Reason}
A file descriptor
is the Pid of the process which
handles the file. The file process is linked to the process
which originally opened the file. If any process to which
the file process is linked terminates, the file will be
closed by the file process and the process itself will be
terminated. The file descriptor returned from this call can
be used as an argument to the I/O functions (see io
).
In previous versions of |
Typical error reasons:
enoent
eacces
eisdir
enotdir
enoent
is returned instead.
enospc
write
access
was specified).
Searches the path Path
(a list of directory names)
until the file Filename
is found.
If Filename
is an absolute file name, Path
is ignored.
The file is opened and all the terms in it are read.
The function returns one of the following:
{ok, TermList, FullName}
FullName
is
the full name of the file which was opened and read.
{error, enoent}
Path
.
{error, Atom}
Atom
is a Posix error code.
See the description of open/2
for a list
of typical error codes.
{error, {Line, Mod, Term}}
format_error/1
function to convert
the three-element tuple to an English description of
the error.
Searches the path Path
(a list of directory names)
until the file Filename
is found.
If Filename
is an absolute file name, Path
is ignored.
The file is opened and all the expression sequences in
it are evaluated.
The function returns one of the following:
{ok, FullName}
FullName
is the full name
of the file which was opened and evaluated.
{error, enoent}
Path
.
{error, Atom}
Atom
is a Posix error code.
See the description of open/2
for a list
of typical error codes.
{error, {Line, Mod, Term}}
format_error/1
function to convert
the three-element tuple to an English description of
the error.
path_open(Path, Filename, Mode)
Searches the path Path
(a list of directory names)
until the file Filename
is found.
If Filename
is an absolute file name, Path
is ignored.
The function returns one of the following:
{ok, IoDevice, FullName}
IoDevice
is a reference to the file and
FullName
is the full name of the file which was
opened.
{error, enoent}
Filename
was not found in the path.
{error, Reason}
Filename
.
Searches the path Path
(a list of directory names)
until the file Filename
is found.
If Filename
is an absolute file name, Path
is ignored.
The file is opened, all the expression sequences in
it are evaluated and the result value is returned.
The function returns one of the following:
{ok, Value, FullName}
FullName
is the full name
of the file which was opened and evaluated with the
result value Value
.
{error, enoent}
Path
.
{error, Atom}
Atom
is a Posix error code.
See the description of open/2
for a list
of typical error codes.
{error, {Line, Mod, Term}}
format_error/1
function to convert
the three-element tuple to an English description of
the error.
path_script(Path, Filename, Bindings)
The same as path_script/2
but the variable bindings
Bindings
are used in the evaluation. See
erl_eval(3) about variable bindings.
If Pid
is a pid previously returned from open/2
,
this function returns the filename, or rather:
{ok, Filename}
Pid
must be a local pid) and the file is not
closed. Filename
is the filename in flat string
format.undefined
This function is meant for debugging only.
Sets the position of the file referenced by
IoDevice
to Location
. Returns {ok,
NewPosition}
(as absolute offset) if successful, otherwise
{error, Reason}
. Location
is one of the
following:
{bof, Offset}
{cur, Offset}
{eof, Offset}
Integer
{bof, Integer}
bof || cur || eof
Offset
0.
Typical error reasons are:
einval
Location
was illegal, or
it evaluated to a negative offset in the file. Note that
if the resulting position is a negative value you will get
an error but after the call it is undefined where the file
position will be.
pread(IoDevice, [{Location, Number}, ...])
Performs a sequence of pread/3
in one operation,
which is more efficient than calling them one at a time.
Returns {ok, [Data, ...]}
or
{error, Reason}
, where Data
is either a list
or a binary depending on the mode of the file, or eof
if the requested position was beyond end of file.
pread(IoDevice, Location, Number)
Combines position/2
and read/2
in one operation,
which is
more efficient than calling them one at a time.
If IoDevice
has been opened in raw mode, some restrictions
apply: Location
is only allowed to be an integer; and the
current position of the file is undefined after the operation.
pwrite(IoDevice, [{Location, Bytes}, ...])
Performs a sequence of pwrite/3
in one operation,
which is more efficient than calling them one at a time.
Returns ok
or
{error, {NumberWritten, Reason}}
, where
NumberWritten
is the number of successful writes that
was done before the failure.
pwrite(IoDevice, Location, Bytes)
Combines position/2
and write/2
in one operation,
which is
more efficient than calling them one at a time.
If IoDevice
has been opened in raw mode, some restrictions
apply: Location
is only allowed to be an integer; and the
current position of the file is undefined after the operation.
Reads Number
bytes from the file described by
IoDevice
.
This function is the only way to read from a file opened
in raw mode (although it works for normally opened files, too).
Returns:
{ok, ListOrBinary}
eof
eof
is returned if the Number
was greater than zero and end of file
was reached before anything at all could be read.
{error, Reason}
ebadf
Returns {ok, Binary}
, where Binary
is a binary
data object that contains the contents of Filename
, or
{error, Reason}
if an error occurs.
Typical error reasons:
enoent
eacces
eisdir
enotdir
enoent
is returned instead.
enomem
Retrieves information about a file. Returns {ok,
FileInfo}
if successful, otherwise {error,
Reason}
. FileInfo
is a record.
Its definition can be found by including file.hrl
from the kernel application:
-include_lib("kernel/include/file.hrl").
The record contains the following fields.
size
type
device
, directory
,
regular
, or other
.
access
read
, write
, read_write
, or none
.
atime
{{Year, Month, Day}, {Hour, Minute, Second}}
.
mtime
{{Year, Month, Day}, {Hour, Minute, Second}}
.
ctime
{{Year, Month, Day}, {Hour, Minute, Second}}
.
mode
links
major_device
minor_device
inode
inode
number.
On non-Unix file systems, this field will be zero.
uid
gid
Typical error reasons:
eacces
enoent
enotdir
enoent
is returned instead.
This function returns {ok,Filename}
if Linkname
refers to a symbolic link or {error,Reason}
otherwise.
On platforms that do not support symbolic links, the return value
will be {error,enotsup}
.
Typical error reasons:
einval
Linkname
does not refer to a symbolic link.
enoent
enotsup
This function works like read_file_info/1
, except that
if Filename
is a symbolic link, information about the link
will be returned in the file_info
record and the type
field of the record will be set to symlink
.
If Filename
is not a symbolic link, this function returns
exactly the same result as read_file_info/1
.
On platforms that do not support symbolic link, this function is
always equvivalent to read_file_info/1
.
Tries to rename the file Source
to
Destination
. It can be used to move files (and directories) between directories, but it is not sufficient to specify the destination only. The destination file name must also be specified. For example, if bar
is a normal file and foo
and baz
are directories, rename("foo/bar", "baz")
returns an
error, but rename("foo/bar", "baz/bar")
succeeds. Returns ok
if it is successful.
Renaming of open files is not allowed on most platforms (see |
Typical error reasons:
eacces
Source
or Destination
.
On some platforms, this error is given if either Source
or Destination
is open.
eexist
Destination
is not an empty
directory.
On some platforms, also given when Source
and
Destination
are not of the same type.
einval
Source
is a root directory, or Destination
is a
sub-directory of Source
.
eisdir
Destination
is a directory, but Source
is not.
enoent
Source
does not exist.
enotdir
Source
is a directory, but Destination
is not.
exdev
Source
and Destination
are on different file systems.
Opens the file Filename
, evaluates all the
expression sequences in it and returns the result value.
It returns one of the following:
{ok, Value}
Value
.
{error, Atom}
Atom
is a Posix error code.
See the description of open/2
for a list
of typical error codes.
{error, {Line, Mod, Term}}
format_error/1
function to convert
the three-element tuple to an English description of
the error.
The same as script/1
but the variable bindings
Bindings
are used in the evaluation. See
erl_eval(3) about variable bindings.
Sets the current working directory of the file server to
DirName
. Returns ok
if successful.
Typical error reasons are:
enoent
enotdir
DirName
is not a directory. On some platforms,
enoent
is returned.
eacces
Makes sure that any buffers kept by the operating system (not by the Erlang runtime system) are written to disk. On some platforms, this function might have no effect .
Typical error reasons are:
enospc
Truncates the file referenced by IoDevice
at
the current position. Returns ok
if successful,
otherwise {error, Reason}
.
Writes Bytes
(possibly a deep list of characters, or
a binary) to the file described by IoDevice
.
This function is the only way to write to a file opened
in raw mode (although it works for normally opened files, too).
This function returns ok
if successful, and
{error, Reason}
otherwise.
Typical error reasons are:
ebadf
enospc
Writes the contents of the binary data object Binary
to the file Filename
.
The file is created if it does not exist already. If it exists, the previous contents are overwritten.
Returns ok
, or {error, Reason}
.
Typical error reasons are:
enoent
enotdir
enoent
is returned instead.
enospc
eacces
eisdir
write_file(Filename, Binary, ModeList)
Same as write_file/2, but allows file open mode flags to
be specified in ModeList
. Mode flags binary
and write
are implicit so they should not be used.
See also open/2
.
write_file_info(Filename, FileInfo)
Change file information. Returns ok
if successful,
otherwise {error, Reason}
.
FileInfo
is a record.
Its definition can be found by including file.hrl
from the kernel application:
-include_lib("kernel/include/file.hrl").
The following fields are used from the record if they are given.
atime
{{Year, Month, Day}, {Hour, Minute, Second}}
.
mtime
{{Year, Month, Day}, {Hour, Minute, Second}}
.
ctime
{{Year, Month, Day}, {Hour, Minute, Second}}
.
mode
uid
gid
Typical error reasons:
eacces
enoent
enotdir
enoent
is returned instead.
Some operating system file operations, for example a
sync/1
or close/1
on a huge file, may block their
calling thread for seconds. If this befalls the emulator main
thread the response time is no longer in the order of
milliseconds, depending on the definition of "soft" in soft
real-time system.
If the device driver thread pool is active, file operations are done through those threads instead, so the emulator can go on executing erlang processes. Unfortunately, the time for serving a file operation increases due to the extra scheduling required from the operating system.
If the device driver thread pool is disabled or of size 0,
large file reads and writes are segmented into several smaller,
which enables the emulator so server other processes during the
file operation. This gives the same effect as when using the
thread pool, but with larger overhead. Other file operations,
for example sync/1
or close/1
on a huge file,
still is a problem.
For increased performance, raw files are recommended. Raw files, uses the file system of the node's host machine. For normal files (non-raw) the file server is used to find the files, and if the node is running its file server as slave to another node's, and the other node runs on some other host machine, they may have different file systems. This is seldom a problem, but you have now been warned.
A normal file is really a process so it can be used as an I/O
device (see io
). Therefore when data is written to a
normal file, the sending of the data to the file process copies
all data that is not binaries. Opening the file in binary mode
and writing binaries is therefore recommended. If the file is
opened on another node, or if the file server runs as slave to
another node's, also binaries are copied.
Caching data to reduce the number of file operations, or rather the number of calls to the file driver, will generally increase performance. The following function writes 4 MBytes in 23 seconds on my machine:
create_file_slow(Name, N) when integer(N), N >= 0 -> {ok, FD} = file:open(Name, [raw, write, delayed_write, binary]), ok = create_file_slow(FD, 0, N), ok = ?FILE_MODULE:close(FD), ok. create_file_slow(FD, M, M) -> ok; create_file_slow(FD, M, N) -> ok = file:write(FD, <<M:32/unsigned>>), create_file_slow(FD, M+1, N).
The following functionallyequivalent function collects 1024
entries into a list of 128 32-byte binaries before each call to
file:write/2
and so does the same work in 0.52 seconds,
which is 44 times faster.
create_file(Name, N) when integer(N), N >= 0 -> {ok, FD} = file:open(Name, [raw, write, delayed_write, binary]), ok = create_file(FD, 0, N), ok = ?FILE_MODULE:close(FD), ok. create_file(FD, M, M) -> ok; create_file(FD, M, N) when M + 1024 =< N -> create_file(FD, M, M + 1024, []), create_file(FD, M + 1024, N); create_file(FD, M, N) -> create_file(FD, M, N, []). create_file(FD, M, M, R) -> ok = file:write(FD, R); create_file(FD, M, N0, R) when M + 8 =< N0 -> N1 = N0-1, N2 = N0-2, N3 = N0-3, N4 = N0-4, N5 = N0-5, N6 = N0-6, N7 = N0-7, N8 = N0-8, create_file(FD, M, N8, [<<N8:32/unsigned, N7:32/unsigned, N6:32/unsigned, N5:32/unsigned, N4:32/unsigned, N3:32/unsigned, N2:32/unsigned, N1:32/unsigned>> | R]); create_file(FD, M, N0, R) -> N1 = N0-1, create_file(FD, M, N1, [<<N1:32/unsigned>> | R]).
Trust only your own benchmarks. If the list length in
If the size of each binary is increased to 64 bytes, it will also run slightly faster, but the code will be twice as clumsy. In the current implementation are binaries larger than 64 bytes stored in memory common to all processes and not copied when sent between processes, while these smaller binaries are stored on the process heap and copied when sent like any other term. So, with a binary size of 68 bytes |
A raw file is really a port. When writing data to a port, it
is efficient to write a list of binaries. There is no need to
flatten a deep list before writing. On Unix hosts, scatter output,
which writes a set of buffers in one operation, is used when
possible. In this way
file:write(FD, [Bin1, Bin2 | Bin3])
will write the
contents of the binaries without copying the data at all except
for perhaps deep down in the operating system kernel.
For raw files, pwrite/2
and pread/2
are
efficiently implemented. The file driver is called only once for
the whole operation, and the list iteration is done in
the file driver.
The options delayed_write
and read_ahead
to
file:open/2
makes the file driver cache data to reduce
the number of operating system calls. The function
create_file/2
in the example above takes 60 seconds
seconds without the delayed_write
option, which is 2.6
times slower.
And, as a really bad example, create_file_slow/2
above
without the raw
, binary
and delayed_write
options, that is it calls file:open(Name, [write])
, needs
1 min 20 seconds for the job, which is 3.5 times slower than the
first example, and 150 times slower than the optimized
create_file/2
.
If an error occurs when accessing an open file with the io
module, the process which handles the file will exit. The dead file process might hang if a process tries to access it later. This will be fixed in a future release.
filename(3)