This module provides an interface to the file system.
On operating systems with thread support,
file operations can be performed in threads of their own, allowing
other Erlang processes to continue executing in parallel with
the file operations. See command-line flag
Regarding filename encoding, the Erlang VM can operate in
two modes. The current mode can be queried using function
In
The default mode depends on the operating system. Windows and
MacOS X enforce consistent filename encoding and therefore the
VM uses
On operating systems with transparent naming (for example, all Unix
systems except MacOS X), default is
On operating systems with transparent naming, files can be
inconsistently named, for example, some files are encoded in UTF-8 while
others are encoded in ISO Latin-1. The concept of raw filenames is
introduced to handle file systems with inconsistent naming when running in
A raw filename is a filename specified as a binary. The Erlang VM does not translate a filename specified as a binary on systems with transparent naming.
When running in
See also section
File operations used to accept filenames containing null characters (integer value zero). This caused the name to be truncated and in some cases arguments to primitive operations to be mixed up. Filenames containing null characters inside the filename are now rejected and will cause primitive file operations fail.
Currently null characters at the end of the filename will be accepted by primitive file operations. Such filenames are however still documented as invalid. The implementation will also change in the future and reject such filenames.
A file descriptor representing a file opened in
See also the documentation of the
See also the documentation of the
As returned by
If VM is in Unicode filename mode,
If VM is in Unicode filename mode, characters
are allowed to be > 255.
An atom that is named from the POSIX error codes used in Unix, and in the runtime libraries of most C compilers.
Must denote a valid date and time.
On some platforms, this function might have no effect.
This function only succeeds in platforms that provide this feature. When it succeeds, space is preallocated for the file but the file size might not be updated. This behaviour depends on the preallocation implementation. To guarantee that the file size is updated, truncate the file to the new size.
Changes group of a file. See
Changes permissions of a file. See
Changes owner of a file. See
Changes owner and group of a file. See
Changes the modification and access times of a file. See
Changes the modification and last access times of a file. See
Closes the file referenced by
Notice that if option
Reads Erlang terms, separated by '.', from
The file was successfully read.
An error occurred when opening the file or reading it.
For a list of typical error codes, see
An error occurred when interpreting the Erlang terms in
the file. To convert the three-element tuple to an English
description of the error, use
Example:
f.txt: {person, "kalle", 25}.
{person, "pelle", 30}.
1> file:consult("f.txt"). {ok,[{person,"kalle",25},{person,"pelle",30}]}
The encoding of
Copies
Argument
If both
If
If
Returns
Typical error reasons: as for
Ensures that any buffers kept by the operating system
(not by the Erlang runtime system) are written to disk. In
many ways it resembles
Applications that access databases or log files often write
a tiny data fragment (for example, one line in a log file) and then
call
Available only in some POSIX systems, this call results in a
call to
Tries to delete directory
Typical error reasons:
Missing search or write permissions for the parent
directories of
The directory is not empty.
The directory does not exist.
A component of
Attempt to delete the current directory. On some
platforms,
Tries to delete file
Typical error reasons:
The file does not exist.
Missing permission for the file or one of its parents.
The file is a directory and the user is not superuser.
A component of the filename is not a directory. On some
platforms,
In a future release, a bad type for argument
Reads and evaluates Erlang expressions, separated by '.' (or
',', a sequence of expressions is also an expression) from
The file was read and evaluated.
An error occurred when opening the file or reading it.
For a list of typical error codes, see
An error occurred when interpreting the Erlang
expressions in the file. To convert the three-element tuple
to an English description of the error, use
The encoding of
The same as
Given the error reason returned by any function in this module, returns a descriptive string of the error in English.
Returns
In rare circumstances, this function can fail on Unix. It can occur if read permission does not exist for the parent directories of the current directory.
A typical error reason:
Missing read permission for one of the parents of the current directory.
Returns
Returns
Typical error reasons:
The operating system has no concept of drives.
The drive does not exist.
The format of
Lists all files in a directory, except files
with raw filenames. Returns
Typical error reasons:
Missing search or write permissions for
The directory does not exist.
Typical error reasons:
Missing search or write permissions for
The directory does not exist.
Tries to create directory
Typical error reasons:
Missing search or write permissions for the parent
directories of
A file or directory named
A component of
No space is left on the device.
A component of
Makes a hard link from
Typical error reasons:
Missing read or write permissions for the parent
directories of
Hard links are not supported on this platform.
Creates a symbolic link
Typical error reasons:
Missing read or write permissions for the parent directories
of
Symbolic links are not supported on this platform.
User does not have privileges to create symbolic links
(
Opens file
The file, which must exist, is opened for reading.
The file is opened for writing. It is created if it does
not exist. If the file exists and
The file is opened for writing. It is created if it does
not exist. Every write operation to a file opened with
The file is opened for writing. It is created if it does
not exist. If the file exists,
This option does not guarantee exclusiveness on
file systems not supporting
The functions in the
Especially if
Only the Erlang process that opened the file can use it.
A remote Erlang file server cannot be used. The computer on which the Erlang node is running must have access to the file system (directly or through NFS).
Read operations on the file return binaries rather than lists.
Data in subsequent
The purpose of this option is to increase performance
by reducing the number of operating system calls. Thus, the
When this option is used, the result of
For example, when
The same as
Activates read data buffering. If
The
If
The same as
Makes it possible to read or write gzip compressed
files. Option
Makes the file perform automatic translation of characters to
and from a specific (Unicode) encoding. Notice that the data supplied
to
Depending on the encoding, different methods of reading and writing
data is preferred. The default encoding of
If data is sent to an
Allowed values for
The default encoding. Bytes supplied to the file, that is,
Characters are translated to and from UTF-8 encoding before they are
written to or read from the file. A file opened in this way can be
readable using function
Bytes written to the file by any means are translated to UTF-8 encoding before being stored on the disk file.
Works like
Works like
Works like
Works like
The Encoding can be changed for a file "on the fly" by using function
This option is not allowed on
On platforms supporting it, enables the POSIX
Returns:
The file is opened in the requested mode.
The file cannot be opened.
In previous versions of
Typical error reasons:
The file does not exist.
Missing permission for reading the file or searching one of the parent directories.
The named file is not a regular file. It can be a directory, a FIFO, or a device.
A component of the filename is not a directory. On some
platforms,
There is no space left on the device (if
Searches the path
Returns one of the following:
The file is successfully read.
The file cannot be found in any of the directories in
An error occurred when opening the file or reading it.
For a list of typical error codes, see
An error occurred when interpreting the Erlang terms in
the file. Use
The encoding of
Searches the path
Returns one of the following:
The file is read and evaluated.
The file cannot be found in any of the directories in
An error occurred when opening the file or reading it.
For a list of typical error codes, see
An error occurred when interpreting the Erlang
expressions in the file. Use
The encoding of
Searches the path
Returns one of the following:
The file is opened in the requested mode.
The file cannot be found in any of the directories in
The file cannot be opened.
Searches the path
Returns one of the following:
The file is read and evaluated.
The file cannot be found in any of the directories in
An error occurred when opening the file or reading it.
For a list of typical error codes, see
An error occurred when interpreting the Erlang
expressions in the file. Use
The encoding of
The same as
If
If the file server of this node is not a slave, the file was
opened by the file server of this node (this implies that
In all other cases.
This function is intended for debugging only.
Sets the position of the file referenced by
The same as
Absolute offset.
Offset from the current position.
Offset from the end of file.
The same as above with
Notice that offsets are counted in bytes, not in characters. If the file
is opened using some other
A typical error reason is:
Either
Performs a sequence of
As the position is specified as a byte-offset, take special caution
when working with files where
Combines
As the position is specified as a byte-offset, take special caution
when working with files where
Performs a sequence of
When positioning in a file with other
Combines
When positioning in a file with other
Reads
For files where
Also, if
The function returns:
If the file was opened in binary mode, the read bytes are returned in a binary, otherwise in a list. The list or binary is shorter than the number of bytes requested if end of file was reached.
Returned if
An error occurred.
Typical error reasons:
The file is not opened for reading.
The file is opened with another
Returns
Typical error reasons:
The file does not exist.
Missing permission for reading the file, or for searching one of the parent directories.
The named file is a directory.
A component of the filename is not a directory. On some
platforms,
There is not enough memory for the contents of the file.
Retrieves information about a file. Returns
-include_lib("kernel/include/file.hrl").
The time type returned in
Returns local time.
Returns universal time.
Returns seconds since or before Unix time epoch, which is 1970-01-01 00:00 UTC.
Default is
If the option
As file times are stored in POSIX time on most OS, it is faster to
query file information with option
The record
Size of file in bytes.
The type of the file.
The current system access to the file.
The last time the file was read.
The last time the file was written.
The interpretation of this time field depends on
the operating system. On Unix, it is the last time
the file or the
The file permissions as the sum of the following bit values:
read permission: owner
write permission: owner
execute permission: owner
read permission: group
write permission: group
execute permission: group
read permission: other
write permission: other
execute permission: other
set user id on execution
set group id on execution
On Unix platforms, other bits than those listed above may be set.
Number of links to the file (this is always 1 for file systems that have no concept of links).
Identifies the file system where the file is located. In Windows, the number indicates a drive as follows: 0 means A:, 1 means B:, and so on.
Only valid for character devices on Unix. In all other cases, this field is zero.
Gives the
Indicates the owner of the file. On non-Unix file systems, this field is zero.
Gives the group that the owner of the file belongs to. On non-Unix file systems, this field is zero.
Typical error reasons:
Missing search permission for one of the parent directories of the file.
The file does not exist.
A component of the filename is not a directory. On some
platforms,
Reads a line of bytes/characters from the file referenced by
The function can be used on files opened in
If
The function returns:
One line from the file is returned, including the trailing LF, but with CRLF sequences replaced by a single LF (see above).
If the file is opened in binary mode, the read bytes are returned in a binary, otherwise in a list.
Returned if end of file was reached before anything at all could be read.
An error occurred.
Typical error reasons:
The file is not opened for reading.
The file is opened with another
Typical error reasons:
The file does not exist.
Symbolic links are not supported on this platform.
Returns
Notice that
Typical error reasons:
The file does not exist.
Symbolic links are not supported on this platform.
Works like
If the option
If
Tries to rename the file
Renaming of open files is not allowed on most platforms
(see
Typical error reasons:
Missing read or write permissions for the parent
directories of
Reads and evaluates Erlang expressions, separated by '.' (or ',', a sequence of expressions is also an expression), from the file.
Returns one of the following:
The file is read and evaluated.
An error occurred when opening the file or reading it.
For a list of typical error codes, see
An error occurred when interpreting the Erlang
expressions in the file. Use
The encoding of
The same as
Sends the file
Sends
The file used must be opened using the
If the OS used does not support
The option list can contain the following options:
The chunk size used by the Erlang fallback to send data. If using the fallback, set this to a value that comfortably fits in the systems memory. Default is 20 MB.
Instructs the emulator to use the
Sets the current working directory of the file server to
The functions in the module
Typical error reasons are:
The directory does not exist.
A component of
Missing permission for the directory or one of its parents.
In a future release, a bad type for argument
Ensures 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.
A typical error reason is:
Not enough space left to write the file.
Truncates the file referenced by
Writes
If the file is opened with
Typical error reasons:
The file is not opened for writing.
No space is left on the device.
Writes the contents of the
Typical error reasons:
A component of the filename does not exist.
A component of the filename is not a directory. On some
platforms,
No space is left on the device.
Missing permission for writing the file or searching one of the parent directories.
The named file is a directory.
Same as
Changes file information. Returns
-include_lib("kernel/include/file.hrl").
The time type set in
Interprets the time set as local.
Interprets it as universal time.
Must be seconds since or before Unix time epoch, which is 1970-01-01 00:00 UTC.
Default is
If the option
The following fields are used from the record, if they are specified:
The last time the file was read.
The last time the file was written.
On Unix, any value specified for this field is ignored (the "ctime" for the file is set to the current time). On Windows, this field is the new creation time to set for the file.
The file permissions as the sum of the following bit values:
Read permission: owner
Write permission: owner
Execute permission: owner
Read permission: group
Write permission: group
Execute permission: group
Read permission: other
Write permission: other
Execute permission: other
Set user id on execution
Set group id on execution
On Unix platforms, other bits than those listed above may be set.
Indicates the file owner. Ignored for non-Unix file systems.
Gives the group that the file owner belongs to. Ignored for non-Unix file systems.
Typical error reasons:
Missing search permission for one of the parent directories of the file.
The file does not exist.
A component of the filename is not a directory. On some
platforms,
Some operating system file operations, for example, a
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 because of 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 many smaller, which
enable the emulator to serve other processes during the file
operation. This has the same effect as when using the thread
pool, but with larger overhead. Other file operations, for
example,
For increased performance, raw files are recommended. Raw files use the file system of the host machine of the node.
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 the file server of another node, and the other node runs on some other host machine, they can have different file systems. However, this is seldom a problem.
A normal file is really a process so it can be used as an I/O
device (see
Caching data to reduce the number of file operations, or rather the number of calls to the file driver, generally increases performance. The following function writes 4 MBytes in 23 seconds when tested:
= 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, <>),
create_file_slow(FD, M+1, N).]]>
The following, functionally equivalent, function collects 1024
entries into a list of 128 32-byte binaries before each call to
= 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,
[<> | R]);
create_file(FD, M, N0, R) ->
N1 = N0-1,
create_file(FD, M, N1, [<> | R]).]]>
Trust only your own benchmarks. If the list length in
If the size of each binary is increased to 64 bytes, it also runs slightly faster, but the code is then twice as clumsy. In the current implementation, binaries larger than 64 bytes are 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. It is not needed 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
For raw files,
The options
As a bad example,
If an error occurs when accessing an open file with module