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 and atoms. 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
.
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
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
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, enotsupt}
on platforms
which have no concept of current drive
(Unix, for example).
Typical error reasons are:
enotsup
eacces
einval
Drive
is invalid.
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
Tries to delete the file Filename
. Returns ok
if successful.
Typical error reasons are:
enoent
eacces
eperm
enotdir
enoent
is returned instead.
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
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.
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
enoent
is returned instead.
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
enoent
is returned instead.
einval
eacces
is returned instead.
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
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 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
.
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.
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 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
.
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.
Searches the path Path
(a list of file names)
until the file Filename
is found.
It is opened and all the terms in it are read.
It 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.
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.
Searches the path Path
until the file Filename
is found. It is opened and all the expression sequences in
it are evaluated. It 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.
Opens the file Filename
in the mode determined by
ModeList
.
ModeList
may contain one or more of the following items:
read
write
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.
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).
path_open(Path, Filename, Mode)
Searches the path Path
for the file Filename
.
If the path of Filename
is absolute, Path
is ignored.
It 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
.
Closes the file referenced by IoDevice
. It returns
ok
.
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
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
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)
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)
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.
Truncates the file referenced by IoDevice
at
the current position. Returns ok
if successful,
otherwise {error, Reason}
.
Makes sure that any buffers kept by the operating system (not by the Erlang system) are written to disk. On some platforms, this function might have no effect .
Given the error reason returned by any function in this module, it returns a descriptive string of the error in English.
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)