![[Erlang Systems]](min_head.gif)
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.
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 returns
ok.
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.
Tries to delete the directory DirName. The directory
must be empty before it can be deleted. Returns ok if
successful.
Typical error reasons are:
eaccesDirName.
eexistenoentenotdirDirName is not a directory. On some platforms,
enoent is returned instead.
einvaleacces is returned instead.
Tries to delete the file Filename. Returns ok
if successful.
Typical error reasons are:
enoenteaccesepermenotdirenoent 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.
 |
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}
SizeTypedevice, directory,
regular, or other.
Accessread, write, read_write, or none.
AccessTime{Year, Month, Day, Hour, Minute, Second}.
ModifyTime{Year, Month, Day, Hour, Minute, Second}.
UnUsed1, UnUsed2unused.
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:
eaccesDrive
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:
enotsupeacceseinvalDrive is invalid.
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:
eaccesDirName or
one of its parent directories.
enoentTries to create the directory DirName. Missing parent
directories are NOT created. Returns ok if
successful.
Typical error reasons are:
eaccesDirName.
eexistDirName.
enoentDirName does not exist.
enospcenotdirDirName 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:
eaccesExisting or New.
eexistnew already exists.
enotsupThis 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:
eaccesExisting or New.
eexistnew already exists.
enotsupOpens the file Filename in the mode determined by
ModeList.
ModeList may contain one or more of the following items:
readwriteread).
appendappend
will take place at the end of the file.
rawraw 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.
binaryraw 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:
enoenteacceseisdirenotdirenoent is returned instead.
enospcwrite 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.
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 || eofOffset 0.
Typical error reasons are:
einvalLocation 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.
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}eofeof is returned if the Number was greater than zero and end of file
was reached before anything at all could be read.
{error, Reason}ebadfReturns {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:
enoenteacceseisdirenotdirenoent is returned instead.
enomemRetrieves 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.
sizetypedevice, directory,
regular, or other.
accessread, 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}}.
modelinksmajor_deviceminor_deviceinodeinode number.
On non-Unix file systems, this field will be zero.
uidgidTypical error reasons:
eaccesenoentenotdirenoent 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:
einvalLinkname does not refer to a symbolic link.
enoentenotsupThis 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:
eaccesSource or Destination.
On some platforms, this error is given if either Source
or Destination is open.
eexistDestination is not an empty
directory.
On some platforms, also given when Source and
Destination are not of the same type.
einvalSource is a root directory, or Destination is a
sub-directory of Source.
eisdirDestination is a directory, but Source is not.
enoentSource does not exist.
enotdirSource is a directory, but Destination is not.
exdevSource and Destination are on different file systems.
Sets the current working directory of the file server to
DirName. Returns ok if successful.
Typical error reasons are:
enoentenotdirDirName is not a directory. On some platforms,
enoent is returned.
eaccesMakes 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 .
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:
ebadfenospcWrites 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:
enoentenotdirenoent is returned instead.
enospceacceseisdirwrite_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}}.
modeuidgidTypical error reasons:
eaccesenoentenotdirenoent is returned instead.
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)