![[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.
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:
enoenteacceseisdirenotdirenoent is returned instead.
enomemWrites 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.
enospceacceseisdirReturns {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, enotsupt} on platforms
which have no concept of current drive
(Unix, for example).
Typical error reasons are:
enotsupeacceseinvalDrive is invalid.
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.
eaccesTries to delete the file Filename. Returns ok
if successful.
Typical error reasons are:
enoenteaccesepermenotdirenoent 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:
eaccesSource or Destination.
On some platforms, this error is given if either Source
or Destination is open.
eexisteinvalSource 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.
Tries 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.
enospcenotdirenoent 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:
eaccesDirName.
eexistenoentenotdirenoent is returned instead.
einvaleacces 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:
eaccesDirName or
one of its parent directories.
enoentRetrieves 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 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.
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}}.
modeuidgidTypical error reasons:
eaccesenoentenotdirenoent 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:
readwriterawraw 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).
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}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}ebadfWrites 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:
ebadfenospcSets 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.
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)