1file(3) Erlang Module Definition file(3)
2
6 file - File interface module.
7
9 This module provides an interface to the file system.
10 Warning:
12 File operations are only guaranteed to appear atomic when going through
13 the same file server. A NIF or other OS process may observe intermedi‐
14 ate steps on certain operations on some operating systems, eg. renaming
15 an existing file on Windows, or write_file_info/2 on any OS at the time
16 of writing.
17 Regarding filename encoding, the Erlang VM can operate in two modes.
20 The current mode can be queried using function native_name_encoding/0.
21 It returns latin1 or utf8.
22 In latin1 mode, the Erlang VM does not change the encoding of file‐
24 names. In utf8 mode, filenames can contain Unicode characters greater
25 than 255 and the VM converts filenames back and forth to the native
26 filename encoding (usually UTF-8, but UTF-16 on Windows).
27 The default mode depends on the operating system. Windows, MacOS X and
29 Android enforce consistent filename encoding and therefore the VM uses
30 utf8 mode.
31 On operating systems with transparent naming (for example, all Unix
33 systems except MacOS X), default is utf8 if the terminal supports
34 UTF-8, otherwise latin1. The default can be overridden using +fnl (to
35 force latin1 mode) or +fnu (to force utf8 mode) when starting erl.
36 On operating systems with transparent naming, files can be inconsis‐
38 tently named, for example, some files are encoded in UTF-8 while others
39 are encoded in ISO Latin-1. The concept of raw filenames is introduced
40 to handle file systems with inconsistent naming when running in utf8
41 mode.
42 A raw filename is a filename specified as a binary. The Erlang VM does
44 not translate a filename specified as a binary on systems with trans‐
45 parent naming.
46 When running in utf8 mode, functions list_dir/1 and read_link/1 never
48 return raw filenames. To return all filenames including raw filenames,
49 use functions list_dir_all/1 and read_link_all/1.
50 See also section Notes About Raw Filenames in the STDLIB User's Guide.
52 Note:
54 File operations used to accept filenames containing null characters
55 (integer value zero). This caused the name to be truncated and in some
56 cases arguments to primitive operations to be mixed up. Filenames con‐
57 taining null characters inside the filename are now rejected and will
58 cause primitive file operations fail.
59
62 deep_list() = [char() | atom() | deep_list()]
63 fd()
65 A file descriptor representing a file opened in raw mode.
67 filename() = string()
69 See also the documentation of the name_all() type.
71 filename_all() = string() | binary()
73 See also the documentation of the name_all() type.
75 io_device() = pid() | fd()
77 As returned by open/2; pid() is a process handling I/O-proto‐
79 cols.
80 name() = string() | atom() | deep_list()
82 If VM is in Unicode filename mode, string() and char() are al‐
84 lowed to be > 255. See also the documentation of the name_all()
85 type.
86 name_all() =
88 string() | atom() | deep_list() | (RawFilename :: binary())
89 If VM is in Unicode filename mode, characters are allowed to be
91 > 255. RawFilename is a filename not subject to Unicode transla‐
92 tion, meaning that it can contain characters not conforming to
93 the Unicode encoding expected from the file system (that is,
94 non-UTF-8 characters although the VM is started in Unicode file‐
95 name mode). Null characters (integer value zero) are not allowed
96 in filenames (not even at the end).
97 posix() =
99 eacces | eagain | ebadf | ebadmsg | ebusy | edeadlk |
100 edeadlock | edquot | eexist | efault | efbig | eftype |
101 eintr | einval | eio | eisdir | eloop | emfile | emlink |
102 emultihop | enametoolong | enfile | enobufs | enodev |
103 enolck | enolink | enoent | enomem | enospc | enosr | enostr |
104 enosys | enotblk | enotdir | enotsup | enxio | eopnotsupp |
105 eoverflow | eperm | epipe | erange | erofs | espipe | esrch |
106 estale | etxtbsy | exdev
107 An atom that is named from the POSIX error codes used in Unix,
109 and in the runtime libraries of most C compilers.
110 date_time() = calendar:datetime()
112 Must denote a valid date and time.
114 file_info() =
116 #file_info{size = integer() >= 0 | undefined,
117 type =
118 device | directory | other | regular |
119 symlink | undefined,
120 access =
121 read | write | read_write | none | undefined,
122 atime =
123 file:date_time() |
124 integer() >= 0 |
125 undefined,
126 mtime =
127 file:date_time() |
128 integer() >= 0 |
129 undefined,
130 ctime =
131 file:date_time() |
132 integer() >= 0 |
133 undefined,
134 mode = integer() >= 0 | undefined,
135 links = integer() >= 0 | undefined,
136 major_device = integer() >= 0 | undefined,
137 minor_device = integer() >= 0 | undefined,
138 inode = integer() >= 0 | undefined,
139 uid = integer() >= 0 | undefined,
140 gid = integer() >= 0 | undefined}
141 location() =
143 integer() |
144 {bof, Offset :: integer()} |
145 {cur, Offset :: integer()} |
146 {eof, Offset :: integer()} |
147 bof | cur | eof
148 mode() =
150 read | write | append | exclusive | raw | binary |
151 {delayed_write,
152 Size :: integer() >= 0,
153 Delay :: integer() >= 0} |
154 delayed_write |
155 {read_ahead, Size :: integer() >= 1} |
156 read_ahead | compressed |
157 {encoding, unicode:encoding()} |
158 sync
159 file_info_option() =
161 {time, local} | {time, universal} | {time, posix} | raw
162
164 advise(IoDevice, Offset, Length, Advise) -> ok | {error, Reason}
165 Types:
167 IoDevice = io_device()
169 Offset = Length = integer()
170 Advise = posix_file_advise()
171 Reason = posix() | badarg
172 posix_file_advise() =
173 normal | sequential | random | no_reuse | will_need |
174 dont_need
175 advise/4 can be used to announce an intention to access file
177 data in a specific pattern in the future, thus allowing the op‐
178 erating system to perform appropriate optimizations.
179 On some platforms, this function might have no effect.
181 allocate(File, Offset, Length) -> ok | {error, posix()}
183 Types:
185 File = io_device()
187 Offset = Length = integer() >= 0
188 allocate/3 can be used to preallocate space for a file.
190 This function only succeeds in platforms that provide this fea‐
192 ture.
193 change_group(Filename, Gid) -> ok | {error, Reason}
195 Types:
197 Filename = name_all()
199 Gid = integer()
200 Reason = posix() | badarg
201 Changes group of a file. See write_file_info/2.
203 change_mode(Filename, Mode) -> ok | {error, Reason}
205 Types:
207 Filename = name_all()
209 Mode = integer()
210 Reason = posix() | badarg
211 Changes permissions of a file. See write_file_info/2.
213 change_owner(Filename, Uid) -> ok | {error, Reason}
215 Types:
217 Filename = name_all()
219 Uid = integer()
220 Reason = posix() | badarg
221 Changes owner of a file. See write_file_info/2.
223 change_owner(Filename, Uid, Gid) -> ok | {error, Reason}
225 Types:
227 Filename = name_all()
229 Uid = Gid = integer()
230 Reason = posix() | badarg
231 Changes owner and group of a file. See write_file_info/2.
233 change_time(Filename, Mtime) -> ok | {error, Reason}
235 Types:
237 Filename = name_all()
239 Mtime = date_time()
240 Reason = posix() | badarg
241 Changes the modification and access times of a file. See
243 write_file_info/2.
244 change_time(Filename, Atime, Mtime) -> ok | {error, Reason}
246 Types:
248 Filename = name_all()
250 Atime = Mtime = date_time()
251 Reason = posix() | badarg
252 Changes the modification and last access times of a file. See
254 write_file_info/2.
255 close(IoDevice) -> ok | {error, Reason}
257 Types:
259 IoDevice = io_device()
261 Reason = posix() | badarg | terminated
262 Closes the file referenced by IoDevice. It mostly returns ok,
264 except for some severe errors such as out of memory.
265 Notice that if option delayed_write was used when opening the
267 file, close/1 can return an old write error and not even try to
268 close the file. See open/2.
269 consult(Filename) -> {ok, Terms} | {error, Reason}
271 Types:
273 Filename = name_all()
275 Terms = [term()]
276 Reason =
277 posix() |
278 badarg | terminated | system_limit |
279 {Line :: integer(), Mod :: module(), Term :: term()}
280 Reads Erlang terms, separated by '.', from Filename. Returns one
282 of the following:
283 {ok, Terms}:
285 The file was successfully read.
286 {error, atom()}:
288 An error occurred when opening the file or reading it. For a
289 list of typical error codes, see open/2.
290 {error, {Line, Mod, Term}}:
292 An error occurred when interpreting the Erlang terms in the
293 file. To convert the three-element tuple to an English de‐
294 scription of the error, use format_error/1.
295 Example:
297 f.txt: {person, "kalle", 25}.
299 {person, "pelle", 30}.
300 1> file:consult("f.txt").
302 {ok,[{person,"kalle",25},{person,"pelle",30}]}
303 The encoding of Filename can be set by a comment, as described
305 in epp(3).
306 copy(Source, Destination) -> {ok, BytesCopied} | {error, Reason}
308 copy(Source, Destination, ByteCount) ->
310 {ok, BytesCopied} | {error, Reason}
311 Types:
313 Source = Destination = io_device() | Filename | {Filename,
315 Modes}
316 Filename = name_all()
317 Modes = [mode()]
318 ByteCount = integer() >= 0 | infinity
319 BytesCopied = integer() >= 0
320 Reason = posix() | badarg | terminated
321 Copies ByteCount bytes from Source to Destination. Source and
323 Destination refer to either filenames or IO devices from, for
324 example, open/2. ByteCount defaults to infinity, denoting an in‐
325 finite number of bytes.
326 Argument Modes is a list of possible modes, see open/2, and de‐
328 faults to [].
329 If both Source and Destination refer to filenames, the files are
331 opened with [read, binary] and [write, binary] prepended to
332 their mode lists, respectively, to optimize the copy.
333 If Source refers to a filename, it is opened with read mode
335 prepended to the mode list before the copy, and closed when
336 done.
337 If Destination refers to a filename, it is opened with write
339 mode prepended to the mode list before the copy, and closed when
340 done.
341 Returns {ok, BytesCopied}, where BytesCopied is the number of
343 bytes that was copied, which can be less than ByteCount if end
344 of file was encountered on the source. If the operation fails,
345 {error, Reason} is returned.
346 Typical error reasons: as for open/2 if a file had to be opened,
348 and as for read/2 and write/2.
349 datasync(IoDevice) -> ok | {error, Reason}
351 Types:
353 IoDevice = io_device()
355 Reason = posix() | badarg | terminated
356 Ensures that any buffers kept by the operating system (not by
358 the Erlang runtime system) are written to disk. In many ways it
359 resembles fsync but it does not update some of the metadata of
360 the file, such as the access time. On some platforms this func‐
361 tion has no effect.
362 Applications that access databases or log files often write a
364 tiny data fragment (for example, one line in a log file) and
365 then call fsync() immediately to ensure that the written data is
366 physically stored on the hard disk. Unfortunately, fsync() al‐
367 ways initiates two write operations: one for the newly written
368 data and another one to update the modification time stored in
369 the inode. If the modification time is not a part of the trans‐
370 action concept, fdatasync() can be used to avoid unnecessary in‐
371 ode disk write operations.
372 Available only in some POSIX systems, this call results in a
374 call to fsync(), or has no effect in systems not providing the
375 fdatasync() syscall.
376 del_dir(Dir) -> ok | {error, Reason}
378 Types:
380 Dir = name_all()
382 Reason = posix() | badarg
383 Tries to delete directory Dir. The directory must be empty be‐
385 fore it can be deleted. Returns ok if successful.
386 Typical error reasons:
388 eacces:
390 Missing search or write permissions for the parent directo‐
391 ries of Dir.
392 eexist:
394 The directory is not empty.
395 enoent:
397 The directory does not exist.
398 enotdir:
400 A component of Dir is not a directory. On some platforms,
401 enoent is returned instead.
402 einval:
404 Attempt to delete the current directory. On some platforms,
405 eacces is returned instead.
406 del_dir_r(File) -> ok | {error, Reason}
408 Types:
410 File = name_all()
412 Reason = posix() | badarg
413 Deletes file or directory File. If File is a directory, its con‐
415 tents is first recursively deleted. Returns:
416 ok:
418 The operation completed without errors.
419 {error, posix()}:
421 An error occurred when accessing or deleting File. If some
422 file or directory under File could not be deleted, File can‐
423 not be deleted as it is non-empty, and {error, eexist} is
424 returned.
425 delete(Filename) -> ok | {error, Reason}
427 delete(Filename, Opts) -> ok | {error, Reason}
429 Types:
431 Filename = name_all()
433 Opts = [delete_option()]
434 Reason = posix() | badarg
435 delete_option() = raw
436 Tries to delete file Filename. Returns ok if successful.
438 If the option raw is set, the file server is not called. This
440 can be useful in particular during the early boot stage when the
441 file server is not yet registered, to still be able to delete
442 local files.
443 Typical error reasons:
445 enoent:
447 The file does not exist.
448 eacces:
450 Missing permission for the file or one of its parents.
451 eperm:
453 The file is a directory and the user is not superuser.
454 enotdir:
456 A component of the filename is not a directory. On some
457 platforms, enoent is returned instead.
458 einval:
460 Filename has an improper type, such as tuple.
461 Warning:
463 In a future release, a bad type for argument Filename will prob‐
464 ably generate an exception.
465 eval(Filename) -> ok | {error, Reason}
468 Types:
470 Filename = name_all()
472 Reason =
473 posix() |
474 badarg | terminated | system_limit |
475 {Line :: integer(), Mod :: module(), Term :: term()}
476 Reads and evaluates Erlang expressions, separated by '.' (or
478 ',', a sequence of expressions is also an expression) from File‐
479 name. The result of the evaluation is not returned; any expres‐
480 sion sequence in the file must be there for its side effect. Re‐
481 turns one of the following:
482 ok:
484 The file was read and evaluated.
485 {error, atom()}:
487 An error occurred when opening the file or reading it. For a
488 list of typical error codes, see open/2.
489 {error, {Line, Mod, Term}}:
491 An error occurred when interpreting the Erlang expressions
492 in the file. To convert the three-element tuple to an Eng‐
493 lish description of the error, use format_error/1.
494 The encoding of Filename can be set by a comment, as described
496 in epp(3).
497 eval(Filename, Bindings) -> ok | {error, Reason}
499 Types:
501 Filename = name_all()
503 Bindings = erl_eval:binding_struct()
504 Reason =
505 posix() |
506 badarg | terminated | system_limit |
507 {Line :: integer(), Mod :: module(), Term :: term()}
508 The same as eval/1, but the variable bindings Bindings are used
510 in the evaluation. For information about the variable bindings,
511 see erl_eval(3).
512 format_error(Reason) -> Chars
514 Types:
516 Reason =
518 posix() |
519 badarg | terminated | system_limit |
520 {Line :: integer(), Mod :: module(), Term :: term()}
521 Chars = string()
522 Given the error reason returned by any function in this module,
524 returns a descriptive string of the error in English.
525 get_cwd() -> {ok, Dir} | {error, Reason}
527 Types:
529 Dir = filename()
531 Reason = posix()
532 Returns {ok, Dir}, where Dir is the current working directory of
534 the file server.
535 Note:
537 In rare circumstances, this function can fail on Unix. It can
538 occur if read permission does not exist for the parent directo‐
539 ries of the current directory.
540 A typical error reason:
543 eacces:
545 Missing read permission for one of the parents of the cur‐
546 rent directory.
547 get_cwd(Drive) -> {ok, Dir} | {error, Reason}
549 Types:
551 Drive = string()
553 Dir = filename()
554 Reason = posix() | badarg
555 Returns {ok, Dir} or {error, Reason}, where Dir is the current
557 working directory of the specified drive.
558 Drive is to be of the form "Letter:", for example, "c:".
560 Returns {error, enotsup} on platforms that have no concept of
562 current drive (Unix, for example).
563 Typical error reasons:
565 enotsup:
567 The operating system has no concept of drives.
568 eacces:
570 The drive does not exist.
571 einval:
573 The format of Drive is invalid.
574 list_dir(Dir) -> {ok, Filenames} | {error, Reason}
576 Types:
578 Dir = name_all()
580 Filenames = [filename()]
581 Reason =
582 posix() |
583 badarg |
584 {no_translation, Filename :: unicode:latin1_binary()}
585 Lists all files in a directory, except files with raw filenames.
587 Returns {ok, Filenames} if successful, otherwise {error, Rea‐
588 son}. Filenames is a list of the names of all the files in the
589 directory. The names are not sorted.
590 Typical error reasons:
592 eacces:
594 Missing search or write permissions for Dir or one of its
595 parent directories.
596 enoent:
598 The directory does not exist.
599 {no_translation, Filename}:
601 Filename is a binary() with characters coded in ISO Latin-1
602 and the VM was started with parameter +fnue.
603 list_dir_all(Dir) -> {ok, Filenames} | {error, Reason}
605 Types:
607 Dir = name_all()
609 Filenames = [filename_all()]
610 Reason = posix() | badarg
611 Lists all the files in a directory, including files with raw
613 filenames. Returns {ok, Filenames} if successful, otherwise {er‐
614 ror, Reason}. Filenames is a list of the names of all the files
615 in the directory. The names are not sorted.
616 Typical error reasons:
618 eacces:
620 Missing search or write permissions for Dir or one of its
621 parent directories.
622 enoent:
624 The directory does not exist.
625 make_dir(Dir) -> ok | {error, Reason}
627 Types:
629 Dir = name_all()
631 Reason = posix() | badarg
632 Tries to create directory Dir. Missing parent directories are
634 not created. Returns ok if successful.
635 Typical error reasons:
637 eacces:
639 Missing search or write permissions for the parent directo‐
640 ries of Dir.
641 eexist:
643 A file or directory named Dir exists already.
644 enoent:
646 A component of Dir does not exist.
647 enospc:
649 No space is left on the device.
650 enotdir:
652 A component of Dir is not a directory. On some platforms,
653 enoent is returned instead.
654 make_link(Existing, New) -> ok | {error, Reason}
656 Types:
658 Existing = New = name_all()
660 Reason = posix() | badarg
661 Makes a hard link from Existing to New on platforms supporting
663 links (Unix and Windows). This function returns ok if the link
664 was successfully created, otherwise {error, Reason}. On plat‐
665 forms not supporting links, {error,enotsup} is returned.
666 Typical error reasons:
668 eacces:
670 Missing read or write permissions for the parent directories
671 of Existing or New.
672 eexist:
674 New already exists.
675 enotsup:
677 Hard links are not supported on this platform.
678 make_symlink(Existing, New) -> ok | {error, Reason}
680 Types:
682 Existing = New = name_all()
684 Reason = posix() | badarg
685 Creates a symbolic link New to the file or directory Existing on
687 platforms supporting symbolic links (most Unix systems and Win‐
688 dows, beginning with Vista). Existing does not need to exist.
689 Returns ok if the link is successfully created, otherwise {er‐
690 ror, Reason}. On platforms not supporting symbolic links, {er‐
691 ror, enotsup} is returned.
692 Typical error reasons:
694 eacces:
696 Missing read or write permissions for the parent directories
697 of Existing or New.
698 eexist:
700 New already exists.
701 enotsup:
703 Symbolic links are not supported on this platform.
704 eperm:
706 User does not have privileges to create symbolic links (Se‐
707 CreateSymbolicLinkPrivilege on Windows).
708 native_name_encoding() -> latin1 | utf8
710 Returns the filename encoding mode. If it is latin1, the system
712 translates no filenames. If it is utf8, filenames are converted
713 back and forth to the native filename encoding (usually UTF-8,
714 but UTF-16 on Windows).
715 open(File, Modes) -> {ok, IoDevice} | {error, Reason}
717 Types:
719 File = Filename | iodata()
721 Filename = name_all()
722 Modes = [mode() | ram | directory]
723 IoDevice = io_device()
724 Reason = posix() | badarg | system_limit
725 Opens file File in the mode determined by Modes, which can con‐
727 tain one or more of the following options:
728 read:
730 The file, which must exist, is opened for reading.
731 write:
733 The file is opened for writing. It is created if it does not
734 exist. If the file exists and write is not combined with
735 read, the file is truncated.
736 append:
738 The file is opened for writing. It is created if it does not
739 exist. Every write operation to a file opened with append
740 takes place at the end of the file.
741 exclusive:
743 The file is opened for writing. It is created if it does not
744 exist. If the file exists, {error, eexist} is returned.
745 Warning:
747 This option does not guarantee exclusiveness on file systems
748 not supporting O_EXCL properly, such as NFS. Do not depend on
749 this option unless you know that the file system supports it
750 (in general, local file systems are safe).
751 raw:
754 Allows faster access to a file, as no Erlang process is
755 needed to handle the file. However, a file opened in this
756 way has the following limitations:
757 * The functions in the io module cannot be used, as they can
759 only talk to an Erlang process. Instead, use functions
760 read/2, read_line/1, and write/2.
761 * Especially if read_line/1 is to be used on a raw file, it
763 is recommended to combine this option with option
764 {read_ahead, Size} as line-oriented I/O is inefficient
765 without buffering.
766 * Only the Erlang process that opened the file can use it.
768 * A remote Erlang file server cannot be used. The computer
770 on which the Erlang node is running must have access to
771 the file system (directly or through NFS).
772 binary:
774 Read operations on the file return binaries rather than
775 lists.
776 {delayed_write, Size, Delay}:
778 Data in subsequent write/2 calls is buffered until at least
779 Size bytes are buffered, or until the oldest buffered data
780 is Delay milliseconds old. Then all buffered data is written
781 in one operating system call. The buffered data is also
782 flushed before some other file operation than write/2 is ex‐
783 ecuted.
784 The purpose of this option is to increase performance by re‐
786 ducing the number of operating system calls. Thus, the
787 write/2 calls must be for sizes significantly less than
788 Size, and not interspersed by too many other file opera‐
789 tions.
790 When this option is used, the result of write/2 calls can
792 prematurely be reported as successful, and if a write error
793 occurs, the error is reported as the result of the next file
794 operation, which is not executed.
795 For example, when delayed_write is used, after a number of
797 write/2 calls, close/1 can return {error, enospc}, as there
798 is not enough space on the disc for previously written data.
799 close/1 must probably be called again, as the file is still
800 open.
801 delayed_write:
803 The same as {delayed_write, Size, Delay} with reasonable de‐
804 fault values for Size and Delay (roughly some 64 KB, 2 sec‐
805 onds).
806 {read_ahead, Size}:
808 Activates read data buffering. If read/2 calls are for sig‐
809 nificantly less than Size bytes, read operations to the op‐
810 erating system are still performed for blocks of Size bytes.
811 The extra data is buffered and returned in subsequent read/2
812 calls, giving a performance gain as the number of operating
813 system calls is reduced.
814 The read_ahead buffer is also highly used by function
816 read_line/1 in raw mode, therefore this option is recom‐
817 mended (for performance reasons) when accessing raw files
818 using that function.
819 If read/2 calls are for sizes not significantly less than,
821 or even greater than Size bytes, no performance gain can be
822 expected.
823 read_ahead:
825 The same as {read_ahead, Size} with a reasonable default
826 value for Size (roughly some 64 KB).
827 compressed:
829 Makes it possible to read or write gzip compressed files.
830 Option compressed must be combined with read or write, but
831 not both. Notice that the file size obtained with
832 read_file_info/1 does probably not match the number of bytes
833 that can be read from a compressed file.
834 {encoding, Encoding}:
836 Makes the file perform automatic translation of characters
837 to and from a specific (Unicode) encoding. Notice that the
838 data supplied to write/2 or returned by read/2 still is
839 byte-oriented; this option denotes only how data is stored
840 in the disk file.
841 Depending on the encoding, different methods of reading and
843 writing data is preferred. The default encoding of latin1
844 implies using this module (file) for reading and writing
845 data as the interfaces provided here work with byte-oriented
846 data. Using other (Unicode) encodings makes the io(3) func‐
847 tions get_chars, get_line, and put_chars more suitable, as
848 they can work with the full Unicode range.
849 If data is sent to an io_device() in a format that cannot be
851 converted to the specified encoding, or if data is read by a
852 function that returns data in a format that cannot cope with
853 the character range of the data, an error occurs and the
854 file is closed.
855 Allowed values for Encoding:
857 latin1:
859 The default encoding. Bytes supplied to the file, that is,
860 write/2 are written "as is" on the file. Likewise, bytes
861 read from the file, that is, read/2 are returned "as is".
862 If module io(3) is used for writing, the file can only
863 cope with Unicode characters up to code point 255 (the ISO
864 Latin-1 range).
865 unicode or utf8:
867 Characters are translated to and from UTF-8 encoding be‐
868 fore they are written to or read from the file. A file
869 opened in this way can be readable using function read/2,
870 as long as no data stored on the file lies beyond the ISO
871 Latin-1 range (0..255), but failure occurs if the data
872 contains Unicode code points beyond that range. The file
873 is best read with the functions in the Unicode aware mod‐
874 ule io(3).
875 Bytes written to the file by any means are translated to
877 UTF-8 encoding before being stored on the disk file.
878 utf16 or {utf16,big}:
880 Works like unicode, but translation is done to and from
881 big endian UTF-16 instead of UTF-8.
882 {utf16,little}:
884 Works like unicode, but translation is done to and from
885 little endian UTF-16 instead of UTF-8.
886 utf32 or {utf32,big}:
888 Works like unicode, but translation is done to and from
889 big endian UTF-32 instead of UTF-8.
890 {utf32,little}:
892 Works like unicode, but translation is done to and from
893 little endian UTF-32 instead of UTF-8.
894 The Encoding can be changed for a file "on the fly" by using
896 function io:setopts/2. So a file can be analyzed in latin1
897 encoding for, for example, a BOM, positioned beyond the BOM
898 and then be set for the right encoding before further read‐
899 ing. For functions identifying BOMs, see module unicode(3).
900 This option is not allowed on raw files.
902 ram:
904 File must be iodata(). Returns an fd(), which lets module
905 file operate on the data in-memory as if it is a file.
906 sync:
908 On platforms supporting it, enables the POSIX O_SYNC syn‐
909 chronous I/O flag or its platform-dependent equivalent (for
910 example, FILE_FLAG_WRITE_THROUGH on Windows) so that writes
911 to the file block until the data is physically written to
912 disk. However, be aware that the exact semantics of this
913 flag differ from platform to platform. For example, none of
914 Linux or Windows guarantees that all file metadata are also
915 written before the call returns. For precise semantics,
916 check the details of your platform documentation. On plat‐
917 forms with no support for POSIX O_SYNC or equivalent, use of
918 the sync flag causes open to return {error, enotsup}.
919 directory:
921 Allows open to work on directories.
922 Returns:
924 {ok, IoDevice}:
926 The file is opened in the requested mode. IoDevice is a ref‐
927 erence to the file.
928 {error, Reason}:
930 The file cannot be opened.
931 IoDevice is really the pid of the process that handles the file.
933 This process monitors the process that originally opened the
934 file (the owner process). If the owner process terminates, the
935 file is closed and the process itself terminates too. An IoDe‐
936 vice returned from this call can be used as an argument to the
937 I/O functions (see io(3)).
938 Warning:
940 While this function can be used to open any file, we recommend
941 against using it for NFS-mounted files, FIFOs, devices, or simi‐
942 lar since they can cause IO threads to hang forever.
943 If your application needs to interact with these kinds of files
945 we recommend breaking out those parts to a port program instead.
946 Note:
949 In previous versions of file, modes were specified as one of the
950 atoms read, write, or read_write instead of a list. This is
951 still allowed for reasons of backwards compatibility, but is not
952 to be used for new code. Also note that read_write is not al‐
953 lowed in a mode list.
954 Typical error reasons:
957 enoent:
959 The file does not exist.
960 eacces:
962 Missing permission for reading the file or searching one of
963 the parent directories.
964 eisdir:
966 The named file is a directory.
967 enotdir:
969 A component of the filename is not a directory, or the file‐
970 name itself is not a directory if directory mode was speci‐
971 fied. On some platforms, enoent is returned instead.
972 enospc:
974 There is no space left on the device (if write access was
975 specified).
976 path_consult(Path, Filename) ->
978 {ok, Terms, FullName} | {error, Reason}
979 Types:
981 Path = [Dir]
983 Dir = Filename = name_all()
984 Terms = [term()]
985 FullName = filename_all()
986 Reason =
987 posix() |
988 badarg | terminated | system_limit |
989 {Line :: integer(), Mod :: module(), Term :: term()}
990 Searches the path Path (a list of directory names) until the
992 file Filename is found. If Filename is an absolute filename,
993 Path is ignored. Then reads Erlang terms, separated by '.', from
994 the file.
995 Returns one of the following:
997 {ok, Terms, FullName}:
999 The file is successfully read. FullName is the full name of
1000 the file.
1001 {error, enoent}:
1003 The file cannot be found in any of the directories in Path.
1004 {error, atom()}:
1006 An error occurred when opening the file or reading it. For a
1007 list of typical error codes, see open/2.
1008 {error, {Line, Mod, Term}}:
1010 An error occurred when interpreting the Erlang terms in the
1011 file. Use format_error/1 to convert the three-element tuple
1012 to an English description of the error.
1013 The encoding of Filename can be set by a comment as described in
1015 epp(3).
1016 path_eval(Path, Filename) -> {ok, FullName} | {error, Reason}
1018 Types:
1020 Path = [Dir :: name_all()]
1022 Filename = name_all()
1023 FullName = filename_all()
1024 Reason =
1025 posix() |
1026 badarg | terminated | system_limit |
1027 {Line :: integer(), Mod :: module(), Term :: term()}
1028 Searches the path Path (a list of directory names) until the
1030 file Filename is found. If Filename is an absolute filename,
1031 Path is ignored. Then reads and evaluates Erlang expressions,
1032 separated by '.' (or ',', a sequence of expressions is also an
1033 expression), from the file. The result of evaluation is not re‐
1034 turned; any expression sequence in the file must be there for
1035 its side effect.
1036 Returns one of the following:
1038 {ok, FullName}:
1040 The file is read and evaluated. FullName is the full name of
1041 the file.
1042 {error, enoent}:
1044 The file cannot be found in any of the directories in Path.
1045 {error, atom()}:
1047 An error occurred when opening the file or reading it. For a
1048 list of typical error codes, see open/2.
1049 {error, {Line, Mod, Term}}:
1051 An error occurred when interpreting the Erlang expressions
1052 in the file. Use format_error/1 to convert the three-element
1053 tuple to an English description of the error.
1054 The encoding of Filename can be set by a comment as described in
1056 epp(3).
1057 path_open(Path, Filename, Modes) ->
1059 {ok, IoDevice, FullName} | {error, Reason}
1060 Types:
1062 Path = [Dir :: name_all()]
1064 Filename = name_all()
1065 Modes = [mode() | directory]
1066 IoDevice = io_device()
1067 FullName = filename_all()
1068 Reason = posix() | badarg | system_limit
1069 Searches the path Path (a list of directory names) until the
1071 file Filename is found. If Filename is an absolute filename,
1072 Path is ignored. Then opens the file in the mode determined by
1073 Modes.
1074 Returns one of the following:
1076 {ok, IoDevice, FullName}:
1078 The file is opened in the requested mode. IoDevice is a ref‐
1079 erence to the file and FullName is the full name of the
1080 file.
1081 {error, enoent}:
1083 The file cannot be found in any of the directories in Path.
1084 {error, atom()}:
1086 The file cannot be opened.
1087 path_script(Path, Filename) ->
1089 {ok, Value, FullName} | {error, Reason}
1090 Types:
1092 Path = [Dir :: name_all()]
1094 Filename = name_all()
1095 Value = term()
1096 FullName = filename_all()
1097 Reason =
1098 posix() |
1099 badarg | terminated | system_limit |
1100 {Line :: integer(), Mod :: module(), Term :: term()}
1101 Searches the path Path (a list of directory names) until the
1103 file Filename is found. If Filename is an absolute filename,
1104 Path is ignored. Then reads and evaluates Erlang expressions,
1105 separated by '.' (or ',', a sequence of expressions is also an
1106 expression), from the file.
1107 Returns one of the following:
1109 {ok, Value, FullName}:
1111 The file is read and evaluated. FullName is the full name of
1112 the file and Value the value of the last expression.
1113 {error, enoent}:
1115 The file cannot be found in any of the directories in Path.
1116 {error, atom()}:
1118 An error occurred when opening the file or reading it. For a
1119 list of typical error codes, see open/2.
1120 {error, {Line, Mod, Term}}:
1122 An error occurred when interpreting the Erlang expressions
1123 in the file. Use format_error/1 to convert the three-element
1124 tuple to an English description of the error.
1125 The encoding of Filename can be set by a comment as described in
1127 epp(3).
1128 path_script(Path, Filename, Bindings) ->
1130 {ok, Value, FullName} | {error, Reason}
1131 Types:
1133 Path = [Dir :: name_all()]
1135 Filename = name_all()
1136 Bindings = erl_eval:binding_struct()
1137 Value = term()
1138 FullName = filename_all()
1139 Reason =
1140 posix() |
1141 badarg | terminated | system_limit |
1142 {Line :: integer(), Mod :: module(), Term :: term()}
1143 The same as path_script/2 but the variable bindings Bindings are
1145 used in the evaluation. See erl_eval(3) about variable bindings.
1146 pid2name(Pid) -> {ok, Filename} | undefined
1148 Types:
1150 Filename = filename_all()
1152 Pid = pid()
1153 If Pid is an I/O device, that is, a pid returned from open/2,
1155 this function returns the filename, or rather:
1156 {ok, Filename}:
1158 If the file server of this node is not a slave, the file was
1159 opened by the file server of this node (this implies that
1160 Pid must be a local pid) and the file is not closed. File‐
1161 name is the filename in flat string format.
1162 undefined:
1164 In all other cases.
1165 Warning:
1167 This function is intended for debugging only.
1168 position(IoDevice, Location) ->
1171 {ok, NewPosition} | {error, Reason}
1172 Types:
1174 IoDevice = io_device()
1176 Location = location()
1177 NewPosition = integer()
1178 Reason = posix() | badarg | terminated
1179 Sets the position of the file referenced by IoDevice to Loca‐
1181 tion. Returns {ok, NewPosition} (as absolute offset) if success‐
1182 ful, otherwise {error, Reason}. Location is one of the follow‐
1183 ing:
1184 Offset:
1186 The same as {bof, Offset}.
1187 {bof, Offset}:
1189 Absolute offset.
1190 {cur, Offset}:
1192 Offset from the current position.
1193 {eof, Offset}:
1195 Offset from the end of file.
1196 bof | cur | eof:
1198 The same as above with Offset 0.
1199 Notice that offsets are counted in bytes, not in characters. If
1201 the file is opened using some other encoding than latin1, one
1202 byte does not correspond to one character. Positioning in such a
1203 file can only be done to known character boundaries. That is, to
1204 a position earlier retrieved by getting a current position, to
1205 the beginning/end of the file or to some other position known to
1206 be on a correct character boundary by some other means (typi‐
1207 cally beyond a byte order mark in the file, which has a known
1208 byte-size).
1209 A typical error reason is:
1211 einval:
1213 Either Location is illegal, or it is evaluated to a negative
1214 offset in the file. Notice that if the resulting position is
1215 a negative value, the result is an error, and after the call
1216 the file position is undefined.
1217 pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason}
1219 Types:
1221 IoDevice = io_device()
1223 LocNums =
1224 [{Location :: location(), Number :: integer() >= 0}]
1225 DataL = [Data]
1226 Data = string() | binary() | eof
1227 Reason = posix() | badarg | terminated
1228 Performs a sequence of pread/3 in one operation, which is more
1230 efficient than calling them one at a time. Returns {ok, [Data,
1231 ...]} or {error, Reason}, where each Data, the result of the
1232 corresponding pread, is either a list or a binary depending on
1233 the mode of the file, or eof if the requested position is beyond
1234 end of file.
1235 As the position is specified as a byte-offset, take special cau‐
1237 tion when working with files where encoding is set to something
1238 else than latin1, as not every byte position is a valid charac‐
1239 ter boundary on such a file.
1240 pread(IoDevice, Location, Number) ->
1242 {ok, Data} | eof | {error, Reason}
1243 Types:
1245 IoDevice = io_device()
1247 Location = location()
1248 Number = integer() >= 0
1249 Data = string() | binary()
1250 Reason = posix() | badarg | terminated
1251 Combines position/2 and read/2 in one operation, which is more
1253 efficient than calling them one at a time.
1254 Location is only allowed to be an integer for raw and ram modes.
1256 The current position of the file after the operation is unde‐
1258 fined for raw mode and unchanged for ram mode.
1259 As the position is specified as a byte-offset, take special cau‐
1261 tion when working with files where encoding is set to something
1262 else than latin1, as not every byte position is a valid charac‐
1263 ter boundary on such a file.
1264 pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}}
1266 Types:
1268 IoDevice = io_device()
1270 LocBytes = [{Location :: location(), Bytes :: iodata()}]
1271 N = integer() >= 0
1272 Reason = posix() | badarg | terminated
1273 Performs a sequence of pwrite/3 in one operation, which is more
1275 efficient than calling them one at a time. Returns ok or {error,
1276 {N, Reason}}, where N is the number of successful writes done
1277 before the failure.
1278 When positioning in a file with other encoding than latin1, cau‐
1280 tion must be taken to set the position on a correct character
1281 boundary. For details, see position/2.
1282 pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason}
1284 Types:
1286 IoDevice = io_device()
1288 Location = location()
1289 Bytes = iodata()
1290 Reason = posix() | badarg | terminated
1291 Combines position/2 and write/2 in one operation, which is more
1293 efficient than calling them one at a time.
1294 Location is only allowed to be an integer for raw and ram modes.
1296 The current position of the file after the operation is unde‐
1298 fined for raw mode and unchanged for ram mode.
1299 When positioning in a file with other encoding than latin1, cau‐
1301 tion must be taken to set the position on a correct character
1302 boundary. For details, see position/2.
1303 read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}
1305 Types:
1307 IoDevice = io_device() | atom()
1309 Number = integer() >= 0
1310 Data = string() | binary()
1311 Reason =
1312 posix() |
1313 badarg | terminated |
1314 {no_translation, unicode, latin1}
1315 Reads Number bytes/characters from the file referenced by IoDe‐
1317 vice. The functions read/2, pread/3, and read_line/1 are the
1318 only ways to read from a file opened in raw mode (although they
1319 work for normally opened files, too).
1320 For files where encoding is set to something else than latin1,
1322 one character can be represented by more than one byte on the
1323 file. The parameter Number always denotes the number of charac‐
1324 ters read from the file, while the position in the file can be
1325 moved much more than this number when reading a Unicode file.
1326 Also, if encoding is set to something else than latin1, the
1328 read/3 call fails if the data contains characters larger than
1329 255, which is why module io(3) is to be preferred when reading
1330 such a file.
1331 The function returns:
1333 {ok, Data}:
1335 If the file was opened in binary mode, the read bytes are
1336 returned in a binary, otherwise in a list. The list or bi‐
1337 nary is shorter than the number of bytes requested if end of
1338 file was reached.
1339 eof:
1341 Returned if Number>0 and end of file was reached before any‐
1342 thing at all could be read.
1343 {error, Reason}:
1345 An error occurred.
1346 Typical error reasons:
1348 ebadf:
1350 The file is not opened for reading.
1351 {no_translation, unicode, latin1}:
1353 The file is opened with another encoding than latin1 and the
1354 data in the file cannot be translated to the byte-oriented
1355 data that this function returns.
1356 read_file(Filename) -> {ok, Binary} | {error, Reason}
1358 Types:
1360 Filename = name_all()
1362 Binary = binary()
1363 Reason = posix() | badarg | terminated | system_limit
1364 Returns {ok, Binary}, where Binary is a binary data object that
1366 contains the contents of Filename, or {error, Reason} if an er‐
1367 ror occurs.
1368 Typical error reasons:
1370 enoent:
1372 The file does not exist.
1373 eacces:
1375 Missing permission for reading the file, or for searching
1376 one of the parent directories.
1377 eisdir:
1379 The named file is a directory.
1380 enotdir:
1382 A component of the filename is not a directory. On some
1383 platforms, enoent is returned instead.
1384 enomem:
1386 There is not enough memory for the contents of the file.
1387 read_file_info(File) -> {ok, FileInfo} | {error, Reason}
1389 read_file_info(File, Opts) -> {ok, FileInfo} | {error, Reason}
1391 Types:
1393 File = name_all() | io_device()
1395 Opts = [file_info_option()]
1396 FileInfo = file_info()
1397 Reason = posix() | badarg
1398 Retrieves information about a file. Returns {ok, FileInfo} if
1400 successful, otherwise {error, Reason}. FileInfo is a record
1401 file_info, defined in the Kernel include file file.hrl. Include
1402 the following directive in the module from which the function is
1403 called:
1404 -include_lib("kernel/include/file.hrl").
1406 The time type returned in atime, mtime, and ctime is dependent
1408 on the time type set in Opts :: {time, Type} as follows:
1409 local:
1411 Returns local time.
1412 universal:
1414 Returns universal time.
1415 posix:
1417 Returns seconds since or before Unix time epoch, which is
1418 1970-01-01 00:00 UTC.
1419 Default is {time, local}.
1421 If the option raw is set, the file server is not called and only
1423 information about local files is returned. Note that this will
1424 break this module's atomicity guarantees as it can race with a
1425 concurrent call to write_file_info/1,2.
1426 This option has no effect when the function is given an I/O de‐
1428 vice instead of a file name. Use open/2 with the raw mode to ob‐
1429 tain a file descriptor first.
1430 Note:
1432 As file times are stored in POSIX time on most OS, it is faster
1433 to query file information with option posix.
1434 The record file_info contains the following fields:
1437 size = integer() >= 0:
1439 Size of file in bytes.
1440 type = device | directory | other | regular:
1442 The type of the file. Can also contain symlink when returned
1443 from read_link_info/1,2.
1444 access = read | write | read_write | none:
1446 The current system access to the file.
1447 atime = date_time() | integer() >= 0:
1449 The last time the file was read.
1450 mtime = date_time() | integer() >= 0:
1452 The last time the file was written.
1453 ctime = date_time() | integer() >=0:
1455 The interpretation of this time field depends on the operat‐
1456 ing system. On Unix, it is the last time the file or the in‐
1457 ode was changed. In Windows, it is the create time.
1458 mode = integer() >= 0:
1460 The file permissions as the sum of the following bit values:
1461 8#00400:
1463 read permission: owner
1464 8#00200:
1466 write permission: owner
1467 8#00100:
1469 execute permission: owner
1470 8#00040:
1472 read permission: group
1473 8#00020:
1475 write permission: group
1476 8#00010:
1478 execute permission: group
1479 8#00004:
1481 read permission: other
1482 8#00002:
1484 write permission: other
1485 8#00001:
1487 execute permission: other
1488 16#800:
1490 set user id on execution
1491 16#400:
1493 set group id on execution
1494 On Unix platforms, other bits than those listed above may be
1496 set.
1497 links = integer() >= 0:
1499 Number of links to the file (this is always 1 for file sys‐
1500 tems that have no concept of links).
1501 major_device = integer() >= 0:
1503 Identifies the file system where the file is located. In
1504 Windows, the number indicates a drive as follows: 0 means
1505 A:, 1 means B:, and so on.
1506 minor_device = integer() >= 0:
1508 Only valid for character devices on Unix. In all other
1509 cases, this field is zero.
1510 inode = integer() >= 0:
1512 Gives the inode number. On non-Unix file systems, this field
1513 is zero.
1514 uid = integer() >= 0:
1516 Indicates the owner of the file. On non-Unix file systems,
1517 this field is zero.
1518 gid = integer() >= 0:
1520 Gives the group that the owner of the file belongs to. On
1521 non-Unix file systems, this field is zero.
1522 Typical error reasons:
1524 eacces:
1526 Missing search permission for one of the parent directories
1527 of the file.
1528 enoent:
1530 The file does not exist.
1531 enotdir:
1533 A component of the filename is not a directory. On some
1534 platforms, enoent is returned instead.
1535 read_line(IoDevice) -> {ok, Data} | eof | {error, Reason}
1537 Types:
1539 IoDevice = io_device() | atom()
1541 Data = string() | binary()
1542 Reason =
1543 posix() |
1544 badarg | terminated |
1545 {no_translation, unicode, latin1}
1546 Reads a line of bytes/characters from the file referenced by
1548 IoDevice. Lines are defined to be delimited by the linefeed (LF,
1549 \n) character, but any carriage return (CR, \r) followed by a
1550 newline is also treated as a single LF character (the carriage
1551 return is silently ignored). The line is returned including the
1552 LF, but excluding any CR immediately followed by an LF. This be‐
1553 haviour is consistent with the behaviour of io:get_line/2. If
1554 end of file is reached without any LF ending the last line, a
1555 line with no trailing LF is returned.
1556 The function can be used on files opened in raw mode. However,
1558 it is inefficient to use it on raw files if the file is not
1559 opened with option {read_ahead, Size} specified. Thus, combining
1560 raw and {read_ahead, Size} is highly recommended when opening a
1561 text file for raw line-oriented reading.
1562 If encoding is set to something else than latin1, the
1564 read_line/1 call fails if the data contains characters larger
1565 than 255, why module io(3) is to be preferred when reading such
1566 a file.
1567 The function returns:
1569 {ok, Data}:
1571 One line from the file is returned, including the trailing
1572 LF, but with CRLF sequences replaced by a single LF (see
1573 above).
1574 If the file is opened in binary mode, the read bytes are re‐
1576 turned in a binary, otherwise in a list.
1577 eof:
1579 Returned if end of file was reached before anything at all
1580 could be read.
1581 {error, Reason}:
1583 An error occurred.
1584 Typical error reasons:
1586 ebadf:
1588 The file is not opened for reading.
1589 {no_translation, unicode, latin1}:
1591 The file is opened with another encoding than latin1 and the
1592 data on the file cannot be translated to the byte-oriented
1593 data that this function returns.
1594 read_link(Name) -> {ok, Filename} | {error, Reason}
1596 Types:
1598 Name = name_all()
1600 Filename = filename()
1601 Reason = posix() | badarg
1602 Returns {ok, Filename} if Name refers to a symbolic link that is
1604 not a raw filename, or {error, Reason} otherwise. On platforms
1605 that do not support symbolic links, the return value is {er‐
1606 ror,enotsup}.
1607 Typical error reasons:
1609 einval:
1611 Name does not refer to a symbolic link or the name of the
1612 file that it refers to does not conform to the expected en‐
1613 coding.
1614 enoent:
1616 The file does not exist.
1617 enotsup:
1619 Symbolic links are not supported on this platform.
1620 read_link_all(Name) -> {ok, Filename} | {error, Reason}
1622 Types:
1624 Name = name_all()
1626 Filename = filename_all()
1627 Reason = posix() | badarg
1628 Returns {ok, Filename} if Name refers to a symbolic link or {er‐
1630 ror, Reason} otherwise. On platforms that do not support sym‐
1631 bolic links, the return value is {error,enotsup}.
1632 Notice that Filename can be either a list or a binary.
1634 Typical error reasons:
1636 einval:
1638 Name does not refer to a symbolic link.
1639 enoent:
1641 The file does not exist.
1642 enotsup:
1644 Symbolic links are not supported on this platform.
1645 read_link_info(Name) -> {ok, FileInfo} | {error, Reason}
1647 read_link_info(Name, Opts) -> {ok, FileInfo} | {error, Reason}
1649 Types:
1651 Name = name_all()
1653 Opts = [file_info_option()]
1654 FileInfo = file_info()
1655 Reason = posix() | badarg
1656 Works like read_file_info/1,2 except that if Name is a symbolic
1658 link, information about the link is returned in the file_info
1659 record and the type field of the record is set to symlink.
1660 If the option raw is set, the file server is not called and only
1662 information about local files is returned. Note that this will
1663 break this module's atomicity guarantees as it can race with a
1664 concurrent call to write_file_info/1,2
1665 If Name is not a symbolic link, this function returns the same
1667 result as read_file_info/1. On platforms that do not support
1668 symbolic links, this function is always equivalent to
1669 read_file_info/1.
1670 rename(Source, Destination) -> ok | {error, Reason}
1672 Types:
1674 Source = Destination = name_all()
1676 Reason = posix() | badarg
1677 Tries to rename the file Source to Destination. It can be used
1679 to move files (and directories) between directories, but it is
1680 not sufficient to specify the destination only. The destination
1681 filename must also be specified. For example, if bar is a normal
1682 file and foo and baz are directories, rename("foo/bar", "baz")
1683 returns an error, but rename("foo/bar", "baz/bar") succeeds. Re‐
1684 turns ok if it is successful.
1685 Note:
1687 Renaming of open files is not allowed on most platforms (see
1688 eacces below).
1689 Typical error reasons:
1692 eacces:
1694 Missing read or write permissions for the parent directories
1695 of Source or Destination. On some platforms, this error is
1696 given if either Source or Destination is open.
1697 eexist:
1699 Destination is not an empty directory. On some platforms,
1700 also given when Source and Destination are not of the same
1701 type.
1702 einval:
1704 Source is a root directory, or Destination is a subdirectory
1705 of Source.
1706 eisdir:
1708 Destination is a directory, but Source is not.
1709 enoent:
1711 Source does not exist.
1712 enotdir:
1714 Source is a directory, but Destination is not.
1715 exdev:
1717 Source and Destination are on different file systems.
1718 script(Filename) -> {ok, Value} | {error, Reason}
1720 Types:
1722 Filename = name_all()
1724 Value = term()
1725 Reason =
1726 posix() |
1727 badarg | terminated | system_limit |
1728 {Line :: integer(), Mod :: module(), Term :: term()}
1729 Reads and evaluates Erlang expressions, separated by '.' (or
1731 ',', a sequence of expressions is also an expression), from the
1732 file.
1733 Returns one of the following:
1735 {ok, Value}:
1737 The file is read and evaluated. Value is the value of the
1738 last expression.
1739 {error, atom()}:
1741 An error occurred when opening the file or reading it. For a
1742 list of typical error codes, see open/2.
1743 {error, {Line, Mod, Term}}:
1745 An error occurred when interpreting the Erlang expressions
1746 in the file. Use format_error/1 to convert the three-element
1747 tuple to an English description of the error.
1748 The encoding of Filename can be set by a comment as described in
1750 epp(3).
1751 script(Filename, Bindings) -> {ok, Value} | {error, Reason}
1753 Types:
1755 Filename = name_all()
1757 Bindings = erl_eval:binding_struct()
1758 Value = term()
1759 Reason =
1760 posix() |
1761 badarg | terminated | system_limit |
1762 {Line :: integer(), Mod :: module(), Term :: term()}
1763 The same as script/1 but the variable bindings Bindings are used
1765 in the evaluation. See erl_eval(3) about variable bindings.
1766 sendfile(Filename, Socket) ->
1768 {ok, integer() >= 0} |
1769 {error, inet:posix() | closed | badarg | not_owner}
1770 Types:
1772 Filename = name_all()
1774 Socket =
1775 inet:socket() |
1776 socket:socket() |
1777 fun((iolist()) -> ok | {error, inet:posix() | closed})
1778 Sends the file Filename to Socket. Returns {ok, BytesSent} if
1780 successful, otherwise {error, Reason}.
1781 sendfile(RawFile, Socket, Offset, Bytes, Opts) ->
1783 {ok, integer() >= 0} |
1784 {error, inet:posix() | closed | badarg | not_owner}
1785 Types:
1787 RawFile = fd()
1789 Socket =
1790 inet:socket() |
1791 socket:socket() |
1792 fun((iolist()) -> ok | {error, inet:posix() | closed})
1793 Offset = Bytes = integer() >= 0
1794 Opts = [sendfile_option()]
1795 sendfile_option() =
1796 {chunk_size, integer() >= 0} | {use_threads, boolean()}
1797 Sends Bytes from the file referenced by RawFile beginning at
1799 Offset to Socket. Returns {ok, BytesSent} if successful, other‐
1800 wise {error, Reason}. If Bytes is set to 0 all data after the
1801 specified Offset is sent.
1802 The file used must be opened using the raw flag, and the process
1804 calling sendfile must be the controlling process of the socket.
1805 See gen_tcp:controlling_process/2 or module socket's level otp
1806 socket option controlling_process.
1807 If the OS used does not support non-blocking sendfile, an Erlang
1809 fallback using read/2 and gen_tcp:send/2 is used.
1810 The option list can contain the following options:
1812 chunk_size:
1814 The chunk size used by the Erlang fallback to send data. If
1815 using the fallback, set this to a value that comfortably
1816 fits in the systems memory. Default is 20 MB.
1817 set_cwd(Dir) -> ok | {error, Reason}
1819 Types:
1821 Dir = name() | EncodedBinary
1823 EncodedBinary = binary()
1824 Reason = posix() | badarg | no_translation
1825 Sets the current working directory of the file server to Dir.
1827 Returns ok if successful.
1828 The functions in the module file usually treat binaries as raw
1830 filenames, that is, they are passed "as is" even when the encod‐
1831 ing of the binary does not agree with native_name_encoding().
1832 However, this function expects binaries to be encoded according
1833 to the value returned by native_name_encoding().
1834 Typical error reasons are:
1836 enoent:
1838 The directory does not exist.
1839 enotdir:
1841 A component of Dir is not a directory. On some platforms,
1842 enoent is returned.
1843 eacces:
1845 Missing permission for the directory or one of its parents.
1846 badarg:
1848 Dir has an improper type, such as tuple.
1849 no_translation:
1851 Dir is a binary() with characters coded in ISO-latin-1 and
1852 the VM is operating with unicode filename encoding.
1853 Warning:
1855 In a future release, a bad type for argument Dir will probably
1856 generate an exception.
1857 sync(IoDevice) -> ok | {error, Reason}
1860 Types:
1862 IoDevice = io_device()
1864 Reason = posix() | badarg | terminated
1865 Ensures that any buffers kept by the operating system (not by
1867 the Erlang runtime system) are written to disk. On some plat‐
1868 forms, this function might have no effect.
1869 A typical error reason is:
1871 enospc:
1873 Not enough space left to write the file.
1874 truncate(IoDevice) -> ok | {error, Reason}
1876 Types:
1878 IoDevice = io_device()
1880 Reason = posix() | badarg | terminated
1881 Truncates the file referenced by IoDevice at the current posi‐
1883 tion. Returns ok if successful, otherwise {error, Reason}.
1884 write(IoDevice, Bytes) -> ok | {error, Reason}
1886 Types:
1888 IoDevice = io_device() | atom()
1890 Bytes = iodata()
1891 Reason = posix() | badarg | terminated
1892 Writes Bytes to the file referenced by IoDevice. This function
1894 is the only way to write to a file opened in raw mode (although
1895 it works for normally opened files too). Returns ok if success‐
1896 ful, and {error, Reason} otherwise.
1897 If the file is opened with encoding set to something else than
1899 latin1, each byte written can result in many bytes being written
1900 to the file, as the byte range 0..255 can represent anything be‐
1901 tween one and four bytes depending on value and UTF encoding
1902 type.
1903 Typical error reasons:
1905 ebadf:
1907 The file is not opened for writing.
1908 enospc:
1910 No space is left on the device.
1911 write_file(Filename, Bytes) -> ok | {error, Reason}
1913 Types:
1915 Filename = name_all()
1917 Bytes = iodata()
1918 Reason = posix() | badarg | terminated | system_limit
1919 Writes the contents of the iodata term Bytes to file Filename.
1921 The file is created if it does not exist. If it exists, the pre‐
1922 vious contents are overwritten. Returns ok if successful, other‐
1923 wise {error, Reason}.
1924 Typical error reasons:
1926 enoent:
1928 A component of the filename does not exist.
1929 enotdir:
1931 A component of the filename is not a directory. On some
1932 platforms, enoent is returned instead.
1933 enospc:
1935 No space is left on the device.
1936 eacces:
1938 Missing permission for writing the file or searching one of
1939 the parent directories.
1940 eisdir:
1942 The named file is a directory.
1943 write_file(Filename, Bytes, Modes) -> ok | {error, Reason}
1945 Types:
1947 Filename = name_all()
1949 Bytes = iodata()
1950 Modes = [mode()]
1951 Reason = posix() | badarg | terminated | system_limit
1952 Same as write_file/2, but takes a third argument Modes, a list
1954 of possible modes, see open/2. The mode flags binary and write
1955 are implicit, so they are not to be used.
1956 write_file_info(Filename, FileInfo) -> ok | {error, Reason}
1958 write_file_info(Filename, FileInfo, Opts) -> ok | {error, Reason}
1960 Types:
1962 Filename = name_all()
1964 Opts = [file_info_option()]
1965 FileInfo = file_info()
1966 Reason = posix() | badarg
1967 Changes file information. Returns ok if successful, otherwise
1969 {error, Reason}. FileInfo is a record file_info, defined in the
1970 Kernel include file file.hrl. Include the following directive in
1971 the module from which the function is called:
1972 -include_lib("kernel/include/file.hrl").
1974 The time type set in atime, mtime, and ctime depends on the time
1976 type set in Opts :: {time, Type} as follows:
1977 local:
1979 Interprets the time set as local.
1980 universal:
1982 Interprets it as universal time.
1983 posix:
1985 Must be seconds since or before Unix time epoch, which is
1986 1970-01-01 00:00 UTC.
1987 Default is {time, local}.
1989 If the option raw is set, the file server is not called and only
1991 information about local files is returned.
1992 The following fields are used from the record, if they are spec‐
1994 ified:
1995 atime = date_time() | integer() >= 0:
1997 The last time the file was read.
1998 mtime = date_time() | integer() >= 0:
2000 The last time the file was written.
2001 ctime = date_time() | integer() >= 0:
2003 On Unix, any value specified for this field is ignored (the
2004 "ctime" for the file is set to the current time). On Win‐
2005 dows, this field is the new creation time to set for the
2006 file.
2007 mode = integer() >= 0:
2009 The file permissions as the sum of the following bit values:
2010 8#00400:
2012 Read permission: owner
2013 8#00200:
2015 Write permission: owner
2016 8#00100:
2018 Execute permission: owner
2019 8#00040:
2021 Read permission: group
2022 8#00020:
2024 Write permission: group
2025 8#00010:
2027 Execute permission: group
2028 8#00004:
2030 Read permission: other
2031 8#00002:
2033 Write permission: other
2034 8#00001:
2036 Execute permission: other
2037 16#800:
2039 Set user id on execution
2040 16#400:
2042 Set group id on execution
2043 On Unix platforms, other bits than those listed above may be
2045 set.
2046 uid = integer() >= 0:
2048 Indicates the file owner. Ignored for non-Unix file systems.
2049 gid = integer() >= 0:
2051 Gives the group that the file owner belongs to. Ignored for
2052 non-Unix file systems.
2053 Typical error reasons:
2055 eacces:
2057 Missing search permission for one of the parent directories
2058 of the file.
2059 enoent:
2061 The file does not exist.
2062 enotdir:
2064 A component of the filename is not a directory. On some
2065 platforms, enoent is returned instead.
2066
2068 * eacces - Permission denied
2069 * eagain - Resource temporarily unavailable
2071 * ebadf - Bad file number
2073 * ebusy - File busy
2075 * edquot - Disk quota exceeded
2077 * eexist - File already exists
2079 * efault - Bad address in system call argument
2081 * efbig - File too large
2083 * eintr - Interrupted system call
2085 * einval - Invalid argument
2087 * eio - I/O error
2089 * eisdir - Illegal operation on a directory
2091 * eloop - Too many levels of symbolic links
2093 * emfile - Too many open files
2095 * emlink - Too many links
2097 * enametoolong - Filename too long
2099 * enfile - File table overflow
2101 * enodev - No such device
2103 * enoent - No such file or directory
2105 * enomem - Not enough memory
2107 * enospc - No space left on device
2109 * enotblk - Block device required
2111 * enotdir - Not a directory
2113 * enotsup - Operation not supported
2115 * enxio - No such device or address
2117 * eperm - Not owner
2119 * epipe - Broken pipe
2121 * erofs - Read-only file system
2123 * espipe - Invalid seek
2125 * esrch - No such process
2127 * estale - Stale remote file handle
2129 * exdev - Cross-domain link
2131
2133 For increased performance, raw files are recommended.
2134 A normal file is really a process so it can be used as an I/O device
2136 (see io). Therefore, when data is written to a normal file, the sending
2137 of the data to the file process, copies all data that are not binaries.
2138 Opening the file in binary mode and writing binaries is therefore rec‐
2139 ommended. If the file is opened on another node, or if the file server
2140 runs as slave to the file server of another node, also binaries are
2141 copied.
2142 Note:
2144 Raw files use the file system of the host machine of the node. For nor‐
2145 mal files (non-raw), the file server is used to find the files, and if
2146 the node is running its file server as slave to the file server of an‐
2147 other node, and the other node runs on some other host machine, they
2148 can have different file systems. However, this is seldom a problem.
2149 open/2 can be given the options delayed_write and read_ahead to turn on
2152 caching, which will reduce the number of operating system calls and
2153 greatly improve performance for small reads and writes. However, the
2154 overhead won't disappear completely and it's best to keep the number of
2155 file operations to a minimum. As a contrived example, the following
2156 function writes 4MB in 2.5 seconds when tested:
2157 create_file_slow(Name) ->
2159 {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2160 create_file_slow_1(Fd, 4 bsl 20),
2161 file:close(Fd).
2162 create_file_slow_1(_Fd, 0) ->
2164 ok;
2165 create_file_slow_1(Fd, M) ->
2166 ok = file:write(Fd, <<0>>),
2167 create_file_slow_1(Fd, M - 1).
2168 The following functionally equivalent code writes 128 bytes per call to
2170 write/2 and so does the same work in 0.08 seconds, which is roughly 30
2171 times faster:
2172 create_file(Name) ->
2174 {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2175 create_file_1(Fd, 4 bsl 20),
2176 file:close(Fd),
2177 ok.
2178 create_file_1(_Fd, 0) ->
2180 ok;
2181 create_file_1(Fd, M) when M >= 128 ->
2182 ok = file:write(Fd, <<0:(128)/unit:8>>),
2183 create_file_1(Fd, M - 128);
2184 create_file_1(Fd, M) ->
2185 ok = file:write(Fd, <<0:(M)/unit:8>>),
2186 create_file_1(Fd, M - 1).
2187 When writing data it's generally more efficient to write a list of bi‐
2189 naries rather than a list of integers. It is not needed to flatten a
2190 deep list before writing. On Unix hosts, scatter output, which writes a
2191 set of buffers in one operation, is used when possible. In this way
2192 write(FD, [Bin1, Bin2 | Bin3]) writes the contents of the binaries
2193 without copying the data at all, except for perhaps deep down in the
2194 operating system kernel.
2195 Warning:
2197 If an error occurs when accessing an open file with module io, the
2198 process handling the file exits. The dead file process can hang if a
2199 process tries to access it later. This will be fixed in a future re‐
2200 lease.
2201
2204 filename(3)
2205Ericsson AB kernel 8.1.3 file(3)