1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
33
<modulesummary>File Interface Module</modulesummary>
35
<p>The module <c>file</c> provides an interface to the file system.</p>
36
<p>On operating systems with thread support, it is possible to let
37
file operations be performed in threads of their own, allowing
38
other Erlang processes to continue executing in parallel with
39
the file operations. See the command line flag
40
<c>+A</c> in <seealso marker="erts:erl">erl(1)</seealso>.</p>
44
<title>DATA TYPES</title>
46
iodata() = iolist() | binary()
47
iolist() = [char() | binary() | iolist()]
50
as returned by file:open/2, a process handling IO protocols
52
name() = string() | atom() | DeepList
53
DeepList = [char() | atom() | DeepList]
56
an atom which is named from the Posix error codes used in
57
Unix, and in the runtime libraries of most C compilers
59
ext_posix() = posix() | badarg
61
time() = {{Year, Month, Day}, {Hour, Minute, Second}}
62
Year = Month = Day = Hour = Minute = Second = int()
63
Must denote a valid date and time</code>
67
<name>change_group(Filename, Gid) -> ok | {error, Reason}</name>
68
<fsummary>Change group of a file</fsummary>
70
<v>Filename = name()</v>
72
<v>Reason = ext_posix()</v>
75
<p>Changes group of a file. See
76
<seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p>
80
<name>change_owner(Filename, Uid) -> ok | {error, Reason}</name>
81
<fsummary>Change owner of a file</fsummary>
83
<v>Filename = name()</v>
85
<v>Reason = ext_posix()</v>
88
<p>Changes owner of a file. See
89
<seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p>
93
<name>change_owner(Filename, Uid, Gid) -> ok | {error, Reason}</name>
94
<fsummary>Change owner and group of a file</fsummary>
96
<v>Filename = name()</v>
99
<v>Reason = ext_posix()</v>
102
<p>Changes owner and group of a file. See
103
<seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p>
107
<name>change_time(Filename, Mtime) -> ok | {error, Reason}</name>
108
<fsummary>Change the modification time of a file</fsummary>
110
<v>Filename = name()</v>
111
<v>Mtime = time()</v>
112
<v>Reason = ext_posix()</v>
115
<p>Changes the modification and access times of a file. See
116
<seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p>
120
<name>change_time(Filename, Mtime, Atime) -> ok | {error, Reason}</name>
121
<fsummary>Change the modification and last access time of a file</fsummary>
123
<v>Filename = name()</v>
124
<v>Mtime = Atime = time()</v>
125
<v>Reason = ext_posix()</v>
128
<p>Changes the modification and last access times of a file. See
129
<seealso marker="#write_file_info/2">write_file_info/2</seealso>.</p>
133
<name>close(IoDevice) -> ok | {error, Reason}</name>
134
<fsummary>Close a file</fsummary>
136
<v>IoDevice = io_device()</v>
137
<v>Reason = ext_posix() | terminated</v>
140
<p>Closes the file referenced by <c>IoDevice</c>. It mostly
141
returns <c>ok</c>, expect for some severe errors such as out
143
<p>Note that if the option <c>delayed_write</c> was
144
used when opening the file, <c>close/1</c> might return an
145
old write error and not even try to close the file. See
146
<seealso marker="#open/2">open/2</seealso>.</p>
150
<name>consult(Filename) -> {ok, Terms} | {error, Reason}</name>
151
<fsummary>Read Erlang terms from a file</fsummary>
153
<v>Filename = name()</v>
154
<v>Terms = [term()]</v>
155
<v>Reason = ext_posix() | terminated | system_limit
156
| {Line, Mod, Term}</v>
157
<v> Line, Mod, Term -- see below</v>
160
<p>Reads Erlang terms, separated by '.', from <c>Filename</c>.
161
Returns one of the following:</p>
163
<tag><c>{ok, Terms}</c></tag>
165
<p>The file was successfully read.</p>
167
<tag><c>{error, atom()}</c></tag>
169
<p>An error occurred when opening the file or reading it.
170
See <seealso marker="#open/2">open/2</seealso> for a list
171
of typical error codes.</p>
173
<tag><c>{error, {Line, Mod, Term}}</c></tag>
175
<p>An error occurred when interpreting the Erlang terms in
176
the file. Use <c>format_error/1</c> to convert
177
the three-element tuple to an English description of
183
f.txt: {person, "kalle", 25}.
184
{person, "pelle", 30}.</code>
186
1> <input>file:consult("f.txt").</input>
187
{ok,[{person,"kalle",25},{person,"pelle",30}]}</pre>
191
<name>copy(Source, Destination) -></name>
192
<name>copy(Source, Destination, ByteCount) -> {ok, BytesCopied} | {error, Reason}</name>
193
<fsummary>Copy file contents</fsummary>
195
<v>Source = Destination = io_device() | Filename | {Filename, Modes}</v>
196
<v> Filename = name()</v>
197
<v> Modes = [Mode] -- see open/2</v>
198
<v>ByteCount = int() >= 0 | infinity</v>
199
<v>BytesCopied = int()</v>
202
<p>Copies <c>ByteCount</c> bytes from <c>Source</c> to
203
<c>Destination</c>. <c>Source</c> and <c>Destination</c> refer
204
to either filenames or IO devices from e.g. <c>open/2</c>.
205
<c>ByteCount</c> defaults <c>infinity</c>, denoting an
206
infinite number of bytes.</p>
207
<p>The argument <c>Modes</c> is a list of possible modes, see
208
<seealso marker="#open/2">open/2</seealso>, and defaults to
210
<p>If both <c>Source</c> and <c>Destination</c> refer to
211
filenames, the files are opened with <c>[read, binary]</c>
212
and <c>[write, binary]</c> prepended to their mode lists,
213
respectively, to optimize the copy.</p>
214
<p>If <c>Source</c> refers to a filename, it is opened with
215
<c>read</c> mode prepended to the mode list before the copy,
216
and closed when done.</p>
217
<p>If <c>Destination</c> refers to a filename, it is opened
218
with <c>write</c> mode prepended to the mode list before
219
the copy, and closed when done.</p>
220
<p>Returns <c>{ok, BytesCopied}</c> where <c>BytesCopied</c> is
221
the number of bytes that actually was copied, which may be
222
less than <c>ByteCount</c> if end of file was encountered on
223
the source. If the operation fails, <c>{error, Reason}</c> is
225
<p>Typical error reasons: As for <c>open/2</c> if a file had to
226
be opened, and as for <c>read/2</c> and <c>write/2</c>.</p>
230
<name>del_dir(Dir) -> ok | {error, Reason}</name>
231
<fsummary>Delete a directory</fsummary>
234
<v>Reason = ext_posix()</v>
237
<p>Tries to delete the directory <c>Dir</c>. The directory must
238
be empty before it can be deleted. Returns <c>ok</c> if
240
<p>Typical error reasons are:</p>
242
<tag><c>eacces</c></tag>
244
<p>Missing search or write permissions for the parent
245
directories of <c>Dir</c>.</p>
247
<tag><c>eexist</c></tag>
249
<p>The directory is not empty.</p>
251
<tag><c>enoent</c></tag>
253
<p>The directory does not exist.</p>
255
<tag><c>enotdir</c></tag>
257
<p>A component of <c>Dir</c> is not a directory. On some
258
platforms, <c>enoent</c> is returned instead.</p>
260
<tag><c>einval</c></tag>
262
<p>Attempt to delete the current directory. On some
263
platforms, <c>eacces</c> is returned instead.</p>
269
<name>delete(Filename) -> ok | {error, Reason}</name>
270
<fsummary>Delete a file</fsummary>
272
<v>Filename = name()</v>
273
<v>Reason = ext_posix()</v>
276
<p>Tries to delete the file <c>Filename</c>. Returns <c>ok</c>
278
<p>Typical error reasons are:</p>
280
<tag><c>enoent</c></tag>
282
<p>The file does not exist.</p>
284
<tag><c>eacces</c></tag>
286
<p>Missing permission for the file or one of its parents.</p>
288
<tag><c>eperm</c></tag>
290
<p>The file is a directory and the user is not super-user.</p>
292
<tag><c>enotdir</c></tag>
294
<p>A component of the file name is not a directory. On some
295
platforms, <c>enoent</c> is returned instead.</p>
297
<tag><c>einval</c></tag>
299
<p><c>Filename</c> had an improper type, such as tuple.</p>
303
<p>In a future release, a bad type for the <c>Filename</c>
304
argument will probably generate an exception.</p>
310
<name>eval(Filename) -> ok | {error, Reason}</name>
311
<fsummary>Evaluate Erlang expressions in a file</fsummary>
313
<v>Filename = name()</v>
314
<v>Reason = ext_posix() | terminated | system_limit
315
| {Line, Mod, Term}</v>
316
<v> Line, Mod, Term -- see below</v>
319
<p>Reads and evaluates Erlang expressions, separated by '.' (or
320
',', a sequence of expressions is also an expression), from
321
<c>Filename</c>. The actual result of the evaluation is not
322
returned; any expression sequence in the file must be there
323
for its side effect. Returns one of the following:</p>
327
<p>The file was read and evaluated.</p>
329
<tag><c>{error, atom()}</c></tag>
331
<p>An error occurred when opening the file or reading it.
332
See <c>open/2</c> for a list of typical error codes.</p>
334
<tag><c>{error, {Line, Mod, Term}}</c></tag>
336
<p>An error occurred when interpreting the Erlang
337
expressions in the file. Use <c>format_error/1</c> to
338
convert the three-element tuple to an English description
345
<name>eval(Filename, Bindings) -> ok | {error, Reason}</name>
346
<fsummary>Evaluate Erlang expressions in a file</fsummary>
348
<v>Filename = name()</v>
349
<v>Bindings -- see erl_eval(3)</v>
350
<v>Reason = ext_posix() | terminated | system_limit
351
| {Line, Mod, Term}</v>
352
<v> Line, Mod, Term -- see eval/1</v>
355
<p>The same as <c>eval/1</c> but the variable bindings
356
<c>Bindings</c> are used in the evaluation. See
357
<seealso marker="stdlib:erl_eval">erl_eval(3)</seealso> about
358
variable bindings.</p>
362
<name>file_info(Filename) -> {ok, FileInfo} | {error, Reason}</name>
363
<fsummary>Get information about a file (deprecated)</fsummary>
365
<p>This function is obsolete. Use <c>read_file_info/1</c>
370
<name>format_error(Reason) -> Chars</name>
371
<fsummary>Return a descriptive string for an error reason</fsummary>
373
<v>Reason = atom() | {Line, Mod, Term}</v>
374
<v> Line, Mod, Term -- see eval/1</v>
375
<v>Chars = [char() | Chars]</v>
378
<p>Given the error reason returned by any function in this
379
module, returns a descriptive string of the error in English.</p>
383
<name>get_cwd() -> {ok, Dir} | {error, Reason}</name>
384
<fsummary>Get the current working directory</fsummary>
386
<v>Dir = string()</v>
387
<v>Reason = posix()</v>
390
<p>Returns <c>{ok, Dir}</c>, where <c>Dir</c> is the current
391
working directory of the file server.</p>
393
<p>In rare circumstances, this function can fail on Unix.
394
It may happen if read permission does not exist for
395
the parent directories of the current directory.</p>
397
<p>Typical error reasons are:</p>
399
<tag><c>eacces</c></tag>
401
<p>Missing read permission for one of the parents of
402
the current directory.</p>
408
<name>get_cwd(Drive) -> {ok, Dir} | {error, Reason}</name>
409
<fsummary>Get the current working directory for the drive specified</fsummary>
411
<v>Drive = string() -- see below</v>
412
<v>Dir = string()</v>
413
<v>Reason = ext_posix()</v>
416
<p><c>Drive</c> should be of the form "<c>Letter</c><c>:</c>",
417
for example "c:". Returns <c>{ok, Dir}</c> or
418
<c>{error, Reason}</c>, where <c>Dir</c> is the current
419
working directory of the drive specified.</p>
420
<p>This function returns <c>{error, enotsup}</c> on platforms
421
which have no concept of current drive (Unix, for example).</p>
422
<p>Typical error reasons are:</p>
424
<tag><c>enotsup</c></tag>
426
<p>The operating system have no concept of drives.</p>
428
<tag><c>eacces</c></tag>
430
<p>The drive does not exist.</p>
432
<tag><c>einval</c></tag>
434
<p>The format of <c>Drive</c> is invalid.</p>
440
<name>list_dir(Dir) -> {ok, Filenames} | {error, Reason}</name>
441
<fsummary>List files in a directory</fsummary>
444
<v>Filenames = [Filename]</v>
445
<v> Filename = string()</v>
446
<v>Reason = ext_posix()</v>
449
<p>Lists all the files in a directory. Returns
450
<c>{ok, Filenames}</c> if successful. Otherwise, it returns
451
<c>{error, Reason}</c>. <c>Filenames</c> is a list of
452
the names of all the files in the directory. The names are
454
<p>Typical error reasons are:</p>
456
<tag><c>eacces</c></tag>
458
<p>Missing search or write permissions for <c>Dir</c> or
459
one of its parent directories.</p>
461
<tag><c>enoent</c></tag>
463
<p>The directory does not exist.</p>
469
<name>make_dir(Dir) -> ok | {error, Reason}</name>
470
<fsummary>Make a directory</fsummary>
473
<v>Reason = ext_posix()</v>
476
<p>Tries to create the directory <c>Dir</c>. Missing parent
477
directories are <em>not</em> created. Returns <c>ok</c> if
479
<p>Typical error reasons are:</p>
481
<tag><c>eacces</c></tag>
483
<p>Missing search or write permissions for the parent
484
directories of <c>Dir</c>.</p>
486
<tag><c>eexist</c></tag>
488
<p>There is already a file or directory named <c>Dir</c>.</p>
490
<tag><c>enoent</c></tag>
492
<p>A component of <c>Dir</c> does not exist.</p>
494
<tag><c>enospc</c></tag>
496
<p>There is a no space left on the device.</p>
498
<tag><c>enotdir</c></tag>
500
<p>A component of <c>Dir</c> is not a directory. On some
501
platforms, <c>enoent</c> is returned instead.</p>
507
<name>make_link(Existing, New) -> ok | {error, Reason}</name>
508
<fsummary>Make a hard link to a file</fsummary>
510
<v>Existing = New = name()</v>
511
<v>Reason = ext_posix()</v>
514
<p>Makes a hard link from <c>Existing</c> to <c>New</c>, on
515
platforms that support links (Unix). This function returns
516
<c>ok</c> if the link was successfully created, or
517
<c>{error, Reason}</c>. On platforms that do not support
518
links, <c>{error,enotsup}</c> is returned.</p>
519
<p>Typical error reasons:</p>
521
<tag><c>eacces</c></tag>
523
<p>Missing read or write permissions for the parent
524
directories of <c>Existing</c> or <c>New</c>.</p>
526
<tag><c>eexist</c></tag>
528
<p><c>New</c> already exists.</p>
530
<tag><c>enotsup</c></tag>
532
<p>Hard links are not supported on this platform.</p>
538
<name>make_symlink(Name1, Name2) -> ok | {error, Reason}</name>
539
<fsummary>Make a symbolic link to a file or directory</fsummary>
541
<v>Name1 = Name2 = name()</v>
542
<v>Reason = ext_posix()</v>
545
<p>This function creates a symbolic link <c>Name2</c> to
546
the file or directory <c>Name1</c>, on platforms that support
547
symbolic links (most Unix systems). <c>Name1</c> need not
548
exist. This function returns <c>ok</c> if the link was
549
successfully created, or <c>{error, Reason}</c>. On platforms
550
that do not support symbolic links, <c>{error, enotsup}</c>
552
<p>Typical error reasons:</p>
554
<tag><c>eacces</c></tag>
556
<p>Missing read or write permissions for the parent
557
directories of <c>Name1</c> or <c>Name2</c>.</p>
559
<tag><c>eexist</c></tag>
561
<p><c>Name2</c> already exists.</p>
563
<tag><c>enotsup</c></tag>
565
<p>Symbolic links are not supported on this platform.</p>
571
<name>open(Filename, Modes) -> {ok, IoDevice} | {error, Reason}</name>
572
<fsummary>Open a file</fsummary>
574
<v>Filename = name()</v>
575
<v>Modes = [Mode]</v>
576
<v> Mode = read | write | append | raw | binary | {delayed_write, Size, Delay} | delayed_write | {read_ahead, Size} | read_ahead | compressed</v>
577
<v> Size = Delay = int()</v>
578
<v>IoDevice = io_device()</v>
579
<v>Reason = ext_posix() | system_limit</v>
582
<p>Opens the file <c>Filename</c> in the mode determined by
583
<c>Modes</c>, which may contain one or more of the following
586
<tag><c>read</c></tag>
588
<p>The file, which must exist, is opened for reading.</p>
590
<tag><c>write</c></tag>
592
<p>The file is opened for writing. It is created if it does
593
not exist. If the file exists, and if <c>write</c> is not
594
combined with <c>read</c>, the file will be truncated.</p>
596
<tag><c>append</c></tag>
598
<p>The file will be opened for writing, and it will be
599
created if it does not exist. Every write operation to a
600
file opened with <c>append</c> will take place at
601
the end of the file.</p>
603
<tag><c>raw</c></tag>
605
<p>The <c>raw</c> option allows faster access to a file,
606
because no Erlang process is needed to handle the file.
607
However, a file opened in this way has the following
609
<list type="bulleted">
610
<item>The functions in the <c>io</c> module cannot be used,
611
because they can only talk to an Erlang process.
612
Instead, use the <c>read/2</c> and <c>write/2</c>
614
<item>Only the Erlang process which opened the file can use
616
<item>A remote Erlang file server cannot be used;
617
the computer on which the Erlang node is running must
618
have access to the file system (directly or through
622
<tag><c>binary</c></tag>
624
<p>This option can only be used if the <c>raw</c> option
625
is specified as well. When specified, read operations on
626
the file using the <c>read/2</c> function will return
627
binaries rather than lists.</p>
629
<tag><c>{delayed_write, Size, Delay}</c></tag>
631
<p>If this option is used, the data in subsequent
632
<c>write/2</c> calls is buffered until there are at least
633
<c>Size</c> bytes buffered, or until the oldest buffered
634
data is <c>Delay</c> milliseconds old. Then all buffered
635
data is written in one operating system call.
636
The buffered data is also flushed before some other file
637
operation than <c>write/2</c> is executed.</p>
638
<p>The purpose of this option is to increase performance
639
by reducing the number of operating system calls, so the
640
<c>write/2</c> calls should be for sizes significantly
641
less than <c>Size</c>, and not interspersed by to many
642
other file operations, for this to happen.</p>
643
<p>When this option is used, the result of <c>write/2</c>
644
calls may prematurely be reported as successful, and if
645
a write error should actually occur the error is
646
reported as the result of the next file operation, which
648
<p>For example, when <c>delayed_write</c> is used, after a
649
number of <c>write/2</c> calls, <c>close/1</c> might
650
return <c>{error, enospc}</c> because there was not enough
651
space on the disc for previously written data, and
652
<c>close/1</c> should probably be called again since the
653
file is still open.</p>
655
<tag><c>delayed_write</c></tag>
657
<p>The same as <c>{delayed_write, Size, Delay}</c> with
658
reasonable default values for <c>Size</c> and
659
<c>Delay</c>. (Roughly some 64 KBytes, 2 seconds)</p>
661
<tag><c>{read_ahead, Size}</c></tag>
663
<p>This option activates read data buffering. If
664
<c>read/2</c> calls are for significantly less than
665
<c>Size</c> bytes, read operations towards the operating
666
system are still performed for blocks of <c>Size</c>
667
bytes. The extra data is buffered and returned in
668
subsequent <c>read/2</c> calls, giving a performance gain
669
since the number of operating system calls is reduced.</p>
670
<p>If <c>read/2</c> calls are for sizes not significantly
671
less than, or even greater than <c>Size</c> bytes, no
672
performance gain can be expected.</p>
674
<tag><c>read_ahead</c></tag>
676
<p>The same as <c>{read_ahead, Size}</c> with a reasonable
677
default value for <c>Size</c>. (Roughly some 64 KBytes)</p>
679
<tag><c>compressed</c></tag>
681
<p>Makes it possible to read and write gzip compressed
682
files. Note that the file size obtained with
683
<c>read_file_info/1</c> will most probably not match the
684
number of bytes that can be read from a compressed file.</p>
689
<tag><c>{ok, IoDevice}</c></tag>
691
<p>The file has been opened in the requested mode.
692
<c>IoDevice</c> is a reference to the file.</p>
694
<tag><c>{error, Reason}</c></tag>
696
<p>The file could not be opened.</p>
699
<p><c>IoDevice</c> is really the pid of the process which
700
handles the file. This process is linked to the process
701
which originally opened the file. If any process to which
702
the <c>IoDevice</c> is linked terminates, the file will be
703
closed and the process itself will be terminated.
704
An <c>IoDevice</c> returned from this call can be used as an
705
argument to the IO functions (see
706
<seealso marker="stdlib:io">io(3)</seealso>).</p>
708
<p>In previous versions of <c>file</c>, modes were given
709
as one of the atoms <c>read</c>, <c>write</c>, or
710
<c>read_write</c> instead of a list. This is still allowed
711
for reasons of backwards compatibility, but should not be
712
used for new code. Also note that <c>read_write</c> is not
713
allowed in a mode list.</p>
715
<p>Typical error reasons:</p>
717
<tag><c>enoent</c></tag>
719
<p>The file does not exist.</p>
721
<tag><c>eacces</c></tag>
723
<p>Missing permission for reading the file or searching one
724
of the parent directories.</p>
726
<tag><c>eisdir</c></tag>
728
<p>The named file is not a regular file. It may be a
729
directory, a fifo, or a device.</p>
731
<tag><c>enotdir</c></tag>
733
<p>A component of the file name is not a directory. On some
734
platforms, <c>enoent</c> is returned instead.</p>
736
<tag><c>enospc</c></tag>
738
<p>There is a no space left on the device (if <c>write</c>
739
access was specified).</p>
745
<name>path_consult(Path, Filename) -> {ok, Terms, FullName} | {error, Reason}</name>
746
<fsummary>Read Erlang terms from a file</fsummary>
749
<v> Dir = name()</v>
750
<v>Filename = name()</v>
751
<v>Terms = [term()]</v>
752
<v>FullName = string()</v>
753
<v>Reason = ext_posix() | terminated | system_limit
754
| {Line, Mod, Term}</v>
755
<v> Line, Mod, Term -- see below</v>
758
<p>Searches the path <c>Path</c> (a list of directory names)
759
until the file <c>Filename</c> is found. If <c>Filename</c>
760
is an absolute filename, <c>Path</c> is ignored.
761
Then reads Erlang terms, separated by '.', from the file.
762
Returns one of the following:</p>
764
<tag><c>{ok, Terms, FullName}</c></tag>
766
<p>The file was successfully read. <c>FullName</c> is
767
the full name of the file.</p>
769
<tag><c>{error, enoent}</c></tag>
771
<p>The file could not be found in any of the directories in
774
<tag><c>{error, atom()}</c></tag>
776
<p>An error occurred when opening the file or reading it.
777
See <seealso marker="#open/2">open/2</seealso> for a list
778
of typical error codes.</p>
780
<tag><c>{error, {Line, Mod, Term}}</c></tag>
782
<p>An error occurred when interpreting the Erlang terms in
783
the file. Use <c>format_error/1</c> to convert
784
the three-element tuple to an English description of
791
<name>path_eval(Path, Filename) -> {ok, FullName} | {error, Reason}</name>
792
<fsummary>Evaluate Erlang expressions in a file</fsummary>
795
<v> Dir = name()</v>
796
<v>Filename = name()</v>
797
<v>FullName = string()</v>
798
<v>Reason = ext_posix() | terminated | system_limit
799
| {Line, Mod, Term}</v>
800
<v> Line, Mod, Term -- see below</v>
803
<p>Searches the path <c>Path</c> (a list of directory names)
804
until the file <c>Filename</c> is found. If <c>Filename</c>
805
is an absolute file name, <c>Path</c> is ignored. Then reads
806
and evaluates Erlang expressions, separated by '.' (or ',', a
807
sequence of expressions is also an expression), from the file.
808
The actual result of evaluation is not returned; any
809
expression sequence in the file must be there for its side
810
effect. Returns one of the following:</p>
812
<tag><c>{ok, FullName}</c></tag>
814
<p>The file was read and evaluated. <c>FullName</c> is
815
the full name of the file.</p>
817
<tag><c>{error, enoent}</c></tag>
819
<p>The file could not be found in any of the directories in
822
<tag><c>{error, atom()}</c></tag>
824
<p>An error occurred when opening the file or reading it.
825
See <seealso marker="#open/2">open/2</seealso> for a list
826
of typical error codes.</p>
828
<tag><c>{error, {Line, Mod, Term}}</c></tag>
830
<p>An error occurred when interpreting the Erlang
831
expressions in the file. Use <c>format_error/1</c> to
832
convert the three-element tuple to an English description
839
<name>path_open(Path, Filename, Modes) -> {ok, IoDevice, FullName} | {error, Reason}</name>
840
<fsummary>Open a file</fsummary>
843
<v> Dir = name()</v>
844
<v>Filename = name()</v>
845
<v>Modes = [Mode] -- see open/2</v>
846
<v>IoDevice = io_device()</v>
847
<v>FullName = string()</v>
848
<v>Reason = ext_posix() | system_limit</v>
851
<p>Searches the path <c>Path</c> (a list of directory names)
852
until the file <c>Filename</c> is found. If <c>Filename</c>
853
is an absolute file name, <c>Path</c> is ignored.
854
Then opens the file in the mode determined by <c>Modes</c>.
855
Returns one of the following:</p>
857
<tag><c>{ok, IoDevice, FullName}</c></tag>
859
<p>The file has been opened in the requested mode.
860
<c>IoDevice</c> is a reference to the file and
861
<c>FullName</c> is the full name of the file.</p>
863
<tag><c>{error, enoent}</c></tag>
865
<p>The file could not be found in any of the directories in
868
<tag><c>{error, atom()}</c></tag>
870
<p>The file could not be opened.</p>
876
<name>path_script(Path, Filename) -> {ok, Value, FullName} | {error, Reason}</name>
877
<fsummary>Evaluate and return the value of Erlang expressions in a file</fsummary>
880
<v> Dir = name()</v>
881
<v>Filename = name()</v>
882
<v>Value = term()</v>
883
<v>FullName = string()</v>
884
<v>Reason = ext_posix() | terminated | system_limit
885
| {Line, Mod, Term}</v>
886
<v> Line, Mod, Term -- see below</v>
889
<p>Searches the path <c>Path</c> (a list of directory names)
890
until the file <c>Filename</c> is found. If <c>Filename</c>
891
is an absolute file name, <c>Path</c> is ignored. Then reads
892
and evaluates Erlang expressions, separated by '.' (or ',', a
893
sequence of expressions is also an expression), from the file.
894
Returns one of the following:</p>
896
<tag><c>{ok, Value, FullName}</c></tag>
898
<p>The file was read and evaluated. <c>FullName</c> is
899
the full name of the file and <c>Value</c> the value of
900
the last expression.</p>
902
<tag><c>{error, enoent}</c></tag>
904
<p>The file could not be found in any of the directories in
907
<tag><c>{error, atom()}</c></tag>
909
<p>An error occurred when opening the file or reading it.
910
See <seealso marker="#open/2">open/2</seealso> for a list
911
of typical error codes.</p>
913
<tag><c>{error, {Line, Mod, Term}}</c></tag>
915
<p>An error occurred when interpreting the Erlang
916
expressions in the file. Use <c>format_error/1</c> to
917
convert the three-element tuple to an English description
924
<name>path_script(Path, Filename, Bindings) -> {ok, Value, FullName} | {error, Reason}</name>
925
<fsummary>Evaluate and return the value of Erlang expressions in a file</fsummary>
928
<v> Dir = name()</v>
929
<v>Filename = name()</v>
930
<v>Bindings -- see erl_eval(3)</v>
931
<v>Value = term()</v>
932
<v>FullName = string()</v>
933
<v>Reason = posix() | terminated | system_limit
934
| {Line, Mod, Term}</v>
935
<v> Line, Mod, Term -- see path_script/2</v>
938
<p>The same as <c>path_script/2</c> but the variable bindings
939
<c>Bindings</c> are used in the evaluation. See
940
<seealso marker="stdlib:erl_eval">erl_eval(3)</seealso> about
941
variable bindings.</p>
945
<name>pid2name(Pid) -> string() | undefined</name>
946
<fsummary>Return the name of the file handled by a pid</fsummary>
951
<p>If <c>Pid</c> is an IO device, that is, a pid returned from
952
<c>open/2</c>, this function returns the filename, or rather:</p>
954
<tag><c>{ok, Filename}</c></tag>
956
<p>If this node's file server is not a slave, the file was
957
opened by this node's file server, (this implies that
958
<c>Pid</c> must be a local pid) and the file is not
959
closed. <c>Filename</c> is the filename in flat string
962
<tag><c>undefined</c></tag>
964
<p>In all other cases.</p>
968
<p>This function is intended for debugging only.</p>
973
<name>position(IoDevice, Location) -> {ok, NewPosition} | {error, Reason}</name>
974
<fsummary>Set position in a file</fsummary>
976
<v>IoDevice = io_device()</v>
977
<v>Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof</v>
978
<v> Offset = int()</v>
979
<v>NewPosition = int()</v>
980
<v>Reason = ext_posix() | terminated</v>
983
<p>Sets the position of the file referenced by <c>IoDevice</c>
984
to <c>Location</c>. Returns <c>{ok, NewPosition}</c> (as
985
absolute offset) if successful, otherwise
986
<c>{error, Reason}</c>. <c>Location</c> is one of
989
<tag><c>Offset</c></tag>
991
<p>The same as <c>{bof, Offset}</c>.</p>
993
<tag><c>{bof, Offset}</c></tag>
995
<p>Absolute offset.</p>
997
<tag><c>{cur, Offset}</c></tag>
999
<p>Offset from the current position.</p>
1001
<tag><c>{eof, Offset}</c></tag>
1003
<p>Offset from the end of file.</p>
1005
<tag><c>bof | cur | eof</c></tag>
1007
<p>The same as above with <c>Offset</c> 0.</p>
1010
<p>Typical error reasons are:</p>
1012
<tag><c>einval</c></tag>
1014
<p>Either <c>Location</c> was illegal, or it evaluated to a
1015
negative offset in the file. Note that if the resulting
1016
position is a negative value, the result is an error, and
1017
after the call the file position is undefined.</p>
1023
<name>pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason}</name>
1024
<fsummary>Read from a file at certain positions</fsummary>
1026
<v>IoDevice = io_device()</v>
1027
<v>LocNums = [{Location, Number}]</v>
1028
<v> Location -- see position/2</v>
1029
<v> Number = int()</v>
1030
<v>DataL = [Data]</v>
1031
<v> Data = [char()] | binary()</v>
1032
<v>Reason = ext_posix() | terminated</v>
1035
<p>Performs a sequence of <c>pread/3</c> in one operation,
1036
which is more efficient than calling them one at a time.
1037
Returns <c>{ok, [Data, ...]}</c> or <c>{error, Reason}</c>,
1038
where each <c>Data</c>, the result of the corresponding
1039
<c>pread</c>, is either a list or a binary depending on
1040
the mode of the file, or <c>eof</c> if the requested position
1041
was beyond end of file.</p>
1045
<name>pread(IoDevice, Location, Number) -> {ok, Data} | eof | {error, Reason}</name>
1046
<fsummary>Read from a file at a certain position</fsummary>
1048
<v>IoDevice = io_device()</v>
1049
<v>Location -- see position/2</v>
1050
<v>Number = int()</v>
1051
<v>Data = [char()] | binary()</v>
1052
<v>Reason = ext_posix() | terminated</v>
1055
<p>Combines <c>position/2</c> and <c>read/2</c> in one
1056
operation, which is more efficient than calling them one at a
1057
time. If <c>IoDevice</c> has been opened in raw mode, some
1058
restrictions apply: <c>Location</c> is only allowed to be an
1059
integer; and the current position of the file is undefined
1060
after the operation.</p>
1064
<name>pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}}</name>
1065
<fsummary>Write to a file at certain positions</fsummary>
1067
<v>IoDevice = io_device()</v>
1068
<v>LocBytes = [{Location, Bytes}]</v>
1069
<v> Location -- see position/2</v>
1070
<v> Bytes = iodata()</v>
1072
<v>Reason = ext_posix() | terminated</v>
1075
<p>Performs a sequence of <c>pwrite/3</c> in one operation,
1076
which is more efficient than calling them one at a time.
1077
Returns <c>ok</c> or <c>{error, {N, Reason}}</c>, where
1078
<c>N</c> is the number of successful writes that was done
1079
before the failure.</p>
1083
<name>pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason}</name>
1084
<fsummary>Write to a file at a certain position</fsummary>
1086
<v>IoDevice = io_device()</v>
1087
<v>Location -- see position/2</v>
1088
<v>Bytes = iodata()</v>
1089
<v>Reason = ext_posix() | terminated</v>
1092
<p>Combines <c>position/2</c> and <c>write/2</c> in one
1093
operation, which is more efficient than calling them one at a
1094
time. If <c>IoDevice</c> has been opened in raw mode, some
1095
restrictions apply: <c>Location</c> is only allowed to be an
1096
integer; and the current position of the file is undefined
1097
after the operation.</p>
1101
<name>read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}</name>
1102
<fsummary>Read from a file</fsummary>
1104
<v>IoDevice = io_device()</v>
1105
<v>Number = int()</v>
1106
<v>Data = [char()] | binary()</v>
1107
<v>Reason = ext_posix() | terminated</v>
1110
<p>Reads <c>Number</c> bytes from the file referenced by
1111
<c>IoDevice</c>. This function is the only way to read from a
1112
file opened in raw mode (although it works for normally
1113
opened files, too). Returns:</p>
1115
<tag><c>{ok, Data}</c></tag>
1117
<p>If the file was opened in binary mode, the read bytes are
1118
returned in a binary, otherwise in a list. The list or
1119
binary will be shorter than the number of bytes requested
1120
if end of file was reached.</p>
1122
<tag><c>eof</c></tag>
1124
<p>Returned if <c>Number>0</c> and end of file was reached
1125
before anything at all could be read.</p>
1127
<tag><c>{error, Reason}</c></tag>
1129
<p>An error occurred.</p>
1132
<p>Typical error reasons:</p>
1134
<tag><c>ebadf</c></tag>
1136
<p>The file is not opened for reading.</p>
1142
<name>read_file(Filename) -> {ok, Binary} | {error, Reason}</name>
1143
<fsummary>Read a file</fsummary>
1145
<v>Filename = name()</v>
1146
<v>Binary = binary()</v>
1147
<v>Reason = ext_posix() | terminated | system_limit</v>
1150
<p>Returns <c>{ok, Binary}</c>, where <c>Binary</c> is a binary
1151
data object that contains the contents of <c>Filename</c>, or
1152
<c>{error, Reason}</c> if an error occurs.</p>
1153
<p>Typical error reasons:</p>
1155
<tag><c>enoent</c></tag>
1157
<p>The file does not exist.</p>
1159
<tag><c>eacces</c></tag>
1161
<p>Missing permission for reading the file, or for
1162
searching one of the parent directories.</p>
1164
<tag><c>eisdir</c></tag>
1166
<p>The named file is a directory.</p>
1168
<tag><c>enotdir</c></tag>
1170
<p>A component of the file name is not a directory. On some
1171
platforms, <c>enoent</c> is returned instead.</p>
1173
<tag><c>enomem</c></tag>
1175
<p>There is not enough memory for the contents of the file.</p>
1181
<name>read_file_info(Filename) -> {ok, FileInfo} | {error, Reason}</name>
1182
<fsummary>Get information about a file</fsummary>
1184
<v>Filename = name()</v>
1185
<v>FileInfo = #file_info{}</v>
1186
<v>Reason = ext_posix()</v>
1189
<p>Retrieves information about a file. Returns
1190
<c>{ok, FileInfo}</c> if successful, otherwise
1191
<c>{error, Reason}</c>. <c>FileInfo</c> is a record
1192
<c>file_info</c>, defined in the Kernel include file
1193
<c>file.hrl</c>. Include the following directive in the module
1194
from which the function is called:</p>
1196
-include_lib("kernel/include/file.hrl").</code>
1197
<p>The record <c>file_info</c> contains the following fields.</p>
1199
<tag><c>size = int()</c></tag>
1201
<p>Size of file in bytes.</p>
1203
<tag><c>type = device | directory | regular | other</c></tag>
1205
<p>The type of the file.</p>
1207
<tag><c>access = read | write | read_write | none</c></tag>
1209
<p>The current system access to the file.</p>
1211
<tag><c>atime = time()</c></tag>
1213
<p>The last (local) time the file was read.</p>
1215
<tag><c>mtime = time()</c></tag>
1217
<p>The last (local) time the file was written.</p>
1219
<tag><c>ctime = time()</c></tag>
1221
<p>The interpretation of this time field depends on
1222
the operating system. On Unix, it is the last time
1223
the file or the inode was changed. In Windows, it is
1224
the create time.</p>
1226
<tag><c>mode = int()</c></tag>
1228
<p>The file permissions as the sum of the following bit
1232
<item>read permission: owner</item>
1234
<item>write permission: owner</item>
1236
<item>execute permission: owner</item>
1238
<item>read permission: group</item>
1240
<item>write permission: group</item>
1242
<item>execute permission: group</item>
1244
<item>read permission: other</item>
1246
<item>write permission: other</item>
1248
<item>execute permission: other</item>
1250
<item>set user id on execution</item>
1252
<item>set group id on execution</item>
1254
<p>On Unix platforms, other bits than those listed above
1257
<tag><c>links = int()</c></tag>
1259
<p>Number of links to the file (this will always be 1 for
1260
file systems which have no concept of links).</p>
1262
<tag><c>major_device = int()</c></tag>
1264
<p>Identifies the file system where the file is located.
1265
In Windows, the number indicates a drive as follows:
1266
0 means A:, 1 means B:, and so on.</p>
1268
<tag><c>minor_device = int()</c></tag>
1270
<p>Only valid for character devices on Unix. In all other
1271
cases, this field is zero.</p>
1273
<tag><c>inode = int()</c></tag>
1275
<p>Gives the <c>inode</c> number. On non-Unix file systems,
1276
this field will be zero.</p>
1278
<tag><c>uid = int()</c></tag>
1280
<p>Indicates the owner of the file. Will be zero for
1281
non-Unix file systems.</p>
1283
<tag><c>gid = int()</c></tag>
1285
<p>Gives the group that the owner of the file belongs to.
1286
Will be zero for non-Unix file systems.</p>
1289
<p>Typical error reasons:</p>
1291
<tag><c>eacces</c></tag>
1293
<p>Missing search permission for one of the parent
1294
directories of the file.</p>
1296
<tag><c>enoent</c></tag>
1298
<p>The file does not exist.</p>
1300
<tag><c>enotdir</c></tag>
1302
<p>A component of the file name is not a directory. On some
1303
platforms, <c>enoent</c> is returned instead.</p>
1309
<name>read_link(Name) -> {ok, Filename} | {error, Reason}</name>
1310
<fsummary>See what a link is pointing to</fsummary>
1312
<v>Name = name()</v>
1313
<v>Filename = string()</v>
1314
<v>Reason = ext_posix()</v>
1317
<p>This function returns <c>{ok, Filename}</c> if <c>Name</c>
1318
refers to a symbolic link or <c>{error, Reason}</c> otherwise.
1319
On platforms that do not support symbolic links, the return
1320
value will be <c>{error,enotsup}</c>.</p>
1321
<p>Typical error reasons:</p>
1323
<tag><c>einval</c></tag>
1325
<p><c>Linkname</c> does not refer to a symbolic link.</p>
1327
<tag><c>enoent</c></tag>
1329
<p>The file does not exist.</p>
1331
<tag><c>enotsup</c></tag>
1333
<p>Symbolic links are not supported on this platform.</p>
1339
<name>read_link_info(Name) -> {ok, FileInfo} | {error, Reason}</name>
1340
<fsummary>Get information about a link or file</fsummary>
1342
<v>Name = name()</v>
1343
<v>FileInfo = #file_info{}, see read_file_info/1</v>
1344
<v>Reason = ext_posix()</v>
1347
<p>This function works like <c>read_file_info/1</c>, except that
1348
if <c>Name</c> is a symbolic link, information about the link
1349
will be returned in the <c>file_info</c> record and
1350
the <c>type</c> field of the record will be set to
1352
<p>If <c>Name</c> is not a symbolic link, this function returns
1353
exactly the same result as <c>read_file_info/1</c>.
1354
On platforms that do not support symbolic links, this function
1355
is always equivalent to <c>read_file_info/1</c>.</p>
1359
<name>rename(Source, Destination) -> ok | {error, Reason}</name>
1360
<fsummary>Rename a file</fsummary>
1362
<v>Source = Destination = name()</v>
1363
<v>Reason = ext_posix()</v>
1366
<p>Tries to rename the file <c>Source</c> to <c>Destination</c>.
1367
It can be used to move files (and directories) between
1368
directories, but it is not sufficient to specify
1369
the destination only. The destination file name must also be
1370
specified. For example, if <c>bar</c> is a normal file and
1371
<c>foo</c> and <c>baz</c> are directories,
1372
<c>rename("foo/bar", "baz")</c> returns an error, but
1373
<c>rename("foo/bar", "baz/bar")</c> succeeds. Returns
1374
<c>ok</c> if it is successful.</p>
1376
<p>Renaming of open files is not allowed on most platforms
1377
(see <c>eacces</c> below).</p>
1379
<p>Typical error reasons:</p>
1381
<tag><c>eacces</c></tag>
1383
<p>Missing read or write permissions for the parent
1384
directories of <c>Source</c> or <c>Destination</c>. On
1385
some platforms, this error is given if either
1386
<c>Source</c> or <c>Destination</c> is open.</p>
1388
<tag><c>eexist</c></tag>
1390
<p><c>Destination</c> is not an empty directory. On some
1391
platforms, also given when <c>Source</c> and
1392
<c>Destination</c> are not of the same type.</p>
1394
<tag><c>einval</c></tag>
1396
<p><c>Source</c> is a root directory, or <c>Destination</c>
1397
is a sub-directory of <c>Source</c>.</p>
1399
<tag><c>eisdir</c></tag>
1401
<p><c>Destination</c> is a directory, but <c>Source</c> is
1404
<tag><c>enoent</c></tag>
1406
<p><c>Source</c> does not exist.</p>
1408
<tag><c>enotdir</c></tag>
1410
<p><c>Source</c> is a directory, but <c>Destination</c> is
1413
<tag><c>exdev</c></tag>
1415
<p><c>Source</c> and <c>Destination</c> are on different
1422
<name>script(Filename) -> {ok, Value} | {error, Reason}</name>
1423
<fsummary>Evaluate and return the value of Erlang expressions in a file</fsummary>
1425
<v>Filename = name()</v>
1426
<v>Value = term()</v>
1427
<v>Reason = ext_posix() | terminated | system_limit
1428
| {Line, Mod, Term}</v>
1429
<v> Line, Mod, Term -- see below</v>
1432
<p>Reads and evaluates Erlang expressions, separated by '.' (or
1433
',', a sequence of expressions is also an expression), from
1434
the file. Returns one of the following:</p>
1436
<tag><c>{ok, Value}</c></tag>
1438
<p>The file was read and evaluated. <c>Value</c> is
1439
the value of the last expression.</p>
1441
<tag><c>{error, atom()}</c></tag>
1443
<p>An error occurred when opening the file or reading it.
1444
See <seealso marker="#open/2">open/2</seealso> for a list
1445
of typical error codes.</p>
1447
<tag><c>{error, {Line, Mod, Term}}</c></tag>
1449
<p>An error occurred when interpreting the Erlang
1450
expressions in the file. Use <c>format_error/1</c> to
1451
convert the three-element tuple to an English description
1458
<name>script(Filename, Bindings) -> {ok, Value} | {error, Reason}</name>
1459
<fsummary>Evaluate and return the value of Erlang expressions in a file</fsummary>
1461
<v>Filename = name()</v>
1462
<v>Bindings -- see erl_eval(3)</v>
1463
<v>Value = term()</v>
1464
<v>Reason = ext_posix() | terminated | system_limit
1465
| {Line, Mod, Term}</v>
1466
<v> Line, Mod, Term -- see below</v>
1469
<p>The same as <c>script/1</c> but the variable bindings
1470
<c>Bindings</c> are used in the evaluation. See
1471
<seealso marker="stdlib:erl_eval">erl_eval(3)</seealso> about
1472
variable bindings.</p>
1476
<name>set_cwd(Dir) -> ok | {error,Reason}</name>
1477
<fsummary>Set the current working directory</fsummary>
1480
<v>Reason = ext_posix()</v>
1483
<p>Sets the current working directory of the file server to
1484
<c>Dir</c>. Returns <c>ok</c> if successful.</p>
1485
<p>Typical error reasons are:</p>
1487
<tag><c>enoent</c></tag>
1489
<p>The directory does not exist.</p>
1491
<tag><c>enotdir</c></tag>
1493
<p>A component of <c>Dir</c> is not a directory. On some
1494
platforms, <c>enoent</c> is returned.</p>
1496
<tag><c>eacces</c></tag>
1498
<p>Missing permission for the directory or one of its
1501
<tag><c>badarg</c></tag>
1503
<p><c>Filename</c> had an improper type, such as tuple.</p>
1507
<p>In a future release, a bad type for the <c>Filename</c>
1508
argument will probably generate an exception.</p>
1514
<name>sync(IoDevice) -> ok | {error, Reason}</name>
1515
<fsummary>Synchronizes the in-memory state of a file with that on the physical medium</fsummary>
1517
<v>IoDevice = io_device()</v>
1518
<v>Reason = ext_posix() | terminated</v>
1521
<p>Makes sure that any buffers kept by the operating system
1522
(not by the Erlang runtime system) are written to disk. On
1523
some platforms, this function might have no effect.</p>
1524
<p>Typical error reasons are:</p>
1526
<tag><c>enospc</c></tag>
1528
<p>Not enough space left to write the file.</p>
1534
<name>truncate(IoDevice) -> ok | {error, Reason}</name>
1535
<fsummary>Truncate a file</fsummary>
1537
<v>IoDevice = io_device()</v>
1538
<v>Reason = ext_posix() | terminated</v>
1541
<p>Truncates the file referenced by <c>IoDevice</c> at
1542
the current position. Returns <c>ok</c> if successful,
1543
otherwise <c>{error, Reason}</c>.</p>
1547
<name>write(IoDevice, Bytes) -> ok | {error, Reason}</name>
1548
<fsummary>Write to a file</fsummary>
1550
<v>IoDevice = io_device()</v>
1551
<v>Bytes = iodata()</v>
1552
<v>Reason = ext_posix() | terminated</v>
1555
<p>Writes <c>Bytes</c> to the file referenced by
1556
<c>IoDevice</c>. This function is the only way to write to a
1557
file opened in raw mode (although it works for normally
1558
opened files, too). Returns <c>ok</c> if successful, and
1559
<c>{error, Reason}</c> otherwise.</p>
1560
<p>Typical error reasons are:</p>
1562
<tag><c>ebadf</c></tag>
1564
<p>The file is not opened for writing.</p>
1566
<tag><c>enospc</c></tag>
1568
<p>There is a no space left on the device.</p>
1574
<name>write_file(Filename, Bytes) -> ok | {error, Reason}</name>
1575
<fsummary>Write a file</fsummary>
1577
<v>Filename = name()</v>
1578
<v>Bytes = iodata()</v>
1579
<v>Reason = ext_posix() | terminated | system_limit</v>
1582
<p>Writes the contents of the iodata term <c>Bytes</c> to the
1583
file <c>Filename</c>. The file is created if it does not
1584
exist. If it exists, the previous contents are
1585
overwritten. Returns <c>ok</c>, or <c>{error, Reason}</c>.</p>
1586
<p>Typical error reasons are:</p>
1588
<tag><c>enoent</c></tag>
1590
<p>A component of the file name does not exist.</p>
1592
<tag><c>enotdir</c></tag>
1594
<p>A component of the file name is not a directory. On some
1595
platforms, <c>enoent</c> is returned instead.</p>
1597
<tag><c>enospc</c></tag>
1599
<p>There is a no space left on the device.</p>
1601
<tag><c>eacces</c></tag>
1603
<p>Missing permission for writing the file or searching one
1604
of the parent directories.</p>
1606
<tag><c>eisdir</c></tag>
1608
<p>The named file is a directory.</p>
1614
<name>write_file(Filename, Bytes, Modes) -> ok | {error, Reason}</name>
1615
<fsummary>Write a file</fsummary>
1617
<v>Filename = name()</v>
1618
<v>Bytes = iodata()</v>
1619
<v>Modes = [Mode] -- see open/2</v>
1620
<v>Reason = ext_posix() | terminated | system_limit</v>
1623
<p>Same as <c>write_file/2</c>, but takes a third argument
1624
<c>Modes</c>, a list of possible modes, see
1625
<seealso marker="#open/2">open/2</seealso>. The mode flags
1626
<c>binary</c> and <c>write</c> are implicit, so they should
1631
<name>write_file_info(Filename, FileInfo) -> ok | {error, Reason}</name>
1632
<fsummary>Change information about a file</fsummary>
1634
<v>Filename = name()</v>
1635
<v>FileInfo = #file_info{} -- see also read_file_info/1</v>
1636
<v>Reason = ext_posix()</v>
1639
<p>Change file information. Returns <c>ok</c> if successful,
1640
otherwise <c>{error, Reason}</c>. <c>FileInfo</c> is a record
1641
<c>file_info</c>, defined in the Kernel include file
1642
<c>file.hrl</c>. Include the following directive in the module
1643
from which the function is called:</p>
1645
-include_lib("kernel/include/file.hrl").</code>
1646
<p>The following fields are used from the record, if they are
1649
<tag><c>atime = time()</c></tag>
1651
<p>The last (local) time the file was read.</p>
1653
<tag><c>mtime = time()</c></tag>
1655
<p>The last (local) time the file was written.</p>
1657
<tag><c>ctime = time()</c></tag>
1659
<p>On Unix, any value give for this field will be ignored
1660
(the "ctime" for the file will be set to the current
1661
time). On Windows, this field is the new creation time to
1662
set for the file.</p>
1664
<tag><c>mode = int()</c></tag>
1666
<p>The file permissions as the sum of the following bit
1670
<item>read permission: owner</item>
1672
<item>write permission: owner</item>
1674
<item>execute permission: owner</item>
1676
<item>read permission: group</item>
1678
<item>write permission: group</item>
1680
<item>execute permission: group</item>
1682
<item>read permission: other</item>
1684
<item>write permission: other</item>
1686
<item>execute permission: other</item>
1688
<item>set user id on execution</item>
1690
<item>set group id on execution</item>
1692
<p>On Unix platforms, other bits than those listed above
1695
<tag><c>uid = int()</c></tag>
1697
<p>Indicates the owner of the file. Ignored for non-Unix
1700
<tag><c>gid = int()</c></tag>
1702
<p>Gives the group that the owner of the file belongs to.
1703
Ignored non-Unix file systems.</p>
1706
<p>Typical error reasons:</p>
1708
<tag><c>eacces</c></tag>
1710
<p>Missing search permission for one of the parent
1711
directories of the file.</p>
1713
<tag><c>enoent</c></tag>
1715
<p>The file does not exist.</p>
1717
<tag><c>enotdir</c></tag>
1719
<p>A component of the file name is not a directory. On some
1720
platforms, <c>enoent</c> is returned instead.</p>
1728
<title>POSIX Error Codes</title>
1729
<list type="bulleted">
1730
<item><c>eacces</c> - permission denied</item>
1731
<item><c>eagain</c> - resource temporarily unavailable</item>
1732
<item><c>ebadf</c> - bad file number</item>
1733
<item><c>ebusy</c> - file busy</item>
1734
<item><c>edquot</c> - disk quota exceeded</item>
1735
<item><c>eexist</c> - file already exists</item>
1736
<item><c>efault</c> - bad address in system call argument</item>
1737
<item><c>efbig</c> - file too large</item>
1738
<item><c>eintr</c> - interrupted system call</item>
1739
<item><c>einval</c> - invalid argument</item>
1740
<item><c>eio</c> - IO error</item>
1741
<item><c>eisdir</c> - illegal operation on a directory</item>
1742
<item><c>eloop</c> - too many levels of symbolic links</item>
1743
<item><c>emfile</c> - too many open files</item>
1744
<item><c>emlink</c> - too many links</item>
1745
<item><c>enametoolong</c> - file name too long</item>
1746
<item><c>enfile</c> - file table overflow</item>
1747
<item><c>enodev</c> - no such device</item>
1748
<item><c>enoent</c> - no such file or directory</item>
1749
<item><c>enomem</c> - not enough memory</item>
1750
<item><c>enospc</c> - no space left on device</item>
1751
<item><c>enotblk</c> - block device required</item>
1752
<item><c>enotdir</c> - not a directory</item>
1753
<item><c>enotsup</c> - operation not supported</item>
1754
<item><c>enxio</c> - no such device or address</item>
1755
<item><c>eperm</c> - not owner</item>
1756
<item><c>epipe</c> - broken pipe</item>
1757
<item><c>erofs</c> - read-only file system</item>
1758
<item><c>espipe</c> - invalid seek</item>
1759
<item><c>esrch</c> - no such process</item>
1760
<item><c>estale</c> - stale remote file handle</item>
1761
<item><c>exdev</c> - cross-domain link</item>
1766
<title>Performance</title>
1767
<p>Some operating system file operations, for example a
1768
<c>sync/1</c> or <c>close/1</c> on a huge file, may block their
1769
calling thread for seconds. If this befalls the emulator main
1770
thread, the response time is no longer in the order of
1771
milliseconds, depending on the definition of "soft" in soft
1772
real-time system.</p>
1773
<p>If the device driver thread pool is active, file operations are
1774
done through those threads instead, so the emulator can go on
1775
executing Erlang processes. Unfortunately, the time for serving a
1776
file operation increases due to the extra scheduling required
1777
from the operating system.</p>
1778
<p>If the device driver thread pool is disabled or of size 0, large
1779
file reads and writes are segmented into several smaller, which
1780
enables the emulator so server other processes during the file
1781
operation. This gives the same effect as when using the thread
1782
pool, but with larger overhead. Other file operations, for
1783
example <c>sync/1</c> or <c>close/1</c> on a huge file, still are
1785
<p>For increased performance, raw files are recommended. Raw files
1786
uses the file system of the node's host machine. For normal files
1787
(non-raw), the file server is used to find the files, and if
1788
the node is running its file server as slave to another node's,
1789
and the other node runs on some other host machine, they may have
1790
different file systems. This is seldom a problem, but you have
1791
now been warned.</p>
1792
<p>A normal file is really a process so it can be used as an IO
1793
device (see <c>io</c>). Therefore when data is written to a
1794
normal file, the sending of the data to the file process, copies
1795
all data that are not binaries. Opening the file in binary mode
1796
and writing binaries is therefore recommended. If the file is
1797
opened on another node, or if the file server runs as slave to
1798
another node's, also binaries are copied.</p>
1799
<p>Caching data to reduce the number of file operations, or rather
1800
the number of calls to the file driver, will generally increase
1801
performance. The following function writes 4 MBytes in 23
1802
seconds when tested:</p>
1803
<code type="none"><![CDATA[
1804
create_file_slow(Name, N) when integer(N), N >= 0 ->
1805
{ok, FD} = file:open(Name, [raw, write, delayed_write, binary]),
1806
ok = create_file_slow(FD, 0, N),
1807
ok = ?FILE_MODULE:close(FD),
1810
create_file_slow(FD, M, M) ->
1812
create_file_slow(FD, M, N) ->
1813
ok = file:write(FD, <<M:32/unsigned>>),
1814
create_file_slow(FD, M+1, N).]]></code>
1815
<p>The following, functionally equivalent, function collects 1024
1816
entries into a list of 128 32-byte binaries before each call to
1817
<c>file:write/2</c> and so does the same work in 0.52 seconds,
1818
which is 44 times faster.</p>
1819
<code type="none"><![CDATA[
1820
create_file(Name, N) when integer(N), N >= 0 ->
1821
{ok, FD} = file:open(Name, [raw, write, delayed_write, binary]),
1822
ok = create_file(FD, 0, N),
1823
ok = ?FILE_MODULE:close(FD),
1826
create_file(FD, M, M) ->
1828
create_file(FD, M, N) when M + 1024 =< N ->
1829
create_file(FD, M, M + 1024, []),
1830
create_file(FD, M + 1024, N);
1831
create_file(FD, M, N) ->
1832
create_file(FD, M, N, []).
1834
create_file(FD, M, M, R) ->
1835
ok = file:write(FD, R);
1836
create_file(FD, M, N0, R) when M + 8 =< N0 ->
1837
N1 = N0-1, N2 = N0-2, N3 = N0-3, N4 = N0-4,
1838
N5 = N0-5, N6 = N0-6, N7 = N0-7, N8 = N0-8,
1839
create_file(FD, M, N8,
1840
[<<N8:32/unsigned, N7:32/unsigned,
1841
N6:32/unsigned, N5:32/unsigned,
1842
N4:32/unsigned, N3:32/unsigned,
1843
N2:32/unsigned, N1:32/unsigned>> | R]);
1844
create_file(FD, M, N0, R) ->
1846
create_file(FD, M, N1, [<<N1:32/unsigned>> | R]).]]></code>
1848
<p>Trust only your own benchmarks. If the list length in
1849
<c>create_file/2</c> above is increased, it will run slightly
1850
faster, but consume more memory and cause more memory
1851
fragmentation. How much this affects your application is
1852
something that this simple benchmark can not predict.</p>
1853
<p>If the\011size of each binary is increased to 64 bytes, it will
1854
also run slightly faster, but the code will be twice as clumsy.
1855
In the current implementation are binaries larger than 64 bytes
1856
stored in memory common to all processes and not copied when
1857
sent between processes, while these smaller binaries are stored
1858
on the process heap and copied when sent like any other term.</p>
1859
<p>So, with a binary size of 68 bytes <c>create_file/2</c> runs
1860
30 percent slower then with 64 bytes, and will cause much more
1861
memory fragmentation. Note that if the binaries were to be sent
1862
between processes (for example a non-raw file) the results
1863
would probably be completely different.</p>
1865
<p>A raw file is really a port. When writing data to a port, it is
1866
efficient to write a list of binaries. There is no need to
1867
flatten a deep list before writing. On Unix hosts, scatter output,
1868
which writes a set of buffers in one operation, is used when
1869
possible. In this way <c>file:write(FD, [Bin1, Bin2 | Bin3])</c>
1870
will write the contents of the binaries without copying the data
1871
at all except for perhaps deep down in the operating system
1873
<p>For raw files, <c>pwrite/2</c> and <c>pread/2</c> are
1874
efficiently implemented. The file driver is called only once for
1875
the whole operation, and the list iteration is done in the file
1877
<p>The options <c>delayed_write</c> and <c>read_ahead</c> to
1878
<c>file:open/2</c> makes the file driver cache data to reduce
1879
the number of operating system calls. The function
1880
<c>create_file/2</c> in the example above takes 60 seconds
1881
seconds without the <c>delayed_write</c> option, which is 2.6
1883
<p>And, as a really bad example, <c>create_file_slow/2</c> above
1884
without the <c>raw</c>, <c>binary</c> and <c>delayed_write</c>
1885
options, that is it calls <c>file:open(Name, [write])</c>, needs
1886
1 min 20 seconds for the job, which is 3.5 times slower than
1887
the first example, and 150 times slower than the optimized
1888
<c>create_file/2</c>. </p>
1892
<title>Warnings</title>
1893
<p>If an error occurs when accessing an open file with the <c>io</c>
1894
module, the process which handles the file will exit. The dead
1895
file process might hang if a process tries to access it later.
1896
This will be fixed in a future release.</p>
1900
<title>SEE ALSO</title>
1901
<p><seealso marker="stdlib:filename">filename(3)</seealso></p>
added
removed
lib/kernel/doc/src/file.xml
