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 and MacOS X
29 enforce consistent filename encoding and therefore the VM uses utf8
30 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
84 allowed to be > 255. See also the documentation of the
85 name_all() 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 |
100 eagain |
101 ebadf |
102 ebadmsg |
103 ebusy |
104 edeadlk |
105 edeadlock |
106 edquot |
107 eexist |
108 efault |
109 efbig |
110 eftype |
111 eintr |
112 einval |
113 eio |
114 eisdir |
115 eloop |
116 emfile |
117 emlink |
118 emultihop |
119 enametoolong |
120 enfile |
121 enobufs |
122 enodev |
123 enolck |
124 enolink |
125 enoent |
126 enomem |
127 enospc |
128 enosr |
129 enostr |
130 enosys |
131 enotblk |
132 enotdir |
133 enotsup |
134 enxio |
135 eopnotsupp |
136 eoverflow |
137 eperm |
138 epipe |
139 erange |
140 erofs |
141 espipe |
142 esrch |
143 estale |
144 etxtbsy |
145 exdev
146 An atom that is named from the POSIX error codes used in Unix,
148 and in the runtime libraries of most C compilers.
149 date_time() = calendar:datetime()
151 Must denote a valid date and time.
153 file_info() =
155 #file_info{size = integer() >= 0 | undefined,
156 type =
157 device |
158 directory |
159 other |
160 regular |
161 symlink |
162 undefined,
163 access =
164 read | write | read_write | none | undefined,
165 atime =
166 file:date_time() |
167 integer() >= 0 |
168 undefined,
169 mtime =
170 file:date_time() |
171 integer() >= 0 |
172 undefined,
173 ctime =
174 file:date_time() |
175 integer() >= 0 |
176 undefined,
177 mode = integer() >= 0 | undefined,
178 links = integer() >= 0 | undefined,
179 major_device = integer() >= 0 | undefined,
180 minor_device = integer() >= 0 | undefined,
181 inode = integer() >= 0 | undefined,
182 uid = integer() >= 0 | undefined,
183 gid = integer() >= 0 | undefined}
184 location() =
186 integer() |
187 {bof, Offset :: integer()} |
188 {cur, Offset :: integer()} |
189 {eof, Offset :: integer()} |
190 bof |
191 cur |
192 eof
193 mode() =
195 read |
196 write |
197 append |
198 exclusive |
199 raw |
200 binary |
201 {delayed_write,
202 Size :: integer() >= 0,
203 Delay :: integer() >= 0} |
204 delayed_write |
205 {read_ahead, Size :: integer() >= 1} |
206 read_ahead |
207 compressed |
208 {encoding, unicode:encoding()} |
209 sync
210 file_info_option() =
212 {time, local} | {time, universal} | {time, posix} | raw
213
215 advise(IoDevice, Offset, Length, Advise) -> ok | {error, Reason}
216 Types:
218 IoDevice = io_device()
220 Offset = Length = integer()
221 Advise = posix_file_advise()
222 Reason = posix() | badarg
223 posix_file_advise() =
224 normal |
225 sequential |
226 random |
227 no_reuse |
228 will_need |
229 dont_need
230 advise/4 can be used to announce an intention to access file
232 data in a specific pattern in the future, thus allowing the
233 operating system to perform appropriate optimizations.
234 On some platforms, this function might have no effect.
236 allocate(File, Offset, Length) -> ok | {error, posix()}
238 Types:
240 File = io_device()
242 Offset = Length = integer() >= 0
243 allocate/3 can be used to preallocate space for a file.
245 This function only succeeds in platforms that provide this fea‐
247 ture. When it succeeds, space is preallocated for the file but
248 the file size might not be updated. This behaviour depends on
249 the preallocation implementation. To guarantee that the file
250 size is updated, truncate the file to the new size.
251 change_group(Filename, Gid) -> ok | {error, Reason}
253 Types:
255 Filename = name_all()
257 Gid = integer()
258 Reason = posix() | badarg
259 Changes group of a file. See write_file_info/2.
261 change_mode(Filename, Mode) -> ok | {error, Reason}
263 Types:
265 Filename = name_all()
267 Mode = integer()
268 Reason = posix() | badarg
269 Changes permissions of a file. See write_file_info/2.
271 change_owner(Filename, Uid) -> ok | {error, Reason}
273 Types:
275 Filename = name_all()
277 Uid = integer()
278 Reason = posix() | badarg
279 Changes owner of a file. See write_file_info/2.
281 change_owner(Filename, Uid, Gid) -> ok | {error, Reason}
283 Types:
285 Filename = name_all()
287 Uid = Gid = integer()
288 Reason = posix() | badarg
289 Changes owner and group of a file. See write_file_info/2.
291 change_time(Filename, Mtime) -> ok | {error, Reason}
293 Types:
295 Filename = name_all()
297 Mtime = date_time()
298 Reason = posix() | badarg
299 Changes the modification and access times of a file. See
301 write_file_info/2.
302 change_time(Filename, Atime, Mtime) -> ok | {error, Reason}
304 Types:
306 Filename = name_all()
308 Atime = Mtime = date_time()
309 Reason = posix() | badarg
310 Changes the modification and last access times of a file. See
312 write_file_info/2.
313 close(IoDevice) -> ok | {error, Reason}
315 Types:
317 IoDevice = io_device()
319 Reason = posix() | badarg | terminated
320 Closes the file referenced by IoDevice. It mostly returns ok,
322 except for some severe errors such as out of memory.
323 Notice that if option delayed_write was used when opening the
325 file, close/1 can return an old write error and not even try to
326 close the file. See open/2.
327 consult(Filename) -> {ok, Terms} | {error, Reason}
329 Types:
331 Filename = name_all()
333 Terms = [term()]
334 Reason =
335 posix() |
336 badarg |
337 terminated |
338 system_limit |
339 {Line :: integer(), Mod :: module(), Term :: term()}
340 Reads Erlang terms, separated by '.', from Filename. Returns one
342 of the following:
343 {ok, Terms}:
345 The file was successfully read.
346 {error, atom()}:
348 An error occurred when opening the file or reading it. For a
349 list of typical error codes, see open/2.
350 {error, {Line, Mod, Term}}:
352 An error occurred when interpreting the Erlang terms in the
353 file. To convert the three-element tuple to an English
354 description of the error, use format_error/1.
355 Example:
357 f.txt: {person, "kalle", 25}.
359 {person, "pelle", 30}.
360 1> file:consult("f.txt").
362 {ok,[{person,"kalle",25},{person,"pelle",30}]}
363 The encoding of Filename can be set by a comment, as described
365 in epp(3).
366 copy(Source, Destination) -> {ok, BytesCopied} | {error, Reason}
368 copy(Source, Destination, ByteCount) ->
370 {ok, BytesCopied} | {error, Reason}
371 Types:
373 Source = Destination = io_device() | Filename | {Filename,
375 Modes}
376 Filename = name_all()
377 Modes = [mode()]
378 ByteCount = integer() >= 0 | infinity
379 BytesCopied = integer() >= 0
380 Reason = posix() | badarg | terminated
381 Copies ByteCount bytes from Source to Destination. Source and
383 Destination refer to either filenames or IO devices from, for
384 example, open/2. ByteCount defaults to infinity, denoting an
385 infinite number of bytes.
386 Argument Modes is a list of possible modes, see open/2, and
388 defaults to [].
389 If both Source and Destination refer to filenames, the files are
391 opened with [read, binary] and [write, binary] prepended to
392 their mode lists, respectively, to optimize the copy.
393 If Source refers to a filename, it is opened with read mode
395 prepended to the mode list before the copy, and closed when
396 done.
397 If Destination refers to a filename, it is opened with write
399 mode prepended to the mode list before the copy, and closed when
400 done.
401 Returns {ok, BytesCopied}, where BytesCopied is the number of
403 bytes that was copied, which can be less than ByteCount if end
404 of file was encountered on the source. If the operation fails,
405 {error, Reason} is returned.
406 Typical error reasons: as for open/2 if a file had to be opened,
408 and as for read/2 and write/2.
409 datasync(IoDevice) -> ok | {error, Reason}
411 Types:
413 IoDevice = io_device()
415 Reason = posix() | badarg | terminated
416 Ensures that any buffers kept by the operating system (not by
418 the Erlang runtime system) are written to disk. In many ways it
419 resembles fsync but it does not update some of the metadata of
420 the file, such as the access time. On some platforms this func‐
421 tion has no effect.
422 Applications that access databases or log files often write a
424 tiny data fragment (for example, one line in a log file) and
425 then call fsync() immediately to ensure that the written data is
426 physically stored on the hard disk. Unfortunately, fsync()
427 always initiates two write operations: one for the newly written
428 data and another one to update the modification time stored in
429 the inode. If the modification time is not a part of the trans‐
430 action concept, fdatasync() can be used to avoid unnecessary
431 inode disk write operations.
432 Available only in some POSIX systems, this call results in a
434 call to fsync(), or has no effect in systems not providing the
435 fdatasync() syscall.
436 del_dir(Dir) -> ok | {error, Reason}
438 Types:
440 Dir = name_all()
442 Reason = posix() | badarg
443 Tries to delete directory Dir. The directory must be empty
445 before it can be deleted. Returns ok if successful.
446 Typical error reasons:
448 eacces:
450 Missing search or write permissions for the parent directo‐
451 ries of Dir.
452 eexist:
454 The directory is not empty.
455 enoent:
457 The directory does not exist.
458 enotdir:
460 A component of Dir is not a directory. On some platforms,
461 enoent is returned instead.
462 einval:
464 Attempt to delete the current directory. On some platforms,
465 eacces is returned instead.
466 delete(Filename) -> ok | {error, Reason}
468 Types:
470 Filename = name_all()
472 Reason = posix() | badarg
473 Tries to delete file Filename. Returns ok if successful.
475 Typical error reasons:
477 enoent:
479 The file does not exist.
480 eacces:
482 Missing permission for the file or one of its parents.
483 eperm:
485 The file is a directory and the user is not superuser.
486 enotdir:
488 A component of the filename is not a directory. On some
489 platforms, enoent is returned instead.
490 einval:
492 Filename has an improper type, such as tuple.
493 Warning:
495 In a future release, a bad type for argument Filename will prob‐
496 ably generate an exception.
497 eval(Filename) -> ok | {error, Reason}
500 Types:
502 Filename = name_all()
504 Reason =
505 posix() |
506 badarg |
507 terminated |
508 system_limit |
509 {Line :: integer(), Mod :: module(), Term :: term()}
510 Reads and evaluates Erlang expressions, separated by '.' (or
512 ',', a sequence of expressions is also an expression) from File‐
513 name. The result of the evaluation is not returned; any expres‐
514 sion sequence in the file must be there for its side effect.
515 Returns one of the following:
516 ok:
518 The file was read and evaluated.
519 {error, atom()}:
521 An error occurred when opening the file or reading it. For a
522 list of typical error codes, see open/2.
523 {error, {Line, Mod, Term}}:
525 An error occurred when interpreting the Erlang expressions
526 in the file. To convert the three-element tuple to an Eng‐
527 lish description of the error, use format_error/1.
528 The encoding of Filename can be set by a comment, as described
530 in epp(3).
531 eval(Filename, Bindings) -> ok | {error, Reason}
533 Types:
535 Filename = name_all()
537 Bindings = erl_eval:binding_struct()
538 Reason =
539 posix() |
540 badarg |
541 terminated |
542 system_limit |
543 {Line :: integer(), Mod :: module(), Term :: term()}
544 The same as eval/1, but the variable bindings Bindings are used
546 in the evaluation. For information about the variable bindings,
547 see erl_eval(3).
548 format_error(Reason) -> Chars
550 Types:
552 Reason =
554 posix() |
555 badarg |
556 terminated |
557 system_limit |
558 {Line :: integer(), Mod :: module(), Term :: term()}
559 Chars = string()
560 Given the error reason returned by any function in this module,
562 returns a descriptive string of the error in English.
563 get_cwd() -> {ok, Dir} | {error, Reason}
565 Types:
567 Dir = filename()
569 Reason = posix()
570 Returns {ok, Dir}, where Dir is the current working directory of
572 the file server.
573 Note:
575 In rare circumstances, this function can fail on Unix. It can
576 occur if read permission does not exist for the parent directo‐
577 ries of the current directory.
578 A typical error reason:
581 eacces:
583 Missing read permission for one of the parents of the cur‐
584 rent directory.
585 get_cwd(Drive) -> {ok, Dir} | {error, Reason}
587 Types:
589 Drive = string()
591 Dir = filename()
592 Reason = posix() | badarg
593 Returns {ok, Dir} or {error, Reason}, where Dir is the current
595 working directory of the specified drive.
596 Drive is to be of the form "Letter:", for example, "c:".
598 Returns {error, enotsup} on platforms that have no concept of
600 current drive (Unix, for example).
601 Typical error reasons:
603 enotsup:
605 The operating system has no concept of drives.
606 eacces:
608 The drive does not exist.
609 einval:
611 The format of Drive is invalid.
612 list_dir(Dir) -> {ok, Filenames} | {error, Reason}
614 Types:
616 Dir = name_all()
618 Filenames = [filename()]
619 Reason =
620 posix() |
621 badarg |
622 {no_translation, Filename :: unicode:latin1_binary()}
623 Lists all files in a directory, except files with raw filenames.
625 Returns {ok, Filenames} if successful, otherwise {error, Rea‐
626 son}. Filenames is a list of the names of all the files in the
627 directory. The names are not sorted.
628 Typical error reasons:
630 eacces:
632 Missing search or write permissions for Dir or one of its
633 parent directories.
634 enoent:
636 The directory does not exist.
637 {no_translation, Filename}:
639 Filename is a binary() with characters coded in ISO Latin-1
640 and the VM was started with parameter +fnue.
641 list_dir_all(Dir) -> {ok, Filenames} | {error, Reason}
643 Types:
645 Dir = name_all()
647 Filenames = [filename_all()]
648 Reason = posix() | badarg
649 Lists all the files in a directory, including files with raw
651 filenames. Returns {ok, Filenames} if successful, otherwise
652 {error, Reason}. Filenames is a list of the names of all the
653 files in the directory. The names are not sorted.
654 Typical error reasons:
656 eacces:
658 Missing search or write permissions for Dir or one of its
659 parent directories.
660 enoent:
662 The directory does not exist.
663 make_dir(Dir) -> ok | {error, Reason}
665 Types:
667 Dir = name_all()
669 Reason = posix() | badarg
670 Tries to create directory Dir. Missing parent directories are
672 not created. Returns ok if successful.
673 Typical error reasons:
675 eacces:
677 Missing search or write permissions for the parent directo‐
678 ries of Dir.
679 eexist:
681 A file or directory named Dir exists already.
682 enoent:
684 A component of Dir does not exist.
685 enospc:
687 No space is left on the device.
688 enotdir:
690 A component of Dir is not a directory. On some platforms,
691 enoent is returned instead.
692 make_link(Existing, New) -> ok | {error, Reason}
694 Types:
696 Existing = New = name_all()
698 Reason = posix() | badarg
699 Makes a hard link from Existing to New on platforms supporting
701 links (Unix and Windows). This function returns ok if the link
702 was successfully created, otherwise {error, Reason}. On plat‐
703 forms not supporting links, {error,enotsup} is returned.
704 Typical error reasons:
706 eacces:
708 Missing read or write permissions for the parent directories
709 of Existing or New.
710 eexist:
712 New already exists.
713 enotsup:
715 Hard links are not supported on this platform.
716 make_symlink(Existing, New) -> ok | {error, Reason}
718 Types:
720 Existing = New = name_all()
722 Reason = posix() | badarg
723 Creates a symbolic link New to the file or directory Existing on
725 platforms supporting symbolic links (most Unix systems and Win‐
726 dows, beginning with Vista). Existing does not need to exist.
727 Returns ok if the link is successfully created, otherwise
728 {error, Reason}. On platforms not supporting symbolic links,
729 {error, enotsup} is returned.
730 Typical error reasons:
732 eacces:
734 Missing read or write permissions for the parent directories
735 of Existing or New.
736 eexist:
738 New already exists.
739 enotsup:
741 Symbolic links are not supported on this platform.
742 eperm:
744 User does not have privileges to create symbolic links
745 (SeCreateSymbolicLinkPrivilege on Windows).
746 native_name_encoding() -> latin1 | utf8
748 Returns the filename encoding mode. If it is latin1, the system
750 translates no filenames. If it is utf8, filenames are converted
751 back and forth to the native filename encoding (usually UTF-8,
752 but UTF-16 on Windows).
753 open(File, Modes) -> {ok, IoDevice} | {error, Reason}
755 Types:
757 File = Filename | iodata()
759 Filename = name_all()
760 Modes = [mode() | ram]
761 IoDevice = io_device()
762 Reason = posix() | badarg | system_limit
763 Opens file File in the mode determined by Modes, which can con‐
765 tain one or more of the following options:
766 read:
768 The file, which must exist, is opened for reading.
769 write:
771 The file is opened for writing. It is created if it does not
772 exist. If the file exists and write is not combined with
773 read, the file is truncated.
774 append:
776 The file is opened for writing. It is created if it does not
777 exist. Every write operation to a file opened with append
778 takes place at the end of the file.
779 exclusive:
781 The file is opened for writing. It is created if it does not
782 exist. If the file exists, {error, eexist} is returned.
783 Warning:
785 This option does not guarantee exclusiveness on file systems
786 not supporting O_EXCL properly, such as NFS. Do not depend on
787 this option unless you know that the file system supports it
788 (in general, local file systems are safe).
789 raw:
792 Allows faster access to a file, as no Erlang process is
793 needed to handle the file. However, a file opened in this
794 way has the following limitations:
795 * The functions in the io module cannot be used, as they can
797 only talk to an Erlang process. Instead, use functions
798 read/2, read_line/1, and write/2.
799 * Especially if read_line/1 is to be used on a raw file, it
801 is recommended to combine this option with option
802 {read_ahead, Size} as line-oriented I/O is inefficient
803 without buffering.
804 * Only the Erlang process that opened the file can use it.
806 * A remote Erlang file server cannot be used. The computer
808 on which the Erlang node is running must have access to
809 the file system (directly or through NFS).
810 binary:
812 Read operations on the file return binaries rather than
813 lists.
814 {delayed_write, Size, Delay}:
816 Data in subsequent write/2 calls is buffered until at least
817 Size bytes are buffered, or until the oldest buffered data
818 is Delay milliseconds old. Then all buffered data is written
819 in one operating system call. The buffered data is also
820 flushed before some other file operation than write/2 is
821 executed.
822 The purpose of this option is to increase performance by
824 reducing the number of operating system calls. Thus, the
825 write/2 calls must be for sizes significantly less than
826 Size, and not interspersed by too many other file opera‐
827 tions.
828 When this option is used, the result of write/2 calls can
830 prematurely be reported as successful, and if a write error
831 occurs, the error is reported as the result of the next file
832 operation, which is not executed.
833 For example, when delayed_write is used, after a number of
835 write/2 calls, close/1 can return {error, enospc}, as there
836 is not enough space on the disc for previously written data.
837 close/1 must probably be called again, as the file is still
838 open.
839 delayed_write:
841 The same as {delayed_write, Size, Delay} with reasonable
842 default values for Size and Delay (roughly some 64 KB, 2
843 seconds).
844 {read_ahead, Size}:
846 Activates read data buffering. If read/2 calls are for sig‐
847 nificantly less than Size bytes, read operations to the
848 operating system are still performed for blocks of Size
849 bytes. The extra data is buffered and returned in subsequent
850 read/2 calls, giving a performance gain as the number of
851 operating system calls is reduced.
852 The read_ahead buffer is also highly used by function
854 read_line/1 in raw mode, therefore this option is recom‐
855 mended (for performance reasons) when accessing raw files
856 using that function.
857 If read/2 calls are for sizes not significantly less than,
859 or even greater than Size bytes, no performance gain can be
860 expected.
861 read_ahead:
863 The same as {read_ahead, Size} with a reasonable default
864 value for Size (roughly some 64 KB).
865 compressed:
867 Makes it possible to read or write gzip compressed files.
868 Option compressed must be combined with read or write, but
869 not both. Notice that the file size obtained with
870 read_file_info/1 does probably not match the number of bytes
871 that can be read from a compressed file.
872 {encoding, Encoding}:
874 Makes the file perform automatic translation of characters
875 to and from a specific (Unicode) encoding. Notice that the
876 data supplied to write/2 or returned by read/2 still is
877 byte-oriented; this option denotes only how data is stored
878 in the disk file.
879 Depending on the encoding, different methods of reading and
881 writing data is preferred. The default encoding of latin1
882 implies using this module (file) for reading and writing
883 data as the interfaces provided here work with byte-oriented
884 data. Using other (Unicode) encodings makes the io(3) func‐
885 tions get_chars, get_line, and put_chars more suitable, as
886 they can work with the full Unicode range.
887 If data is sent to an io_device() in a format that cannot be
889 converted to the specified encoding, or if data is read by a
890 function that returns data in a format that cannot cope with
891 the character range of the data, an error occurs and the
892 file is closed.
893 Allowed values for Encoding:
895 latin1:
897 The default encoding. Bytes supplied to the file, that is,
898 write/2 are written "as is" on the file. Likewise, bytes
899 read from the file, that is, read/2 are returned "as is".
900 If module io(3) is used for writing, the file can only
901 cope with Unicode characters up to code point 255 (the ISO
902 Latin-1 range).
903 unicode or utf8:
905 Characters are translated to and from UTF-8 encoding
906 before they are written to or read from the file. A file
907 opened in this way can be readable using function read/2,
908 as long as no data stored on the file lies beyond the ISO
909 Latin-1 range (0..255), but failure occurs if the data
910 contains Unicode code points beyond that range. The file
911 is best read with the functions in the Unicode aware mod‐
912 ule io(3).
913 Bytes written to the file by any means are translated to
915 UTF-8 encoding before being stored on the disk file.
916 utf16 or {utf16,big}:
918 Works like unicode, but translation is done to and from
919 big endian UTF-16 instead of UTF-8.
920 {utf16,little}:
922 Works like unicode, but translation is done to and from
923 little endian UTF-16 instead of UTF-8.
924 utf32 or {utf32,big}:
926 Works like unicode, but translation is done to and from
927 big endian UTF-32 instead of UTF-8.
928 {utf32,little}:
930 Works like unicode, but translation is done to and from
931 little endian UTF-32 instead of UTF-8.
932 The Encoding can be changed for a file "on the fly" by using
934 function io:setopts/2. So a file can be analyzed in latin1
935 encoding for, for example, a BOM, positioned beyond the BOM
936 and then be set for the right encoding before further read‐
937 ing. For functions identifying BOMs, see module unicode(3).
938 This option is not allowed on raw files.
940 ram:
942 File must be iodata(). Returns an fd(), which lets module
943 file operate on the data in-memory as if it is a file.
944 sync:
946 On platforms supporting it, enables the POSIX O_SYNC syn‐
947 chronous I/O flag or its platform-dependent equivalent (for
948 example, FILE_FLAG_WRITE_THROUGH on Windows) so that writes
949 to the file block until the data is physically written to
950 disk. However, be aware that the exact semantics of this
951 flag differ from platform to platform. For example, none of
952 Linux or Windows guarantees that all file metadata are also
953 written before the call returns. For precise semantics,
954 check the details of your platform documentation. On plat‐
955 forms with no support for POSIX O_SYNC or equivalent, use of
956 the sync flag causes open to return {error, enotsup}.
957 Returns:
959 {ok, IoDevice}:
961 The file is opened in the requested mode. IoDevice is a ref‐
962 erence to the file.
963 {error, Reason}:
965 The file cannot be opened.
966 IoDevice is really the pid of the process that handles the file.
968 This process is linked to the process that originally opened the
969 file. If any process to which the IoDevice is linked terminates,
970 the file is closed and the process itself is terminated. An
971 IoDevice returned from this call can be used as an argument to
972 the I/O functions (see io(3)).
973 Note:
975 In previous versions of file, modes were specified as one of the
976 atoms read, write, or read_write instead of a list. This is
977 still allowed for reasons of backwards compatibility, but is not
978 to be used for new code. Also note that read_write is not
979 allowed in a mode list.
980 Typical error reasons:
983 enoent:
985 The file does not exist.
986 eacces:
988 Missing permission for reading the file or searching one of
989 the parent directories.
990 eisdir:
992 The named file is a directory.
993 enotdir:
995 A component of the filename is not a directory. On some
996 platforms, enoent is returned instead.
997 enospc:
999 There is no space left on the device (if write access was
1000 specified).
1001 path_consult(Path, Filename) ->
1003 {ok, Terms, FullName} | {error, Reason}
1004 Types:
1006 Path = [Dir]
1008 Dir = Filename = name_all()
1009 Terms = [term()]
1010 FullName = filename_all()
1011 Reason =
1012 posix() |
1013 badarg |
1014 terminated |
1015 system_limit |
1016 {Line :: integer(), Mod :: module(), Term :: term()}
1017 Searches the path Path (a list of directory names) until the
1019 file Filename is found. If Filename is an absolute filename,
1020 Path is ignored. Then reads Erlang terms, separated by '.', from
1021 the file.
1022 Returns one of the following:
1024 {ok, Terms, FullName}:
1026 The file is successfully read. FullName is the full name of
1027 the file.
1028 {error, enoent}:
1030 The file cannot be found in any of the directories in Path.
1031 {error, atom()}:
1033 An error occurred when opening the file or reading it. For a
1034 list of typical error codes, see open/2.
1035 {error, {Line, Mod, Term}}:
1037 An error occurred when interpreting the Erlang terms in the
1038 file. Use format_error/1 to convert the three-element tuple
1039 to an English description of the error.
1040 The encoding of Filename can be set by a comment as described in
1042 epp(3).
1043 path_eval(Path, Filename) -> {ok, FullName} | {error, Reason}
1045 Types:
1047 Path = [Dir :: name_all()]
1049 Filename = name_all()
1050 FullName = filename_all()
1051 Reason =
1052 posix() |
1053 badarg |
1054 terminated |
1055 system_limit |
1056 {Line :: integer(), Mod :: module(), Term :: term()}
1057 Searches the path Path (a list of directory names) until the
1059 file Filename is found. If Filename is an absolute filename,
1060 Path is ignored. Then reads and evaluates Erlang expressions,
1061 separated by '.' (or ',', a sequence of expressions is also an
1062 expression), from the file. The result of evaluation is not
1063 returned; any expression sequence in the file must be there for
1064 its side effect.
1065 Returns one of the following:
1067 {ok, FullName}:
1069 The file is read and evaluated. FullName is the full name of
1070 the file.
1071 {error, enoent}:
1073 The file cannot be found in any of the directories in Path.
1074 {error, atom()}:
1076 An error occurred when opening the file or reading it. For a
1077 list of typical error codes, see open/2.
1078 {error, {Line, Mod, Term}}:
1080 An error occurred when interpreting the Erlang expressions
1081 in the file. Use format_error/1 to convert the three-element
1082 tuple to an English description of the error.
1083 The encoding of Filename can be set by a comment as described in
1085 epp(3).
1086 path_open(Path, Filename, Modes) ->
1088 {ok, IoDevice, FullName} | {error, Reason}
1089 Types:
1091 Path = [Dir :: name_all()]
1093 Filename = name_all()
1094 Modes = [mode()]
1095 IoDevice = io_device()
1096 FullName = filename_all()
1097 Reason = posix() | badarg | system_limit
1098 Searches the path Path (a list of directory names) until the
1100 file Filename is found. If Filename is an absolute filename,
1101 Path is ignored. Then opens the file in the mode determined by
1102 Modes.
1103 Returns one of the following:
1105 {ok, IoDevice, FullName}:
1107 The file is opened in the requested mode. IoDevice is a ref‐
1108 erence to the file and FullName is the full name of the
1109 file.
1110 {error, enoent}:
1112 The file cannot be found in any of the directories in Path.
1113 {error, atom()}:
1115 The file cannot be opened.
1116 path_script(Path, Filename) ->
1118 {ok, Value, FullName} | {error, Reason}
1119 Types:
1121 Path = [Dir :: name_all()]
1123 Filename = name_all()
1124 Value = term()
1125 FullName = filename_all()
1126 Reason =
1127 posix() |
1128 badarg |
1129 terminated |
1130 system_limit |
1131 {Line :: integer(), Mod :: module(), Term :: term()}
1132 Searches the path Path (a list of directory names) until the
1134 file Filename is found. If Filename is an absolute filename,
1135 Path is ignored. Then reads and evaluates Erlang expressions,
1136 separated by '.' (or ',', a sequence of expressions is also an
1137 expression), from the file.
1138 Returns one of the following:
1140 {ok, Value, FullName}:
1142 The file is read and evaluated. FullName is the full name of
1143 the file and Value the value of the last expression.
1144 {error, enoent}:
1146 The file cannot be found in any of the directories in Path.
1147 {error, atom()}:
1149 An error occurred when opening the file or reading it. For a
1150 list of typical error codes, see open/2.
1151 {error, {Line, Mod, Term}}:
1153 An error occurred when interpreting the Erlang expressions
1154 in the file. Use format_error/1 to convert the three-element
1155 tuple to an English description of the error.
1156 The encoding of Filename can be set by a comment as described in
1158 epp(3).
1159 path_script(Path, Filename, Bindings) ->
1161 {ok, Value, FullName} | {error, Reason}
1162 Types:
1164 Path = [Dir :: name_all()]
1166 Filename = name_all()
1167 Bindings = erl_eval:binding_struct()
1168 Value = term()
1169 FullName = filename_all()
1170 Reason =
1171 posix() |
1172 badarg |
1173 terminated |
1174 system_limit |
1175 {Line :: integer(), Mod :: module(), Term :: term()}
1176 The same as path_script/2 but the variable bindings Bindings are
1178 used in the evaluation. See erl_eval(3) about variable bindings.
1179 pid2name(Pid) -> {ok, Filename} | undefined
1181 Types:
1183 Filename = filename_all()
1185 Pid = pid()
1186 If Pid is an I/O device, that is, a pid returned from open/2,
1188 this function returns the filename, or rather:
1189 {ok, Filename}:
1191 If the file server of this node is not a slave, the file was
1192 opened by the file server of this node (this implies that
1193 Pid must be a local pid) and the file is not closed. File‐
1194 name is the filename in flat string format.
1195 undefined:
1197 In all other cases.
1198 Warning:
1200 This function is intended for debugging only.
1201 position(IoDevice, Location) ->
1204 {ok, NewPosition} | {error, Reason}
1205 Types:
1207 IoDevice = io_device()
1209 Location = location()
1210 NewPosition = integer()
1211 Reason = posix() | badarg | terminated
1212 Sets the position of the file referenced by IoDevice to Loca‐
1214 tion. Returns {ok, NewPosition} (as absolute offset) if success‐
1215 ful, otherwise {error, Reason}. Location is one of the follow‐
1216 ing:
1217 Offset:
1219 The same as {bof, Offset}.
1220 {bof, Offset}:
1222 Absolute offset.
1223 {cur, Offset}:
1225 Offset from the current position.
1226 {eof, Offset}:
1228 Offset from the end of file.
1229 bof | cur | eof:
1231 The same as above with Offset 0.
1232 Notice that offsets are counted in bytes, not in characters. If
1234 the file is opened using some other encoding than latin1, one
1235 byte does not correspond to one character. Positioning in such a
1236 file can only be done to known character boundaries. That is, to
1237 a position earlier retrieved by getting a current position, to
1238 the beginning/end of the file or to some other position known to
1239 be on a correct character boundary by some other means (typi‐
1240 cally beyond a byte order mark in the file, which has a known
1241 byte-size).
1242 A typical error reason is:
1244 einval:
1246 Either Location is illegal, or it is evaluated to a negative
1247 offset in the file. Notice that if the resulting position is
1248 a negative value, the result is an error, and after the call
1249 the file position is undefined.
1250 pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason}
1252 Types:
1254 IoDevice = io_device()
1256 LocNums =
1257 [{Location :: location(), Number :: integer() >= 0}]
1258 DataL = [Data]
1259 Data = string() | binary() | eof
1260 Reason = posix() | badarg | terminated
1261 Performs a sequence of pread/3 in one operation, which is more
1263 efficient than calling them one at a time. Returns {ok, [Data,
1264 ...]} or {error, Reason}, where each Data, the result of the
1265 corresponding pread, is either a list or a binary depending on
1266 the mode of the file, or eof if the requested position is beyond
1267 end of file.
1268 As the position is specified as a byte-offset, take special cau‐
1270 tion when working with files where encoding is set to something
1271 else than latin1, as not every byte position is a valid charac‐
1272 ter boundary on such a file.
1273 pread(IoDevice, Location, Number) ->
1275 {ok, Data} | eof | {error, Reason}
1276 Types:
1278 IoDevice = io_device()
1280 Location = location()
1281 Number = integer() >= 0
1282 Data = string() | binary()
1283 Reason = posix() | badarg | terminated
1284 Combines position/2 and read/2 in one operation, which is more
1286 efficient than calling them one at a time. If IoDevice is opened
1287 in raw mode, some restrictions apply:
1288 * Location is only allowed to be an integer.
1290 * The current position of the file is undefined after the
1292 operation.
1293 As the position is specified as a byte-offset, take special cau‐
1295 tion when working with files where encoding is set to something
1296 else than latin1, as not every byte position is a valid charac‐
1297 ter boundary on such a file.
1298 pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}}
1300 Types:
1302 IoDevice = io_device()
1304 LocBytes = [{Location :: location(), Bytes :: iodata()}]
1305 N = integer() >= 0
1306 Reason = posix() | badarg | terminated
1307 Performs a sequence of pwrite/3 in one operation, which is more
1309 efficient than calling them one at a time. Returns ok or {error,
1310 {N, Reason}}, where N is the number of successful writes done
1311 before the failure.
1312 When positioning in a file with other encoding than latin1, cau‐
1314 tion must be taken to set the position on a correct character
1315 boundary. For details, see position/2.
1316 pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason}
1318 Types:
1320 IoDevice = io_device()
1322 Location = location()
1323 Bytes = iodata()
1324 Reason = posix() | badarg | terminated
1325 Combines position/2 and write/2 in one operation, which is more
1327 efficient than calling them one at a time. If IoDevice has been
1328 opened in raw mode, some restrictions apply:
1329 * Location is only allowed to be an integer.
1331 * The current position of the file is undefined after the
1333 operation.
1334 When positioning in a file with other encoding than latin1, cau‐
1336 tion must be taken to set the position on a correct character
1337 boundary. For details, see position/2.
1338 read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}
1340 Types:
1342 IoDevice = io_device() | atom()
1344 Number = integer() >= 0
1345 Data = string() | binary()
1346 Reason =
1347 posix() |
1348 badarg |
1349 terminated |
1350 {no_translation, unicode, latin1}
1351 Reads Number bytes/characters from the file referenced by IoDe‐
1353 vice. The functions read/2, pread/3, and read_line/1 are the
1354 only ways to read from a file opened in raw mode (although they
1355 work for normally opened files, too).
1356 For files where encoding is set to something else than latin1,
1358 one character can be represented by more than one byte on the
1359 file. The parameter Number always denotes the number of charac‐
1360 ters read from the file, while the position in the file can be
1361 moved much more than this number when reading a Unicode file.
1362 Also, if encoding is set to something else than latin1, the
1364 read/3 call fails if the data contains characters larger than
1365 255, which is why module io(3) is to be preferred when reading
1366 such a file.
1367 The function returns:
1369 {ok, Data}:
1371 If the file was opened in binary mode, the read bytes are
1372 returned in a binary, otherwise in a list. The list or
1373 binary is shorter than the number of bytes requested if end
1374 of file was reached.
1375 eof:
1377 Returned if Number>0 and end of file was reached before any‐
1378 thing at all could be read.
1379 {error, Reason}:
1381 An error occurred.
1382 Typical error reasons:
1384 ebadf:
1386 The file is not opened for reading.
1387 {no_translation, unicode, latin1}:
1389 The file is opened with another encoding than latin1 and the
1390 data in the file cannot be translated to the byte-oriented
1391 data that this function returns.
1392 read_file(Filename) -> {ok, Binary} | {error, Reason}
1394 Types:
1396 Filename = name_all()
1398 Binary = binary()
1399 Reason = posix() | badarg | terminated | system_limit
1400 Returns {ok, Binary}, where Binary is a binary data object that
1402 contains the contents of Filename, or {error, Reason} if an
1403 error occurs.
1404 Typical error reasons:
1406 enoent:
1408 The file does not exist.
1409 eacces:
1411 Missing permission for reading the file, or for searching
1412 one of the parent directories.
1413 eisdir:
1415 The named file is a directory.
1416 enotdir:
1418 A component of the filename is not a directory. On some
1419 platforms, enoent is returned instead.
1420 enomem:
1422 There is not enough memory for the contents of the file.
1423 read_file_info(Filename) -> {ok, FileInfo} | {error, Reason}
1425 read_file_info(Filename, Opts) -> {ok, FileInfo} | {error, Reason}
1427 Types:
1429 Filename = name_all()
1431 Opts = [file_info_option()]
1432 FileInfo = file_info()
1433 Reason = posix() | badarg
1434 Retrieves information about a file. Returns {ok, FileInfo} if
1436 successful, otherwise {error, Reason}. FileInfo is a record
1437 file_info, defined in the Kernel include file file.hrl. Include
1438 the following directive in the module from which the function is
1439 called:
1440 -include_lib("kernel/include/file.hrl").
1442 The time type returned in atime, mtime, and ctime is dependent
1444 on the time type set in Opts :: {time, Type} as follows:
1445 local:
1447 Returns local time.
1448 universal:
1450 Returns universal time.
1451 posix:
1453 Returns seconds since or before Unix time epoch, which is
1454 1970-01-01 00:00 UTC.
1455 Default is {time, local}.
1457 If the option raw is set, the file server is not called and only
1459 information about local files is returned. Note that this will
1460 break this module's atomicity guarantees as it can race with a
1461 concurrent call to write_file_info/1,2
1462 Note:
1464 As file times are stored in POSIX time on most OS, it is faster
1465 to query file information with option posix.
1466 The record file_info contains the following fields:
1469 size = integer() >= 0:
1471 Size of file in bytes.
1472 type = device | directory | other | regular | symlink:
1474 The type of the file.
1475 access = read | write | read_write | none:
1477 The current system access to the file.
1478 atime = date_time() | integer() >= 0:
1480 The last time the file was read.
1481 mtime = date_time() | integer() >= 0:
1483 The last time the file was written.
1484 ctime = date_time() | integer() >=0:
1486 The interpretation of this time field depends on the operat‐
1487 ing system. On Unix, it is the last time the file or the
1488 inode was changed. In Windows, it is the create time.
1489 mode = integer() >= 0:
1491 The file permissions as the sum of the following bit values:
1492 8#00400:
1494 read permission: owner
1495 8#00200:
1497 write permission: owner
1498 8#00100:
1500 execute permission: owner
1501 8#00040:
1503 read permission: group
1504 8#00020:
1506 write permission: group
1507 8#00010:
1509 execute permission: group
1510 8#00004:
1512 read permission: other
1513 8#00002:
1515 write permission: other
1516 8#00001:
1518 execute permission: other
1519 16#800:
1521 set user id on execution
1522 16#400:
1524 set group id on execution
1525 On Unix platforms, other bits than those listed above may be
1527 set.
1528 links = integer() >= 0:
1530 Number of links to the file (this is always 1 for file sys‐
1531 tems that have no concept of links).
1532 major_device = integer() >= 0:
1534 Identifies the file system where the file is located. In
1535 Windows, the number indicates a drive as follows: 0 means
1536 A:, 1 means B:, and so on.
1537 minor_device = integer() >= 0:
1539 Only valid for character devices on Unix. In all other
1540 cases, this field is zero.
1541 inode = integer() >= 0:
1543 Gives the inode number. On non-Unix file systems, this field
1544 is zero.
1545 uid = integer() >= 0:
1547 Indicates the owner of the file. On non-Unix file systems,
1548 this field is zero.
1549 gid = integer() >= 0:
1551 Gives the group that the owner of the file belongs to. On
1552 non-Unix file systems, this field is zero.
1553 Typical error reasons:
1555 eacces:
1557 Missing search permission for one of the parent directories
1558 of the file.
1559 enoent:
1561 The file does not exist.
1562 enotdir:
1564 A component of the filename is not a directory. On some
1565 platforms, enoent is returned instead.
1566 read_line(IoDevice) -> {ok, Data} | eof | {error, Reason}
1568 Types:
1570 IoDevice = io_device() | atom()
1572 Data = string() | binary()
1573 Reason =
1574 posix() |
1575 badarg |
1576 terminated |
1577 {no_translation, unicode, latin1}
1578 Reads a line of bytes/characters from the file referenced by
1580 IoDevice. Lines are defined to be delimited by the linefeed (LF,
1581 \n) character, but any carriage return (CR, \r) followed by a
1582 newline is also treated as a single LF character (the carriage
1583 return is silently ignored). The line is returned including the
1584 LF, but excluding any CR immediately followed by an LF. This be‐
1585 haviour is consistent with the behaviour of io:get_line/2. If
1586 end of file is reached without any LF ending the last line, a
1587 line with no trailing LF is returned.
1588 The function can be used on files opened in raw mode. However,
1590 it is inefficient to use it on raw files if the file is not
1591 opened with option {read_ahead, Size} specified. Thus, combining
1592 raw and {read_ahead, Size} is highly recommended when opening a
1593 text file for raw line-oriented reading.
1594 If encoding is set to something else than latin1, the
1596 read_line/1 call fails if the data contains characters larger
1597 than 255, why module io(3) is to be preferred when reading such
1598 a file.
1599 The function returns:
1601 {ok, Data}:
1603 One line from the file is returned, including the trailing
1604 LF, but with CRLF sequences replaced by a single LF (see
1605 above).
1606 If the file is opened in binary mode, the read bytes are
1608 returned in a binary, otherwise in a list.
1609 eof:
1611 Returned if end of file was reached before anything at all
1612 could be read.
1613 {error, Reason}:
1615 An error occurred.
1616 Typical error reasons:
1618 ebadf:
1620 The file is not opened for reading.
1621 {no_translation, unicode, latin1}:
1623 The file is opened with another encoding than latin1 and the
1624 data on the file cannot be translated to the byte-oriented
1625 data that this function returns.
1626 read_link(Name) -> {ok, Filename} | {error, Reason}
1628 Types:
1630 Name = name_all()
1632 Filename = filename()
1633 Reason = posix() | badarg
1634 Returns {ok, Filename} if Name refers to a symbolic link that is
1636 not a raw filename, or {error, Reason} otherwise. On platforms
1637 that do not support symbolic links, the return value is
1638 {error,enotsup}.
1639 Typical error reasons:
1641 einval:
1643 Name does not refer to a symbolic link or the name of the
1644 file that it refers to does not conform to the expected
1645 encoding.
1646 enoent:
1648 The file does not exist.
1649 enotsup:
1651 Symbolic links are not supported on this platform.
1652 read_link_all(Name) -> {ok, Filename} | {error, Reason}
1654 Types:
1656 Name = name_all()
1658 Filename = filename_all()
1659 Reason = posix() | badarg
1660 Returns {ok, Filename} if Name refers to a symbolic link or
1662 {error, Reason} otherwise. On platforms that do not support sym‐
1663 bolic links, the return value is {error,enotsup}.
1664 Notice that Filename can be either a list or a binary.
1666 Typical error reasons:
1668 einval:
1670 Name does not refer to a symbolic link.
1671 enoent:
1673 The file does not exist.
1674 enotsup:
1676 Symbolic links are not supported on this platform.
1677 read_link_info(Name) -> {ok, FileInfo} | {error, Reason}
1679 read_link_info(Name, Opts) -> {ok, FileInfo} | {error, Reason}
1681 Types:
1683 Name = name_all()
1685 Opts = [file_info_option()]
1686 FileInfo = file_info()
1687 Reason = posix() | badarg
1688 Works like read_file_info/1,2 except that if Name is a symbolic
1690 link, information about the link is returned in the file_info
1691 record and the type field of the record is set to symlink.
1692 If the option raw is set, the file server is not called and only
1694 information about local files is returned. Note that this will
1695 break this module's atomicity guarantees as it can race with a
1696 concurrent call to write_file_info/1,2
1697 If Name is not a symbolic link, this function returns the same
1699 result as read_file_info/1. On platforms that do not support
1700 symbolic links, this function is always equivalent to
1701 read_file_info/1.
1702 rename(Source, Destination) -> ok | {error, Reason}
1704 Types:
1706 Source = Destination = name_all()
1708 Reason = posix() | badarg
1709 Tries to rename the file Source to Destination. It can be used
1711 to move files (and directories) between directories, but it is
1712 not sufficient to specify the destination only. The destination
1713 filename must also be specified. For example, if bar is a normal
1714 file and foo and baz are directories, rename("foo/bar", "baz")
1715 returns an error, but rename("foo/bar", "baz/bar") succeeds.
1716 Returns ok if it is successful.
1717 Note:
1719 Renaming of open files is not allowed on most platforms (see
1720 eacces below).
1721 Typical error reasons:
1724 eacces:
1726 Missing read or write permissions for the parent directories
1727 of Source or Destination. On some platforms, this error is
1728 given if either Source or Destination is open.
1729 eexist:
1731 Destination is not an empty directory. On some platforms,
1732 also given when Source and Destination are not of the same
1733 type.
1734 einval:
1736 Source is a root directory, or Destination is a subdirectory
1737 of Source.
1738 eisdir:
1740 Destination is a directory, but Source is not.
1741 enoent:
1743 Source does not exist.
1744 enotdir:
1746 Source is a directory, but Destination is not.
1747 exdev:
1749 Source and Destination are on different file systems.
1750 script(Filename) -> {ok, Value} | {error, Reason}
1752 Types:
1754 Filename = name_all()
1756 Value = term()
1757 Reason =
1758 posix() |
1759 badarg |
1760 terminated |
1761 system_limit |
1762 {Line :: integer(), Mod :: module(), Term :: term()}
1763 Reads and evaluates Erlang expressions, separated by '.' (or
1765 ',', a sequence of expressions is also an expression), from the
1766 file.
1767 Returns one of the following:
1769 {ok, Value}:
1771 The file is read and evaluated. Value is the value of the
1772 last expression.
1773 {error, atom()}:
1775 An error occurred when opening the file or reading it. For a
1776 list of typical error codes, see open/2.
1777 {error, {Line, Mod, Term}}:
1779 An error occurred when interpreting the Erlang expressions
1780 in the file. Use format_error/1 to convert the three-element
1781 tuple to an English description of the error.
1782 The encoding of Filename can be set by a comment as described in
1784 epp(3).
1785 script(Filename, Bindings) -> {ok, Value} | {error, Reason}
1787 Types:
1789 Filename = name_all()
1791 Bindings = erl_eval:binding_struct()
1792 Value = term()
1793 Reason =
1794 posix() |
1795 badarg |
1796 terminated |
1797 system_limit |
1798 {Line :: integer(), Mod :: module(), Term :: term()}
1799 The same as script/1 but the variable bindings Bindings are used
1801 in the evaluation. See erl_eval(3) about variable bindings.
1802 sendfile(Filename, Socket) ->
1804 {ok, integer() >= 0} |
1805 {error, inet:posix() | closed | badarg | not_owner}
1806 Types:
1808 Filename = name_all()
1810 Socket = inet:socket()
1811 Sends the file Filename to Socket. Returns {ok, BytesSent} if
1813 successful, otherwise {error, Reason}.
1814 sendfile(RawFile, Socket, Offset, Bytes, Opts) ->
1816 {ok, integer() >= 0} |
1817 {error, inet:posix() | closed | badarg | not_owner}
1818 Types:
1820 RawFile = fd()
1822 Socket = inet:socket()
1823 Offset = Bytes = integer() >= 0
1824 Opts = [sendfile_option()]
1825 sendfile_option() =
1826 {chunk_size, integer() >= 0} | {use_threads, boolean()}
1827 Sends Bytes from the file referenced by RawFile beginning at
1829 Offset to Socket. Returns {ok, BytesSent} if successful, other‐
1830 wise {error, Reason}. If Bytes is set to 0 all data after the
1831 specified Offset is sent.
1832 The file used must be opened using the raw flag, and the process
1834 calling sendfile must be the controlling process of the socket.
1835 See gen_tcp:controlling_process/2.
1836 If the OS used does not support non-blocking sendfile, an Erlang
1838 fallback using read/2 and gen_tcp:send/2 is used.
1839 The option list can contain the following options:
1841 chunk_size:
1843 The chunk size used by the Erlang fallback to send data. If
1844 using the fallback, set this to a value that comfortably
1845 fits in the systems memory. Default is 20 MB.
1846 set_cwd(Dir) -> ok | {error, Reason}
1848 Types:
1850 Dir = name() | EncodedBinary
1852 EncodedBinary = binary()
1853 Reason = posix() | badarg | no_translation
1854 Sets the current working directory of the file server to Dir.
1856 Returns ok if successful.
1857 The functions in the module file usually treat binaries as raw
1859 filenames, that is, they are passed "as is" even when the encod‐
1860 ing of the binary does not agree with native_name_encoding().
1861 However, this function expects binaries to be encoded according
1862 to the value returned by native_name_encoding().
1863 Typical error reasons are:
1865 enoent:
1867 The directory does not exist.
1868 enotdir:
1870 A component of Dir is not a directory. On some platforms,
1871 enoent is returned.
1872 eacces:
1874 Missing permission for the directory or one of its parents.
1875 badarg:
1877 Dir has an improper type, such as tuple.
1878 no_translation:
1880 Dir is a binary() with characters coded in ISO-latin-1 and
1881 the VM is operating with unicode filename encoding.
1882 Warning:
1884 In a future release, a bad type for argument Dir will probably
1885 generate an exception.
1886 sync(IoDevice) -> ok | {error, Reason}
1889 Types:
1891 IoDevice = io_device()
1893 Reason = posix() | badarg | terminated
1894 Ensures that any buffers kept by the operating system (not by
1896 the Erlang runtime system) are written to disk. On some plat‐
1897 forms, this function might have no effect.
1898 A typical error reason is:
1900 enospc:
1902 Not enough space left to write the file.
1903 truncate(IoDevice) -> ok | {error, Reason}
1905 Types:
1907 IoDevice = io_device()
1909 Reason = posix() | badarg | terminated
1910 Truncates the file referenced by IoDevice at the current posi‐
1912 tion. Returns ok if successful, otherwise {error, Reason}.
1913 write(IoDevice, Bytes) -> ok | {error, Reason}
1915 Types:
1917 IoDevice = io_device() | atom()
1919 Bytes = iodata()
1920 Reason = posix() | badarg | terminated
1921 Writes Bytes to the file referenced by IoDevice. This function
1923 is the only way to write to a file opened in raw mode (although
1924 it works for normally opened files too). Returns ok if success‐
1925 ful, and {error, Reason} otherwise.
1926 If the file is opened with encoding set to something else than
1928 latin1, each byte written can result in many bytes being written
1929 to the file, as the byte range 0..255 can represent anything
1930 between one and four bytes depending on value and UTF encoding
1931 type.
1932 Typical error reasons:
1934 ebadf:
1936 The file is not opened for writing.
1937 enospc:
1939 No space is left on the device.
1940 write_file(Filename, Bytes) -> ok | {error, Reason}
1942 Types:
1944 Filename = name_all()
1946 Bytes = iodata()
1947 Reason = posix() | badarg | terminated | system_limit
1948 Writes the contents of the iodata term Bytes to file Filename.
1950 The file is created if it does not exist. If it exists, the pre‐
1951 vious contents are overwritten. Returns ok if successful, other‐
1952 wise {error, Reason}.
1953 Typical error reasons:
1955 enoent:
1957 A component of the filename does not exist.
1958 enotdir:
1960 A component of the filename is not a directory. On some
1961 platforms, enoent is returned instead.
1962 enospc:
1964 No space is left on the device.
1965 eacces:
1967 Missing permission for writing the file or searching one of
1968 the parent directories.
1969 eisdir:
1971 The named file is a directory.
1972 write_file(Filename, Bytes, Modes) -> ok | {error, Reason}
1974 Types:
1976 Filename = name_all()
1978 Bytes = iodata()
1979 Modes = [mode()]
1980 Reason = posix() | badarg | terminated | system_limit
1981 Same as write_file/2, but takes a third argument Modes, a list
1983 of possible modes, see open/2. The mode flags binary and write
1984 are implicit, so they are not to be used.
1985 write_file_info(Filename, FileInfo) -> ok | {error, Reason}
1987 write_file_info(Filename, FileInfo, Opts) -> ok | {error, Reason}
1989 Types:
1991 Filename = name_all()
1993 Opts = [file_info_option()]
1994 FileInfo = file_info()
1995 Reason = posix() | badarg
1996 Changes file information. Returns ok if successful, otherwise
1998 {error, Reason}. FileInfo is a record file_info, defined in the
1999 Kernel include file file.hrl. Include the following directive in
2000 the module from which the function is called:
2001 -include_lib("kernel/include/file.hrl").
2003 The time type set in atime, mtime, and ctime depends on the time
2005 type set in Opts :: {time, Type} as follows:
2006 local:
2008 Interprets the time set as local.
2009 universal:
2011 Interprets it as universal time.
2012 posix:
2014 Must be seconds since or before Unix time epoch, which is
2015 1970-01-01 00:00 UTC.
2016 Default is {time, local}.
2018 If the option raw is set, the file server is not called and only
2020 information about local files is returned.
2021 The following fields are used from the record, if they are spec‐
2023 ified:
2024 atime = date_time() | integer() >= 0:
2026 The last time the file was read.
2027 mtime = date_time() | integer() >= 0:
2029 The last time the file was written.
2030 ctime = date_time() | integer() >= 0:
2032 On Unix, any value specified for this field is ignored (the
2033 "ctime" for the file is set to the current time). On Win‐
2034 dows, this field is the new creation time to set for the
2035 file.
2036 mode = integer() >= 0:
2038 The file permissions as the sum of the following bit values:
2039 8#00400:
2041 Read permission: owner
2042 8#00200:
2044 Write permission: owner
2045 8#00100:
2047 Execute permission: owner
2048 8#00040:
2050 Read permission: group
2051 8#00020:
2053 Write permission: group
2054 8#00010:
2056 Execute permission: group
2057 8#00004:
2059 Read permission: other
2060 8#00002:
2062 Write permission: other
2063 8#00001:
2065 Execute permission: other
2066 16#800:
2068 Set user id on execution
2069 16#400:
2071 Set group id on execution
2072 On Unix platforms, other bits than those listed above may be
2074 set.
2075 uid = integer() >= 0:
2077 Indicates the file owner. Ignored for non-Unix file systems.
2078 gid = integer() >= 0:
2080 Gives the group that the file owner belongs to. Ignored for
2081 non-Unix file systems.
2082 Typical error reasons:
2084 eacces:
2086 Missing search permission for one of the parent directories
2087 of the file.
2088 enoent:
2090 The file does not exist.
2091 enotdir:
2093 A component of the filename is not a directory. On some
2094 platforms, enoent is returned instead.
2095
2097 * eacces - Permission denied
2098 * eagain - Resource temporarily unavailable
2100 * ebadf - Bad file number
2102 * ebusy - File busy
2104 * edquot - Disk quota exceeded
2106 * eexist - File already exists
2108 * efault - Bad address in system call argument
2110 * efbig - File too large
2112 * eintr - Interrupted system call
2114 * einval - Invalid argument
2116 * eio - I/O error
2118 * eisdir - Illegal operation on a directory
2120 * eloop - Too many levels of symbolic links
2122 * emfile - Too many open files
2124 * emlink - Too many links
2126 * enametoolong - Filename too long
2128 * enfile - File table overflow
2130 * enodev - No such device
2132 * enoent - No such file or directory
2134 * enomem - Not enough memory
2136 * enospc - No space left on device
2138 * enotblk - Block device required
2140 * enotdir - Not a directory
2142 * enotsup - Operation not supported
2144 * enxio - No such device or address
2146 * eperm - Not owner
2148 * epipe - Broken pipe
2150 * erofs - Read-only file system
2152 * espipe - Invalid seek
2154 * esrch - No such process
2156 * estale - Stale remote file handle
2158 * exdev - Cross-domain link
2160
2162 For increased performance, raw files are recommended.
2163 A normal file is really a process so it can be used as an I/O device
2165 (see io). Therefore, when data is written to a normal file, the sending
2166 of the data to the file process, copies all data that are not binaries.
2167 Opening the file in binary mode and writing binaries is therefore rec‐
2168 ommended. If the file is opened on another node, or if the file server
2169 runs as slave to the file server of another node, also binaries are
2170 copied.
2171 Note:
2173 Raw files use the file system of the host machine of the node. For nor‐
2174 mal files (non-raw), the file server is used to find the files, and if
2175 the node is running its file server as slave to the file server of
2176 another node, and the other node runs on some other host machine, they
2177 can have different file systems. However, this is seldom a problem.
2178 open/2 can be given the options delayed_write and read_ahead to turn on
2181 caching, which will reduce the number of operating system calls and
2182 greatly improve performance for small reads and writes. However, the
2183 overhead won't disappear completely and it's best to keep the number of
2184 file operations to a minimum. As a contrived example, the following
2185 function writes 4MB in 2.5 seconds when tested:
2186 create_file_slow(Name) ->
2188 {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2189 create_file_slow_1(Fd, 4 bsl 20),
2190 file:close(Fd).
2191 create_file_slow_1(_Fd, 0) ->
2193 ok;
2194 create_file_slow_1(Fd, M) ->
2195 ok = file:write(Fd, <<0>>),
2196 create_file_slow_1(Fd, M - 1).
2197 The following functionally equivalent code writes 128 bytes per call to
2199 write/2 and so does the same work in 0.08 seconds, which is roughly 30
2200 times faster:
2201 create_file(Name) ->
2203 {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2204 create_file_1(Fd, 4 bsl 20),
2205 file:close(Fd),
2206 ok.
2207 create_file_1(_Fd, 0) ->
2209 ok;
2210 create_file_1(Fd, M) when M >= 128 ->
2211 ok = file:write(Fd, <<0:(128)/unit:8>>),
2212 create_file_1(Fd, M - 128);
2213 create_file_1(Fd, M) ->
2214 ok = file:write(Fd, <<0:(M)/unit:8>>),
2215 create_file_1(Fd, M - 1).
2216 When writing data it's generally more efficient to write a list of
2218 binaries rather than a list of integers. It is not needed to flatten a
2219 deep list before writing. On Unix hosts, scatter output, which writes a
2220 set of buffers in one operation, is used when possible. In this way
2221 write(FD, [Bin1, Bin2 | Bin3]) writes the contents of the binaries
2222 without copying the data at all, except for perhaps deep down in the
2223 operating system kernel.
2224 Warning:
2226 If an error occurs when accessing an open file with module io, the
2227 process handling the file exits. The dead file process can hang if a
2228 process tries to access it later. This will be fixed in a future
2229 release.
2230
2233 filename(3)
2234Ericsson AB kernel 6.3.1.1 file(3)