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 On operating systems with thread support, file operations can be per‐
12 formed in threads of their own, allowing other Erlang processes to con‐
13 tinue executing in parallel with the file operations. See command-line
14 flag +A in erl(1).
15 Regarding filename encoding, the Erlang VM can operate in two modes.
17 The current mode can be queried using function native_name_encoding/0.
18 It returns latin1 or utf8.
19 In latin1 mode, the Erlang VM does not change the encoding of file‐
21 names. In utf8 mode, filenames can contain Unicode characters greater
22 than 255 and the VM converts filenames back and forth to the native
23 filename encoding (usually UTF-8, but UTF-16 on Windows).
24 The default mode depends on the operating system. Windows and MacOS X
26 enforce consistent filename encoding and therefore the VM uses utf8
27 mode.
28 On operating systems with transparent naming (for example, all Unix
30 systems except MacOS X), default is utf8 if the terminal supports
31 UTF-8, otherwise latin1. The default can be overridden using +fnl (to
32 force latin1 mode) or +fnu (to force utf8 mode) when starting erts:erl.
33 On operating systems with transparent naming, files can be inconsis‐
35 tently named, for example, some files are encoded in UTF-8 while others
36 are encoded in ISO Latin-1. The concept of raw filenames is introduced
37 to handle file systems with inconsistent naming when running in utf8
38 mode.
39 A raw filename is a filename specified as a binary. The Erlang VM does
41 not translate a filename specified as a binary on systems with trans‐
42 parent naming.
43 When running in utf8 mode, functions list_dir/1 and read_link/1 never
45 return raw filenames. To return all filenames including raw filenames,
46 use functions list_dir_all/1 and read_link_all/1.
47 See also section Notes About Raw Filenames in the STDLIB User's Guide.
49
51 deep_list() = [char() | atom() | deep_list()]
52 fd()
54 A file descriptor representing a file opened in raw mode.
56 filename() = string()
58 filename_all() = string() | binary()
60 io_device() = pid() | fd()
62 As returned by open/2; pid() is a process handling I/O-proto‐
64 cols.
65 name() = string() | atom() | deep_list()
67 If VM is in Unicode filename mode, string() and char() are
69 allowed to be > 255.
70 name_all() =
72 string() | atom() | deep_list() | (RawFilename :: binary())
73 If VM is in Unicode filename mode, string() and char() are
75 allowed to be > 255. RawFilename is a filename not subject to
76 Unicode translation, meaning that it can contain characters not
77 conforming to the Unicode encoding expected from the file system
78 (that is, non-UTF-8 characters although the VM is started in
79 Unicode filename mode).
80 posix() =
82 eacces |
83 eagain |
84 ebadf |
85 ebusy |
86 edquot |
87 eexist |
88 efault |
89 efbig |
90 eintr |
91 einval |
92 eio |
93 eisdir |
94 eloop |
95 emfile |
96 emlink |
97 enametoolong |
98 enfile |
99 enodev |
100 enoent |
101 enomem |
102 enospc |
103 enotblk |
104 enotdir |
105 enotsup |
106 enxio |
107 eperm |
108 epipe |
109 erofs |
110 espipe |
111 esrch |
112 estale |
113 exdev
114 An atom that is named from the POSIX error codes used in Unix,
116 and in the runtime libraries of most C compilers.
117 date_time() = calendar:datetime()
119 Must denote a valid date and time.
121 file_info() =
123 #file_info{size = integer() >= 0 | undefined,
124 type =
125 device |
126 directory |
127 other |
128 regular |
129 symlink |
130 undefined,
131 access =
132 read | write | read_write | none | undefined,
133 atime =
134 file:date_time() |
135 integer() >= 0 |
136 undefined,
137 mtime =
138 file:date_time() |
139 integer() >= 0 |
140 undefined,
141 ctime =
142 file:date_time() |
143 integer() >= 0 |
144 undefined,
145 mode = integer() >= 0 | undefined,
146 links = integer() >= 0 | undefined,
147 major_device = integer() >= 0 | undefined,
148 minor_device = integer() >= 0 | undefined,
149 inode = integer() >= 0 | undefined,
150 uid = integer() >= 0 | undefined,
151 gid = integer() >= 0 | undefined}
152 location() =
154 integer() |
155 {bof, Offset :: integer()} |
156 {cur, Offset :: integer()} |
157 {eof, Offset :: integer()} |
158 bof |
159 cur |
160 eof
161 mode() =
163 read |
164 write |
165 append |
166 exclusive |
167 raw |
168 binary |
169 {delayed_write,
170 Size :: integer() >= 0,
171 Delay :: integer() >= 0} |
172 delayed_write |
173 {read_ahead, Size :: integer() >= 1} |
174 read_ahead |
175 compressed |
176 {encoding, unicode:encoding()} |
177 sync
178 file_info_option() =
180 {time, local} | {time, universal} | {time, posix} | raw
181
183 advise(IoDevice, Offset, Length, Advise) -> ok | {error, Reason}
184 Types:
186 IoDevice = io_device()
188 Offset = Length = integer()
189 Advise = posix_file_advise()
190 Reason = posix() | badarg
191 posix_file_advise() =
192 normal |
193 sequential |
194 random |
195 no_reuse |
196 will_need |
197 dont_need
198 advise/4 can be used to announce an intention to access file
200 data in a specific pattern in the future, thus allowing the
201 operating system to perform appropriate optimizations.
202 On some platforms, this function might have no effect.
204 allocate(File, Offset, Length) -> ok | {error, posix()}
206 Types:
208 File = io_device()
210 Offset = Length = integer() >= 0
211 allocate/3 can be used to preallocate space for a file.
213 This function only succeeds in platforms that provide this fea‐
215 ture. When it succeeds, space is preallocated for the file but
216 the file size might not be updated. This behaviour depends on
217 the preallocation implementation. To guarantee that the file
218 size is updated, truncate the file to the new size.
219 change_group(Filename, Gid) -> ok | {error, Reason}
221 Types:
223 Filename = name_all()
225 Gid = integer()
226 Reason = posix() | badarg
227 Changes group of a file. See write_file_info/2.
229 change_mode(Filename, Mode) -> ok | {error, Reason}
231 Types:
233 Filename = name_all()
235 Mode = integer()
236 Reason = posix() | badarg
237 Changes permissions of a file. See write_file_info/2.
239 change_owner(Filename, Uid) -> ok | {error, Reason}
241 Types:
243 Filename = name_all()
245 Uid = integer()
246 Reason = posix() | badarg
247 Changes owner of a file. See write_file_info/2.
249 change_owner(Filename, Uid, Gid) -> ok | {error, Reason}
251 Types:
253 Filename = name_all()
255 Uid = Gid = integer()
256 Reason = posix() | badarg
257 Changes owner and group of a file. See write_file_info/2.
259 change_time(Filename, Mtime) -> ok | {error, Reason}
261 Types:
263 Filename = name_all()
265 Mtime = date_time()
266 Reason = posix() | badarg
267 Changes the modification and access times of a file. See
269 write_file_info/2.
270 change_time(Filename, Atime, Mtime) -> ok | {error, Reason}
272 Types:
274 Filename = name_all()
276 Atime = Mtime = date_time()
277 Reason = posix() | badarg
278 Changes the modification and last access times of a file. See
280 write_file_info/2.
281 close(IoDevice) -> ok | {error, Reason}
283 Types:
285 IoDevice = io_device()
287 Reason = posix() | badarg | terminated
288 Closes the file referenced by IoDevice. It mostly returns ok,
290 except for some severe errors such as out of memory.
291 Notice that if option delayed_write was used when opening the
293 file, close/1 can return an old write error and not even try to
294 close the file. See open/2.
295 consult(Filename) -> {ok, Terms} | {error, Reason}
297 Types:
299 Filename = name_all()
301 Terms = [term()]
302 Reason =
303 posix() |
304 badarg |
305 terminated |
306 system_limit |
307 {Line :: integer(), Mod :: module(), Term :: term()}
308 Reads Erlang terms, separated by '.', from Filename. Returns one
310 of the following:
311 {ok, Terms}:
313 The file was successfully read.
314 {error, atom()}:
316 An error occurred when opening the file or reading it. For a
317 list of typical error codes, see open/2.
318 {error, {Line, Mod, Term}}:
320 An error occurred when interpreting the Erlang terms in the
321 file. To convert the three-element tuple to an English
322 description of the error, use format_error/1.
323 Example:
325 f.txt: {person, "kalle", 25}.
327 {person, "pelle", 30}.
328 1> file:consult("f.txt").
330 {ok,[{person,"kalle",25},{person,"pelle",30}]}
331 The encoding of Filename can be set by a comment, as described
333 in epp(3).
334 copy(Source, Destination) -> {ok, BytesCopied} | {error, Reason}
336 copy(Source, Destination, ByteCount) ->
338 {ok, BytesCopied} | {error, Reason}
339 Types:
341 Source = Destination = io_device() | Filename | {Filename,
343 Modes}
344 Filename = name_all()
345 Modes = [mode()]
346 ByteCount = integer() >= 0 | infinity
347 BytesCopied = integer() >= 0
348 Reason = posix() | badarg | terminated
349 Copies ByteCount bytes from Source to Destination. Source and
351 Destination refer to either filenames or IO devices from, for
352 example, open/2. ByteCount defaults to infinity, denoting an
353 infinite number of bytes.
354 Argument Modes is a list of possible modes, see open/2, and
356 defaults to [].
357 If both Source and Destination refer to filenames, the files are
359 opened with [read, binary] and [write, binary] prepended to
360 their mode lists, respectively, to optimize the copy.
361 If Source refers to a filename, it is opened with read mode
363 prepended to the mode list before the copy, and closed when
364 done.
365 If Destination refers to a filename, it is opened with write
367 mode prepended to the mode list before the copy, and closed when
368 done.
369 Returns {ok, BytesCopied}, where BytesCopied is the number of
371 bytes that was copied, which can be less than ByteCount if end
372 of file was encountered on the source. If the operation fails,
373 {error, Reason} is returned.
374 Typical error reasons: as for open/2 if a file had to be opened,
376 and as for read/2 and write/2.
377 datasync(IoDevice) -> ok | {error, Reason}
379 Types:
381 IoDevice = io_device()
383 Reason = posix() | badarg | terminated
384 Ensures that any buffers kept by the operating system (not by
386 the Erlang runtime system) are written to disk. In many ways it
387 resembles fsync but it does not update some of the metadata of
388 the file, such as the access time. On some platforms this func‐
389 tion has no effect.
390 Applications that access databases or log files often write a
392 tiny data fragment (for example, one line in a log file) and
393 then call fsync() immediately to ensure that the written data is
394 physically stored on the hard disk. Unfortunately, fsync()
395 always initiates two write operations: one for the newly written
396 data and another one to update the modification time stored in
397 the inode. If the modification time is not a part of the trans‐
398 action concept, fdatasync() can be used to avoid unnecessary
399 inode disk write operations.
400 Available only in some POSIX systems, this call results in a
402 call to fsync(), or has no effect in systems not providing the
403 fdatasync() syscall.
404 del_dir(Dir) -> ok | {error, Reason}
406 Types:
408 Dir = name_all()
410 Reason = posix() | badarg
411 Tries to delete directory Dir. The directory must be empty
413 before it can be deleted. Returns ok if successful.
414 Typical error reasons:
416 eacces:
418 Missing search or write permissions for the parent directo‐
419 ries of Dir.
420 eexist:
422 The directory is not empty.
423 enoent:
425 The directory does not exist.
426 enotdir:
428 A component of Dir is not a directory. On some platforms,
429 enoent is returned instead.
430 einval:
432 Attempt to delete the current directory. On some platforms,
433 eacces is returned instead.
434 delete(Filename) -> ok | {error, Reason}
436 Types:
438 Filename = name_all()
440 Reason = posix() | badarg
441 Tries to delete file Filename. Returns ok if successful.
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 |
475 terminated |
476 system_limit |
477 {Line :: integer(), Mod :: module(), Term :: term()}
478 Reads and evaluates Erlang expressions, separated by '.' (or
480 ',', a sequence of expressions is also an expression) from File‐
481 name. The result of the evaluation is not returned; any expres‐
482 sion sequence in the file must be there for its side effect.
483 Returns one of the following:
484 ok:
486 The file was read and evaluated.
487 {error, atom()}:
489 An error occurred when opening the file or reading it. For a
490 list of typical error codes, see open/2.
491 {error, {Line, Mod, Term}}:
493 An error occurred when interpreting the Erlang expressions
494 in the file. To convert the three-element tuple to an Eng‐
495 lish description of the error, use format_error/1.
496 The encoding of Filename can be set by a comment, as described
498 in epp(3).
499 eval(Filename, Bindings) -> ok | {error, Reason}
501 Types:
503 Filename = name_all()
505 Bindings = erl_eval:binding_struct()
506 Reason =
507 posix() |
508 badarg |
509 terminated |
510 system_limit |
511 {Line :: integer(), Mod :: module(), Term :: term()}
512 The same as eval/1, but the variable bindings Bindings are used
514 in the evaluation. For information about the variable bindings,
515 see erl_eval(3).
516 format_error(Reason) -> Chars
518 Types:
520 Reason =
522 posix() |
523 badarg |
524 terminated |
525 system_limit |
526 {Line :: integer(), Mod :: module(), Term :: term()}
527 Chars = string()
528 Given the error reason returned by any function in this module,
530 returns a descriptive string of the error in English.
531 get_cwd() -> {ok, Dir} | {error, Reason}
533 Types:
535 Dir = filename()
537 Reason = posix()
538 Returns {ok, Dir}, where Dir is the current working directory of
540 the file server.
541 Note:
543 In rare circumstances, this function can fail on Unix. It can
544 occur if read permission does not exist for the parent directo‐
545 ries of the current directory.
546 A typical error reason:
549 eacces:
551 Missing read permission for one of the parents of the cur‐
552 rent directory.
553 get_cwd(Drive) -> {ok, Dir} | {error, Reason}
555 Types:
557 Drive = string()
559 Dir = filename()
560 Reason = posix() | badarg
561 Returns {ok, Dir} or {error, Reason}, where Dir is the current
563 working directory of the specified drive.
564 Drive is to be of the form "Letter:", for example, "c:".
566 Returns {error, enotsup} on platforms that have no concept of
568 current drive (Unix, for example).
569 Typical error reasons:
571 enotsup:
573 The operating system has no concept of drives.
574 eacces:
576 The drive does not exist.
577 einval:
579 The format of Drive is invalid.
580 list_dir(Dir) -> {ok, Filenames} | {error, Reason}
582 Types:
584 Dir = name_all()
586 Filenames = [filename()]
587 Reason =
588 posix() |
589 badarg |
590 {no_translation, Filename :: unicode:latin1_binary()}
591 Lists all files in a directory, except files with raw filenames.
593 Returns {ok, Filenames} if successful, otherwise {error, Rea‐
594 son}. Filenames is a list of the names of all the files in the
595 directory. The names are not sorted.
596 Typical error reasons:
598 eacces:
600 Missing search or write permissions for Dir or one of its
601 parent directories.
602 enoent:
604 The directory does not exist.
605 {no_translation, Filename}:
607 Filename is a binary() with characters coded in ISO Latin-1
608 and the VM was started with parameter +fnue.
609 list_dir_all(Dir) -> {ok, Filenames} | {error, Reason}
611 Types:
613 Dir = name_all()
615 Filenames = [filename_all()]
616 Reason = posix() | badarg
617 Lists all the files in a directory, including files with raw
619 filenames. Returns {ok, Filenames} if successful, otherwise
620 {error, Reason}. Filenames is a list of the names of all the
621 files in the directory. The names are not sorted.
622 Typical error reasons:
624 eacces:
626 Missing search or write permissions for Dir or one of its
627 parent directories.
628 enoent:
630 The directory does not exist.
631 make_dir(Dir) -> ok | {error, Reason}
633 Types:
635 Dir = name_all()
637 Reason = posix() | badarg
638 Tries to create directory Dir. Missing parent directories are
640 not created. Returns ok if successful.
641 Typical error reasons:
643 eacces:
645 Missing search or write permissions for the parent directo‐
646 ries of Dir.
647 eexist:
649 A file or directory named Dir exists already.
650 enoent:
652 A component of Dir does not exist.
653 enospc:
655 No space is left on the device.
656 enotdir:
658 A component of Dir is not a directory. On some platforms,
659 enoent is returned instead.
660 make_link(Existing, New) -> ok | {error, Reason}
662 Types:
664 Existing = New = name_all()
666 Reason = posix() | badarg
667 Makes a hard link from Existing to New on platforms supporting
669 links (Unix and Windows). This function returns ok if the link
670 was successfully created, otherwise {error, Reason}. On plat‐
671 forms not supporting links, {error,enotsup} is returned.
672 Typical error reasons:
674 eacces:
676 Missing read or write permissions for the parent directories
677 of Existing or New.
678 eexist:
680 New already exists.
681 enotsup:
683 Hard links are not supported on this platform.
684 make_symlink(Existing, New) -> ok | {error, Reason}
686 Types:
688 Existing = New = name_all()
690 Reason = posix() | badarg
691 Creates a symbolic link New to the file or directory Existing on
693 platforms supporting symbolic links (most Unix systems and Win‐
694 dows, beginning with Vista). Existing does not need to exist.
695 Returns ok if the link is successfully created, otherwise
696 {error, Reason}. On platforms not supporting symbolic links,
697 {error, enotsup} is returned.
698 Typical error reasons:
700 eacces:
702 Missing read or write permissions for the parent directories
703 of Existing or New.
704 eexist:
706 New already exists.
707 enotsup:
709 Symbolic links are not supported on this platform.
710 eperm:
712 User does not have privileges to create symbolic links
713 (SeCreateSymbolicLinkPrivilege on Windows).
714 native_name_encoding() -> latin1 | utf8
716 Returns the filename encoding mode. If it is latin1, the system
718 translates no filenames. If it is utf8, filenames are converted
719 back and forth to the native filename encoding (usually UTF-8,
720 but UTF-16 on Windows).
721 open(File, Modes) -> {ok, IoDevice} | {error, Reason}
723 Types:
725 File = Filename | iodata()
727 Filename = name_all()
728 Modes = [mode() | ram]
729 IoDevice = io_device()
730 Reason = posix() | badarg | system_limit
731 Opens file File in the mode determined by Modes, which can con‐
733 tain one or more of the following options:
734 read:
736 The file, which must exist, is opened for reading.
737 write:
739 The file is opened for writing. It is created if it does not
740 exist. If the file exists and write is not combined with
741 read, the file is truncated.
742 append:
744 The file is opened for writing. It is created if it does not
745 exist. Every write operation to a file opened with append
746 takes place at the end of the file.
747 exclusive:
749 The file is opened for writing. It is created if it does not
750 exist. If the file exists, {error, eexist} is returned.
751 Warning:
753 This option does not guarantee exclusiveness on file systems
754 not supporting O_EXCL properly, such as NFS. Do not depend on
755 this option unless you know that the file system supports it
756 (in general, local file systems are safe).
757 raw:
760 Allows faster access to a file, as no Erlang process is
761 needed to handle the file. However, a file opened in this
762 way has the following limitations:
763 * The functions in the io module cannot be used, as they can
765 only talk to an Erlang process. Instead, use functions
766 read/2, read_line/1, and write/2.
767 * Especially if read_line/1 is to be used on a raw file, it
769 is recommended to combine this option with option
770 {read_ahead, Size} as line-oriented I/O is inefficient
771 without buffering.
772 * Only the Erlang process that opened the file can use it.
774 * A remote Erlang file server cannot be used. The computer
776 on which the Erlang node is running must have access to
777 the file system (directly or through NFS).
778 binary:
780 Read operations on the file return binaries rather than
781 lists.
782 {delayed_write, Size, Delay}:
784 Data in subsequent write/2 calls is buffered until at least
785 Size bytes are buffered, or until the oldest buffered data
786 is Delay milliseconds old. Then all buffered data is written
787 in one operating system call. The buffered data is also
788 flushed before some other file operation than write/2 is
789 executed.
790 The purpose of this option is to increase performance by
792 reducing the number of operating system calls. Thus, the
793 write/2 calls must be for sizes significantly less than
794 Size, and not interspersed by too many other file opera‐
795 tions.
796 When this option is used, the result of write/2 calls can
798 prematurely be reported as successful, and if a write error
799 occurs, the error is reported as the result of the next file
800 operation, which is not executed.
801 For example, when delayed_write is used, after a number of
803 write/2 calls, close/1 can return {error, enospc}, as there
804 is not enough space on the disc for previously written data.
805 close/1 must probably be called again, as the file is still
806 open.
807 delayed_write:
809 The same as {delayed_write, Size, Delay} with reasonable
810 default values for Size and Delay (roughly some 64 KB, 2
811 seconds).
812 {read_ahead, Size}:
814 Activates read data buffering. If read/2 calls are for sig‐
815 nificantly less than Size bytes, read operations to the
816 operating system are still performed for blocks of Size
817 bytes. The extra data is buffered and returned in subsequent
818 read/2 calls, giving a performance gain as the number of
819 operating system calls is reduced.
820 The read_ahead buffer is also highly used by function
822 read_line/1 in raw mode, therefore this option is recom‐
823 mended (for performance reasons) when accessing raw files
824 using that function.
825 If read/2 calls are for sizes not significantly less than,
827 or even greater than Size bytes, no performance gain can be
828 expected.
829 read_ahead:
831 The same as {read_ahead, Size} with a reasonable default
832 value for Size (roughly some 64 KB).
833 compressed:
835 Makes it possible to read or write gzip compressed files.
836 Option compressed must be combined with read or write, but
837 not both. Notice that the file size obtained with
838 read_file_info/1 does probably not match the number of bytes
839 that can be read from a compressed file.
840 {encoding, Encoding}:
842 Makes the file perform automatic translation of characters
843 to and from a specific (Unicode) encoding. Notice that the
844 data supplied to write/2 or returned by read/2 still is
845 byte-oriented; this option denotes only how data is stored
846 in the disk file.
847 Depending on the encoding, different methods of reading and
849 writing data is preferred. The default encoding of latin1
850 implies using this module (file) for reading and writing
851 data as the interfaces provided here work with byte-oriented
852 data. Using other (Unicode) encodings makes the io(3) func‐
853 tions get_chars, get_line, and put_chars more suitable, as
854 they can work with the full Unicode range.
855 If data is sent to an io_device() in a format that cannot be
857 converted to the specified encoding, or if data is read by a
858 function that returns data in a format that cannot cope with
859 the character range of the data, an error occurs and the
860 file is closed.
861 Allowed values for Encoding:
863 latin1:
865 The default encoding. Bytes supplied to the file, that is,
866 write/2 are written "as is" on the file. Likewise, bytes
867 read from the file, that is, read/2 are returned "as is".
868 If module io(3) is used for writing, the file can only
869 cope with Unicode characters up to code point 255 (the ISO
870 Latin-1 range).
871 unicode or utf8:
873 Characters are translated to and from UTF-8 encoding
874 before they are written to or read from the file. A file
875 opened in this way can be readable using function read/2,
876 as long as no data stored on the file lies beyond the ISO
877 Latin-1 range (0..255), but failure occurs if the data
878 contains Unicode code points beyond that range. The file
879 is best read with the functions in the Unicode aware mod‐
880 ule io(3).
881 Bytes written to the file by any means are translated to
883 UTF-8 encoding before being stored on the disk file.
884 utf16 or {utf16,big}:
886 Works like unicode, but translation is done to and from
887 big endian UTF-16 instead of UTF-8.
888 {utf16,little}:
890 Works like unicode, but translation is done to and from
891 little endian UTF-16 instead of UTF-8.
892 utf32 or {utf32,big}:
894 Works like unicode, but translation is done to and from
895 big endian UTF-32 instead of UTF-8.
896 {utf32,little}:
898 Works like unicode, but translation is done to and from
899 little endian UTF-32 instead of UTF-8.
900 The Encoding can be changed for a file "on the fly" by using
902 function io:setopts/2. So a file can be analyzed in latin1
903 encoding for, for example, a BOM, positioned beyond the BOM
904 and then be set for the right encoding before further read‐
905 ing. For functions identifying BOMs, see module unicode(3).
906 This option is not allowed on raw files.
908 ram:
910 File must be iodata(). Returns an fd(), which lets module
911 file operate on the data in-memory as if it is a file.
912 sync:
914 On platforms supporting it, enables the POSIX O_SYNC syn‐
915 chronous I/O flag or its platform-dependent equivalent (for
916 example, FILE_FLAG_WRITE_THROUGH on Windows) so that writes
917 to the file block until the data is physically written to
918 disk. However, be aware that the exact semantics of this
919 flag differ from platform to platform. For example, none of
920 Linux or Windows guarantees that all file metadata are also
921 written before the call returns. For precise semantics,
922 check the details of your platform documentation. On plat‐
923 forms with no support for POSIX O_SYNC or equivalent, use of
924 the sync flag causes open to return {error, enotsup}.
925 Returns:
927 {ok, IoDevice}:
929 The file is opened in the requested mode. IoDevice is a ref‐
930 erence to the file.
931 {error, Reason}:
933 The file cannot be opened.
934 IoDevice is really the pid of the process that handles the file.
936 This process is linked to the process that originally opened the
937 file. If any process to which the IoDevice is linked terminates,
938 the file is closed and the process itself is terminated. An
939 IoDevice returned from this call can be used as an argument to
940 the I/O functions (see io(3)).
941 Note:
943 In previous versions of file, modes were specified as one of the
944 atoms read, write, or read_write instead of a list. This is
945 still allowed for reasons of backwards compatibility, but is not
946 to be used for new code. Also note that read_write is not
947 allowed in a mode list.
948 Typical error reasons:
951 enoent:
953 The file does not exist.
954 eacces:
956 Missing permission for reading the file or searching one of
957 the parent directories.
958 eisdir:
960 The named file is not a regular file. It can be a directory,
961 a FIFO, or a device.
962 enotdir:
964 A component of the filename is not a directory. On some
965 platforms, enoent is returned instead.
966 enospc:
968 There is no space left on the device (if write access was
969 specified).
970 path_consult(Path, Filename) ->
972 {ok, Terms, FullName} | {error, Reason}
973 Types:
975 Path = [Dir]
977 Dir = Filename = name_all()
978 Terms = [term()]
979 FullName = filename_all()
980 Reason =
981 posix() |
982 badarg |
983 terminated |
984 system_limit |
985 {Line :: integer(), Mod :: module(), Term :: term()}
986 Searches the path Path (a list of directory names) until the
988 file Filename is found. If Filename is an absolute filename,
989 Path is ignored. Then reads Erlang terms, separated by '.', from
990 the file.
991 Returns one of the following:
993 {ok, Terms, FullName}:
995 The file is successfully read. FullName is the full name of
996 the file.
997 {error, enoent}:
999 The file cannot be found in any of the directories in Path.
1000 {error, atom()}:
1002 An error occurred when opening the file or reading it. For a
1003 list of typical error codes, see open/2.
1004 {error, {Line, Mod, Term}}:
1006 An error occurred when interpreting the Erlang terms in the
1007 file. Use format_error/1 to convert the three-element tuple
1008 to an English description of the error.
1009 The encoding of Filename can be set by a comment as described in
1011 epp(3).
1012 path_eval(Path, Filename) -> {ok, FullName} | {error, Reason}
1014 Types:
1016 Path = [Dir :: name_all()]
1018 Filename = name_all()
1019 FullName = filename_all()
1020 Reason =
1021 posix() |
1022 badarg |
1023 terminated |
1024 system_limit |
1025 {Line :: integer(), Mod :: module(), Term :: term()}
1026 Searches the path Path (a list of directory names) until the
1028 file Filename is found. If Filename is an absolute filename,
1029 Path is ignored. Then reads and evaluates Erlang expressions,
1030 separated by '.' (or ',', a sequence of expressions is also an
1031 expression), from the file. The result of evaluation is not
1032 returned; any expression sequence in the file must be there for
1033 its side effect.
1034 Returns one of the following:
1036 {ok, FullName}:
1038 The file is read and evaluated. FullName is the full name of
1039 the file.
1040 {error, enoent}:
1042 The file cannot be found in any of the directories in Path.
1043 {error, atom()}:
1045 An error occurred when opening the file or reading it. For a
1046 list of typical error codes, see open/2.
1047 {error, {Line, Mod, Term}}:
1049 An error occurred when interpreting the Erlang expressions
1050 in the file. Use format_error/1 to convert the three-element
1051 tuple to an English description of the error.
1052 The encoding of Filename can be set by a comment as described in
1054 epp(3).
1055 path_open(Path, Filename, Modes) ->
1057 {ok, IoDevice, FullName} | {error, Reason}
1058 Types:
1060 Path = [Dir :: name_all()]
1062 Filename = name_all()
1063 Modes = [mode()]
1064 IoDevice = io_device()
1065 FullName = filename_all()
1066 Reason = posix() | badarg | system_limit
1067 Searches the path Path (a list of directory names) until the
1069 file Filename is found. If Filename is an absolute filename,
1070 Path is ignored. Then opens the file in the mode determined by
1071 Modes.
1072 Returns one of the following:
1074 {ok, IoDevice, FullName}:
1076 The file is opened in the requested mode. IoDevice is a ref‐
1077 erence to the file and FullName is the full name of the
1078 file.
1079 {error, enoent}:
1081 The file cannot be found in any of the directories in Path.
1082 {error, atom()}:
1084 The file cannot be opened.
1085 path_script(Path, Filename) ->
1087 {ok, Value, FullName} | {error, Reason}
1088 Types:
1090 Path = [Dir :: name_all()]
1092 Filename = name_all()
1093 Value = term()
1094 FullName = filename_all()
1095 Reason =
1096 posix() |
1097 badarg |
1098 terminated |
1099 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 |
1142 terminated |
1143 system_limit |
1144 {Line :: integer(), Mod :: module(), Term :: term()}
1145 The same as path_script/2 but the variable bindings Bindings are
1147 used in the evaluation. See erl_eval(3) about variable bindings.
1148 pid2name(Pid) -> {ok, Filename} | undefined
1150 Types:
1152 Filename = filename_all()
1154 Pid = pid()
1155 If Pid is an I/O device, that is, a pid returned from open/2,
1157 this function returns the filename, or rather:
1158 {ok, Filename}:
1160 If the file server of this node is not a slave, the file was
1161 opened by the file server of this node (this implies that
1162 Pid must be a local pid) and the file is not closed. File‐
1163 name is the filename in flat string format.
1164 undefined:
1166 In all other cases.
1167 Warning:
1169 This function is intended for debugging only.
1170 position(IoDevice, Location) ->
1173 {ok, NewPosition} | {error, Reason}
1174 Types:
1176 IoDevice = io_device()
1178 Location = location()
1179 NewPosition = integer()
1180 Reason = posix() | badarg | terminated
1181 Sets the position of the file referenced by IoDevice to Loca‐
1183 tion. Returns {ok, NewPosition} (as absolute offset) if success‐
1184 ful, otherwise {error, Reason}. Location is one of the follow‐
1185 ing:
1186 Offset:
1188 The same as {bof, Offset}.
1189 {bof, Offset}:
1191 Absolute offset.
1192 {cur, Offset}:
1194 Offset from the current position.
1195 {eof, Offset}:
1197 Offset from the end of file.
1198 bof | cur | eof:
1200 The same as above with Offset 0.
1201 Notice that offsets are counted in bytes, not in characters. If
1203 the file is opened using some other encoding than latin1, one
1204 byte does not correspond to one character. Positioning in such a
1205 file can only be done to known character boundaries. That is, to
1206 a position earlier retrieved by getting a current position, to
1207 the beginning/end of the file or to some other position known to
1208 be on a correct character boundary by some other means (typi‐
1209 cally beyond a byte order mark in the file, which has a known
1210 byte-size).
1211 A typical error reason is:
1213 einval:
1215 Either Location is illegal, or it is evaluated to a negative
1216 offset in the file. Notice that if the resulting position is
1217 a negative value, the result is an error, and after the call
1218 the file position is undefined.
1219 pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason}
1221 Types:
1223 IoDevice = io_device()
1225 LocNums =
1226 [{Location :: location(), Number :: integer() >= 0}]
1227 DataL = [Data]
1228 Data = string() | binary() | eof
1229 Reason = posix() | badarg | terminated
1230 Performs a sequence of pread/3 in one operation, which is more
1232 efficient than calling them one at a time. Returns {ok, [Data,
1233 ...]} or {error, Reason}, where each Data, the result of the
1234 corresponding pread, is either a list or a binary depending on
1235 the mode of the file, or eof if the requested position is beyond
1236 end of file.
1237 As the position is specified as a byte-offset, take special cau‐
1239 tion when working with files where encoding is set to something
1240 else than latin1, as not every byte position is a valid charac‐
1241 ter boundary on such a file.
1242 pread(IoDevice, Location, Number) ->
1244 {ok, Data} | eof | {error, Reason}
1245 Types:
1247 IoDevice = io_device()
1249 Location = location()
1250 Number = integer() >= 0
1251 Data = string() | binary()
1252 Reason = posix() | badarg | terminated
1253 Combines position/2 and read/2 in one operation, which is more
1255 efficient than calling them one at a time. If IoDevice is opened
1256 in raw mode, some restrictions apply:
1257 * Location is only allowed to be an integer.
1259 * The current position of the file is undefined after the
1261 operation.
1262 As the position is specified as a byte-offset, take special cau‐
1264 tion when working with files where encoding is set to something
1265 else than latin1, as not every byte position is a valid charac‐
1266 ter boundary on such a file.
1267 pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}}
1269 Types:
1271 IoDevice = io_device()
1273 LocBytes = [{Location :: location(), Bytes :: iodata()}]
1274 N = integer() >= 0
1275 Reason = posix() | badarg | terminated
1276 Performs a sequence of pwrite/3 in one operation, which is more
1278 efficient than calling them one at a time. Returns ok or {error,
1279 {N, Reason}}, where N is the number of successful writes done
1280 before the failure.
1281 When positioning in a file with other encoding than latin1, cau‐
1283 tion must be taken to set the position on a correct character
1284 boundary. For details, see position/2.
1285 pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason}
1287 Types:
1289 IoDevice = io_device()
1291 Location = location()
1292 Bytes = iodata()
1293 Reason = posix() | badarg | terminated
1294 Combines position/2 and write/2 in one operation, which is more
1296 efficient than calling them one at a time. If IoDevice has been
1297 opened in raw mode, some restrictions apply:
1298 * Location is only allowed to be an integer.
1300 * The current position of the file is undefined after the
1302 operation.
1303 When positioning in a file with other encoding than latin1, cau‐
1305 tion must be taken to set the position on a correct character
1306 boundary. For details, see position/2.
1307 read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}
1309 Types:
1311 IoDevice = io_device() | atom()
1313 Number = integer() >= 0
1314 Data = string() | binary()
1315 Reason =
1316 posix() |
1317 badarg |
1318 terminated |
1319 {no_translation, unicode, latin1}
1320 Reads Number bytes/characters from the file referenced by IoDe‐
1322 vice. The functions read/2, pread/3, and read_line/1 are the
1323 only ways to read from a file opened in raw mode (although they
1324 work for normally opened files, too).
1325 For files where encoding is set to something else than latin1,
1327 one character can be represented by more than one byte on the
1328 file. The parameter Number always denotes the number of charac‐
1329 ters read from the file, while the position in the file can be
1330 moved much more than this number when reading a Unicode file.
1331 Also, if encoding is set to something else than latin1, the
1333 read/3 call fails if the data contains characters larger than
1334 255, which is why module io(3) is to be preferred when reading
1335 such a file.
1336 The function returns:
1338 {ok, Data}:
1340 If the file was opened in binary mode, the read bytes are
1341 returned in a binary, otherwise in a list. The list or
1342 binary is shorter than the number of bytes requested if end
1343 of file was reached.
1344 eof:
1346 Returned if Number>0 and end of file was reached before any‐
1347 thing at all could be read.
1348 {error, Reason}:
1350 An error occurred.
1351 Typical error reasons:
1353 ebadf:
1355 The file is not opened for reading.
1356 {no_translation, unicode, latin1}:
1358 The file is opened with another encoding than latin1 and the
1359 data in the file cannot be translated to the byte-oriented
1360 data that this function returns.
1361 read_file(Filename) -> {ok, Binary} | {error, Reason}
1363 Types:
1365 Filename = name_all()
1367 Binary = binary()
1368 Reason = posix() | badarg | terminated | system_limit
1369 Returns {ok, Binary}, where Binary is a binary data object that
1371 contains the contents of Filename, or {error, Reason} if an
1372 error occurs.
1373 Typical error reasons:
1375 enoent:
1377 The file does not exist.
1378 eacces:
1380 Missing permission for reading the file, or for searching
1381 one of the parent directories.
1382 eisdir:
1384 The named file is a directory.
1385 enotdir:
1387 A component of the filename is not a directory. On some
1388 platforms, enoent is returned instead.
1389 enomem:
1391 There is not enough memory for the contents of the file.
1392 read_file_info(Filename) -> {ok, FileInfo} | {error, Reason}
1394 read_file_info(Filename, Opts) -> {ok, FileInfo} | {error, Reason}
1396 Types:
1398 Filename = name_all()
1400 Opts = [file_info_option()]
1401 FileInfo = file_info()
1402 Reason = posix() | badarg
1403 Retrieves information about a file. Returns {ok, FileInfo} if
1405 successful, otherwise {error, Reason}. FileInfo is a record
1406 file_info, defined in the Kernel include file file.hrl. Include
1407 the following directive in the module from which the function is
1408 called:
1409 -include_lib("kernel/include/file.hrl").
1411 The time type returned in atime, mtime, and ctime is dependent
1413 on the time type set in Opts :: {time, Type} as follows:
1414 local:
1416 Returns local time.
1417 universal:
1419 Returns universal time.
1420 posix:
1422 Returns seconds since or before Unix time epoch, which is
1423 1970-01-01 00:00 UTC.
1424 Default is {time, local}.
1426 If the option raw is set, the file server is not called and only
1428 information about local files is returned.
1429 Note:
1431 As file times are stored in POSIX time on most OS, it is faster
1432 to query file information with option posix.
1433 The record file_info contains the following fields:
1436 size = integer() >= 0:
1438 Size of file in bytes.
1439 type = device | directory | other | regular | symlink:
1441 The type of the file.
1442 access = read | write | read_write | none:
1444 The current system access to the file.
1445 atime = date_time() | integer() >= 0:
1447 The last time the file was read.
1448 mtime = date_time() | integer() >= 0:
1450 The last time the file was written.
1451 ctime = date_time() | integer() >=0:
1453 The interpretation of this time field depends on the operat‐
1454 ing system. On Unix, it is the last time the file or the
1455 inode was changed. In Windows, it is the create time.
1456 mode = integer() >= 0:
1458 The file permissions as the sum of the following bit values:
1459 8#00400:
1461 read permission: owner
1462 8#00200:
1464 write permission: owner
1465 8#00100:
1467 execute permission: owner
1468 8#00040:
1470 read permission: group
1471 8#00020:
1473 write permission: group
1474 8#00010:
1476 execute permission: group
1477 8#00004:
1479 read permission: other
1480 8#00002:
1482 write permission: other
1483 8#00001:
1485 execute permission: other
1486 16#800:
1488 set user id on execution
1489 16#400:
1491 set group id on execution
1492 On Unix platforms, other bits than those listed above may be
1494 set.
1495 links = integer() >= 0:
1497 Number of links to the file (this is always 1 for file sys‐
1498 tems that have no concept of links).
1499 major_device = integer() >= 0:
1501 Identifies the file system where the file is located. In
1502 Windows, the number indicates a drive as follows: 0 means
1503 A:, 1 means B:, and so on.
1504 minor_device = integer() >= 0:
1506 Only valid for character devices on Unix. In all other
1507 cases, this field is zero.
1508 inode = integer() >= 0:
1510 Gives the inode number. On non-Unix file systems, this field
1511 is zero.
1512 uid = integer() >= 0:
1514 Indicates the owner of the file. On non-Unix file systems,
1515 this field is zero.
1516 gid = integer() >= 0:
1518 Gives the group that the owner of the file belongs to. On
1519 non-Unix file systems, this field is zero.
1520 Typical error reasons:
1522 eacces:
1524 Missing search permission for one of the parent directories
1525 of the file.
1526 enoent:
1528 The file does not exist.
1529 enotdir:
1531 A component of the filename is not a directory. On some
1532 platforms, enoent is returned instead.
1533 read_line(IoDevice) -> {ok, Data} | eof | {error, Reason}
1535 Types:
1537 IoDevice = io_device() | atom()
1539 Data = string() | binary()
1540 Reason =
1541 posix() |
1542 badarg |
1543 terminated |
1544 {no_translation, unicode, latin1}
1545 Reads a line of bytes/characters from the file referenced by
1547 IoDevice. Lines are defined to be delimited by the linefeed (LF,
1548 \n) character, but any carriage return (CR, \r) followed by a
1549 newline is also treated as a single LF character (the carriage
1550 return is silently ignored). The line is returned including the
1551 LF, but excluding any CR immediately followed by an LF. This be‐
1552 haviour is consistent with the behaviour of io:get_line/2. If
1553 end of file is reached without any LF ending the last line, a
1554 line with no trailing LF is returned.
1555 The function can be used on files opened in raw mode. However,
1557 it is inefficient to use it on raw files if the file is not
1558 opened with option {read_ahead, Size} specified. Thus, combining
1559 raw and {read_ahead, Size} is highly recommended when opening a
1560 text file for raw line-oriented reading.
1561 If encoding is set to something else than latin1, the
1563 read_line/1 call fails if the data contains characters larger
1564 than 255, why module io(3) is to be preferred when reading such
1565 a file.
1566 The function returns:
1568 {ok, Data}:
1570 One line from the file is returned, including the trailing
1571 LF, but with CRLF sequences replaced by a single LF (see
1572 above).
1573 If the file is opened in binary mode, the read bytes are
1575 returned in a binary, otherwise in a list.
1576 eof:
1578 Returned if end of file was reached before anything at all
1579 could be read.
1580 {error, Reason}:
1582 An error occurred.
1583 Typical error reasons:
1585 ebadf:
1587 The file is not opened for reading.
1588 {no_translation, unicode, latin1}:
1590 The file is opened with another encoding than latin1 and the
1591 data on the file cannot be translated to the byte-oriented
1592 data that this function returns.
1593 read_link(Name) -> {ok, Filename} | {error, Reason}
1595 Types:
1597 Name = name_all()
1599 Filename = filename()
1600 Reason = posix() | badarg
1601 Returns {ok, Filename} if Name refers to a symbolic link that is
1603 not a raw filename, or {error, Reason} otherwise. On platforms
1604 that do not support symbolic links, the return value is
1605 {error,enotsup}.
1606 Typical error reasons:
1608 einval:
1610 Name does not refer to a symbolic link or the name of the
1611 file that it refers to does not conform to the expected
1612 encoding.
1613 enoent:
1615 The file does not exist.
1616 enotsup:
1618 Symbolic links are not supported on this platform.
1619 read_link_all(Name) -> {ok, Filename} | {error, Reason}
1621 Types:
1623 Name = name_all()
1625 Filename = filename_all()
1626 Reason = posix() | badarg
1627 Returns {ok, Filename} if Name refers to a symbolic link or
1629 {error, Reason} otherwise. On platforms that do not support sym‐
1630 bolic links, the return value is {error,enotsup}.
1631 Notice that Filename can be either a list or a binary.
1633 Typical error reasons:
1635 einval:
1637 Name does not refer to a symbolic link.
1638 enoent:
1640 The file does not exist.
1641 enotsup:
1643 Symbolic links are not supported on this platform.
1644 read_link_info(Name) -> {ok, FileInfo} | {error, Reason}
1646 read_link_info(Name, Opts) -> {ok, FileInfo} | {error, Reason}
1648 Types:
1650 Name = name_all()
1652 Opts = [file_info_option()]
1653 FileInfo = file_info()
1654 Reason = posix() | badarg
1655 Works like read_file_info/1,2 except that if Name is a symbolic
1657 link, information about the link is returned in the file_info
1658 record and the type field of the record is set to symlink.
1659 If the option raw is set, the file server is not called and only
1661 information about local files is returned.
1662 If Name is not a symbolic link, this function returns the same
1664 result as read_file_info/1. On platforms that do not support
1665 symbolic links, this function is always equivalent to
1666 read_file_info/1.
1667 rename(Source, Destination) -> ok | {error, Reason}
1669 Types:
1671 Source = Destination = name_all()
1673 Reason = posix() | badarg
1674 Tries to rename the file Source to Destination. It can be used
1676 to move files (and directories) between directories, but it is
1677 not sufficient to specify the destination only. The destination
1678 filename must also be specified. For example, if bar is a normal
1679 file and foo and baz are directories, rename("foo/bar", "baz")
1680 returns an error, but rename("foo/bar", "baz/bar") succeeds.
1681 Returns ok if it is successful.
1682 Note:
1684 Renaming of open files is not allowed on most platforms (see
1685 eacces below).
1686 Typical error reasons:
1689 eacces:
1691 Missing read or write permissions for the parent directories
1692 of Source or Destination. On some platforms, this error is
1693 given if either Source or Destination is open.
1694 eexist:
1696 Destination is not an empty directory. On some platforms,
1697 also given when Source and Destination are not of the same
1698 type.
1699 einval:
1701 Source is a root directory, or Destination is a subdirectory
1702 of Source.
1703 eisdir:
1705 Destination is a directory, but Source is not.
1706 enoent:
1708 Source does not exist.
1709 enotdir:
1711 Source is a directory, but Destination is not.
1712 exdev:
1714 Source and Destination are on different file systems.
1715 script(Filename) -> {ok, Value} | {error, Reason}
1717 Types:
1719 Filename = name_all()
1721 Value = term()
1722 Reason =
1723 posix() |
1724 badarg |
1725 terminated |
1726 system_limit |
1727 {Line :: integer(), Mod :: module(), Term :: term()}
1728 Reads and evaluates Erlang expressions, separated by '.' (or
1730 ',', a sequence of expressions is also an expression), from the
1731 file.
1732 Returns one of the following:
1734 {ok, Value}:
1736 The file is read and evaluated. Value is the value of the
1737 last expression.
1738 {error, atom()}:
1740 An error occurred when opening the file or reading it. For a
1741 list of typical error codes, see open/2.
1742 {error, {Line, Mod, Term}}:
1744 An error occurred when interpreting the Erlang expressions
1745 in the file. Use format_error/1 to convert the three-element
1746 tuple to an English description of the error.
1747 The encoding of Filename can be set by a comment as described in
1749 epp(3).
1750 script(Filename, Bindings) -> {ok, Value} | {error, Reason}
1752 Types:
1754 Filename = name_all()
1756 Bindings = erl_eval:binding_struct()
1757 Value = term()
1758 Reason =
1759 posix() |
1760 badarg |
1761 terminated |
1762 system_limit |
1763 {Line :: integer(), Mod :: module(), Term :: term()}
1764 The same as script/1 but the variable bindings Bindings are used
1766 in the evaluation. See erl_eval(3) about variable bindings.
1767 sendfile(Filename, Socket) ->
1769 {ok, integer() >= 0} |
1770 {error, inet:posix() | closed | badarg | not_owner}
1771 Types:
1773 Filename = name_all()
1775 Socket = inet:socket()
1776 Sends the file Filename to Socket. Returns {ok, BytesSent} if
1778 successful, otherwise {error, Reason}.
1779 sendfile(RawFile, Socket, Offset, Bytes, Opts) ->
1781 {ok, integer() >= 0} |
1782 {error, inet:posix() | closed | badarg | not_owner}
1783 Types:
1785 RawFile = fd()
1787 Socket = inet:socket()
1788 Offset = Bytes = integer() >= 0
1789 Opts = [sendfile_option()]
1790 sendfile_option() =
1791 {chunk_size, integer() >= 0} | {use_threads, boolean()}
1792 Sends Bytes from the file referenced by RawFile beginning at
1794 Offset to Socket. Returns {ok, BytesSent} if successful, other‐
1795 wise {error, Reason}. If Bytes is set to 0 all data after the
1796 specified Offset is sent.
1797 The file used must be opened using the raw flag, and the process
1799 calling sendfile must be the controlling process of the socket.
1800 See gen_tcp:controlling_process/2.
1801 If the OS used does not support sendfile, an Erlang fallback
1803 using read/2 and gen_tcp:send/2 is used.
1804 The option list can contain the following options:
1806 chunk_size:
1808 The chunk size used by the Erlang fallback to send data. If
1809 using the fallback, set this to a value that comfortably
1810 fits in the systems memory. Default is 20 MB.
1811 use_threads:
1813 Instructs the emulator to use the async thread pool for the
1814 sendfile system call. This can be useful if the OS you are
1815 running on does not properly support non-blocking sendfile
1816 calls. Notice that using async threads potentially makes
1817 your system vulnerable to slow client attacks. If set to
1818 true and no async threads are available, the sendfile call
1819 returns {error,einval}. Introduced in Erlang/OTP 17.0.
1820 Default is false.
1821 set_cwd(Dir) -> ok | {error, Reason}
1823 Types:
1825 Dir = name() | EncodedBinary
1827 EncodedBinary = binary()
1828 Reason = posix() | badarg | no_translation
1829 Sets the current working directory of the file server to Dir.
1831 Returns ok if successful.
1832 The functions in the module file usually treat binaries as raw
1834 filenames, that is, they are passed "as is" even when the encod‐
1835 ing of the binary does not agree with native_name_encoding().
1836 However, this function expects binaries to be encoded according
1837 to the value returned by native_name_encoding().
1838 Typical error reasons are:
1840 enoent:
1842 The directory does not exist.
1843 enotdir:
1845 A component of Dir is not a directory. On some platforms,
1846 enoent is returned.
1847 eacces:
1849 Missing permission for the directory or one of its parents.
1850 badarg:
1852 Dir has an improper type, such as tuple.
1853 no_translation:
1855 Dir is a binary() with characters coded in ISO-latin-1 and
1856 the VM is operating with unicode filename encoding.
1857 Warning:
1859 In a future release, a bad type for argument Dir will probably
1860 generate an exception.
1861 sync(IoDevice) -> ok | {error, Reason}
1864 Types:
1866 IoDevice = io_device()
1868 Reason = posix() | badarg | terminated
1869 Ensures that any buffers kept by the operating system (not by
1871 the Erlang runtime system) are written to disk. On some plat‐
1872 forms, this function might have no effect.
1873 A typical error reason is:
1875 enospc:
1877 Not enough space left to write the file.
1878 truncate(IoDevice) -> ok | {error, Reason}
1880 Types:
1882 IoDevice = io_device()
1884 Reason = posix() | badarg | terminated
1885 Truncates the file referenced by IoDevice at the current posi‐
1887 tion. Returns ok if successful, otherwise {error, Reason}.
1888 write(IoDevice, Bytes) -> ok | {error, Reason}
1890 Types:
1892 IoDevice = io_device() | atom()
1894 Bytes = iodata()
1895 Reason = posix() | badarg | terminated
1896 Writes Bytes to the file referenced by IoDevice. This function
1898 is the only way to write to a file opened in raw mode (although
1899 it works for normally opened files too). Returns ok if success‐
1900 ful, and {error, Reason} otherwise.
1901 If the file is opened with encoding set to something else than
1903 latin1, each byte written can result in many bytes being written
1904 to the file, as the byte range 0..255 can represent anything
1905 between one and four bytes depending on value and UTF encoding
1906 type.
1907 Typical error reasons:
1909 ebadf:
1911 The file is not opened for writing.
1912 enospc:
1914 No space is left on the device.
1915 write_file(Filename, Bytes) -> ok | {error, Reason}
1917 Types:
1919 Filename = name_all()
1921 Bytes = iodata()
1922 Reason = posix() | badarg | terminated | system_limit
1923 Writes the contents of the iodata term Bytes to file Filename.
1925 The file is created if it does not exist. If it exists, the pre‐
1926 vious contents are overwritten. Returns ok if successful, other‐
1927 wise {error, Reason}.
1928 Typical error reasons:
1930 enoent:
1932 A component of the filename does not exist.
1933 enotdir:
1935 A component of the filename is not a directory. On some
1936 platforms, enoent is returned instead.
1937 enospc:
1939 No space is left on the device.
1940 eacces:
1942 Missing permission for writing the file or searching one of
1943 the parent directories.
1944 eisdir:
1946 The named file is a directory.
1947 write_file(Filename, Bytes, Modes) -> ok | {error, Reason}
1949 Types:
1951 Filename = name_all()
1953 Bytes = iodata()
1954 Modes = [mode()]
1955 Reason = posix() | badarg | terminated | system_limit
1956 Same as write_file/2, but takes a third argument Modes, a list
1958 of possible modes, see open/2. The mode flags binary and write
1959 are implicit, so they are not to be used.
1960 write_file_info(Filename, FileInfo) -> ok | {error, Reason}
1962 write_file_info(Filename, FileInfo, Opts) -> ok | {error, Reason}
1964 Types:
1966 Filename = name_all()
1968 Opts = [file_info_option()]
1969 FileInfo = file_info()
1970 Reason = posix() | badarg
1971 Changes file information. Returns ok if successful, otherwise
1973 {error, Reason}. FileInfo is a record file_info, defined in the
1974 Kernel include file file.hrl. Include the following directive in
1975 the module from which the function is called:
1976 -include_lib("kernel/include/file.hrl").
1978 The time type set in atime, mtime, and ctime depends on the time
1980 type set in Opts :: {time, Type} as follows:
1981 local:
1983 Interprets the time set as local.
1984 universal:
1986 Interprets it as universal time.
1987 posix:
1989 Must be seconds since or before Unix time epoch, which is
1990 1970-01-01 00:00 UTC.
1991 Default is {time, local}.
1993 If the option raw is set, the file server is not called and only
1995 information about local files is returned.
1996 The following fields are used from the record, if they are spec‐
1998 ified:
1999 atime = date_time() | integer() >= 0:
2001 The last time the file was read.
2002 mtime = date_time() | integer() >= 0:
2004 The last time the file was written.
2005 ctime = date_time() | integer() >= 0:
2007 On Unix, any value specified for this field is ignored (the
2008 "ctime" for the file is set to the current time). On Win‐
2009 dows, this field is the new creation time to set for the
2010 file.
2011 mode = integer() >= 0:
2013 The file permissions as the sum of the following bit values:
2014 8#00400:
2016 Read permission: owner
2017 8#00200:
2019 Write permission: owner
2020 8#00100:
2022 Execute permission: owner
2023 8#00040:
2025 Read permission: group
2026 8#00020:
2028 Write permission: group
2029 8#00010:
2031 Execute permission: group
2032 8#00004:
2034 Read permission: other
2035 8#00002:
2037 Write permission: other
2038 8#00001:
2040 Execute permission: other
2041 16#800:
2043 Set user id on execution
2044 16#400:
2046 Set group id on execution
2047 On Unix platforms, other bits than those listed above may be
2049 set.
2050 uid = integer() >= 0:
2052 Indicates the file owner. Ignored for non-Unix file systems.
2053 gid = integer() >= 0:
2055 Gives the group that the file owner belongs to. Ignored for
2056 non-Unix file systems.
2057 Typical error reasons:
2059 eacces:
2061 Missing search permission for one of the parent directories
2062 of the file.
2063 enoent:
2065 The file does not exist.
2066 enotdir:
2068 A component of the filename is not a directory. On some
2069 platforms, enoent is returned instead.
2070
2072 * eacces - Permission denied
2073 * eagain - Resource temporarily unavailable
2075 * ebadf - Bad file number
2077 * ebusy - File busy
2079 * edquot - Disk quota exceeded
2081 * eexist - File already exists
2083 * efault - Bad address in system call argument
2085 * efbig - File too large
2087 * eintr - Interrupted system call
2089 * einval - Invalid argument
2091 * eio - I/O error
2093 * eisdir - Illegal operation on a directory
2095 * eloop - Too many levels of symbolic links
2097 * emfile - Too many open files
2099 * emlink - Too many links
2101 * enametoolong - Filename too long
2103 * enfile - File table overflow
2105 * enodev - No such device
2107 * enoent - No such file or directory
2109 * enomem - Not enough memory
2111 * enospc - No space left on device
2113 * enotblk - Block device required
2115 * enotdir - Not a directory
2117 * enotsup - Operation not supported
2119 * enxio - No such device or address
2121 * eperm - Not owner
2123 * epipe - Broken pipe
2125 * erofs - Read-only file system
2127 * espipe - Invalid seek
2129 * esrch - No such process
2131 * estale - Stale remote file handle
2133 * exdev - Cross-domain link
2135
2137 Some operating system file operations, for example, a sync/1 or close/1
2138 on a huge file, can block their calling thread for seconds. If this
2139 affects the emulator main thread, the response time is no longer in the
2140 order of milliseconds, depending on the definition of "soft" in soft
2141 real-time system.
2142 If the device driver thread pool is active, file operations are done
2144 through those threads instead, so the emulator can go on executing
2145 Erlang processes. Unfortunately, the time for serving a file operation
2146 increases because of the extra scheduling required from the operating
2147 system.
2148 If the device driver thread pool is disabled or of size 0, large file
2150 reads and writes are segmented into many smaller, which enable the emu‐
2151 lator to serve other processes during the file operation. This has the
2152 same effect as when using the thread pool, but with larger overhead.
2153 Other file operations, for example, sync/1 or close/1 on a huge file,
2154 still are a problem.
2155 For increased performance, raw files are recommended. Raw files use the
2157 file system of the host machine of the node.
2158 Note:
2160 For normal files (non-raw), the file server is used to find the files,
2161 and if the node is running its file server as slave to the file server
2162 of another node, and the other node runs on some other host machine,
2163 they can have different file systems. However, this is seldom a prob‐
2164 lem.
2165 A normal file is really a process so it can be used as an I/O device
2168 (see io). Therefore, when data is written to a normal file, the sending
2169 of the data to the file process, copies all data that are not binaries.
2170 Opening the file in binary mode and writing binaries is therefore rec‐
2171 ommended. If the file is opened on another node, or if the file server
2172 runs as slave to the file server of another node, also binaries are
2173 copied.
2174 Caching data to reduce the number of file operations, or rather the
2176 number of calls to the file driver, generally increases performance.
2177 The following function writes 4 MBytes in 23 seconds when tested:
2178 create_file_slow(Name, N) when integer(N), N >= 0 ->
2180 {ok, FD} = file:open(Name, [raw, write, delayed_write, binary]),
2181 ok = create_file_slow(FD, 0, N),
2182 ok = ?FILE_MODULE:close(FD),
2183 ok.
2184 create_file_slow(FD, M, M) ->
2186 ok;
2187 create_file_slow(FD, M, N) ->
2188 ok = file:write(FD, <<M:32/unsigned>>),
2189 create_file_slow(FD, M+1, N).
2190 The following, functionally equivalent, function collects 1024 entries
2192 into a list of 128 32-byte binaries before each call to write/2 and so
2193 does the same work in 0.52 seconds, which is 44 times faster:
2194 create_file(Name, N) when integer(N), N >= 0 ->
2196 {ok, FD} = file:open(Name, [raw, write, delayed_write, binary]),
2197 ok = create_file(FD, 0, N),
2198 ok = ?FILE_MODULE:close(FD),
2199 ok.
2200 create_file(FD, M, M) ->
2202 ok;
2203 create_file(FD, M, N) when M + 1024 =< N ->
2204 create_file(FD, M, M + 1024, []),
2205 create_file(FD, M + 1024, N);
2206 create_file(FD, M, N) ->
2207 create_file(FD, M, N, []).
2208 create_file(FD, M, M, R) ->
2210 ok = file:write(FD, R);
2211 create_file(FD, M, N0, R) when M + 8 =< N0 ->
2212 N1 = N0-1, N2 = N0-2, N3 = N0-3, N4 = N0-4,
2213 N5 = N0-5, N6 = N0-6, N7 = N0-7, N8 = N0-8,
2214 create_file(FD, M, N8,
2215 [<<N8:32/unsigned, N7:32/unsigned,
2216 N6:32/unsigned, N5:32/unsigned,
2217 N4:32/unsigned, N3:32/unsigned,
2218 N2:32/unsigned, N1:32/unsigned>> | R]);
2219 create_file(FD, M, N0, R) ->
2220 N1 = N0-1,
2221 create_file(FD, M, N1, [<<N1:32/unsigned>> | R]).
2222 Note:
2224 Trust only your own benchmarks. If the list length in create_file/2
2225 above is increased, it runs slightly faster, but consumes more memory
2226 and causes more memory fragmentation. How much this affects your appli‐
2227 cation is something that this simple benchmark cannot predict.
2228 If the size of each binary is increased to 64 bytes, it also runs
2230 slightly faster, but the code is then twice as clumsy. In the current
2231 implementation, binaries larger than 64 bytes are stored in memory com‐
2232 mon to all processes and not copied when sent between processes, while
2233 these smaller binaries are stored on the process heap and copied when
2234 sent like any other term.
2235 So, with a binary size of 68 bytes, create_file/2 runs 30 percent
2237 slower than with 64 bytes, and causes much more memory fragmentation.
2238 Notice that if the binaries were to be sent between processes (for
2239 example, a non-raw file), the results would probably be completely dif‐
2240 ferent.
2241 A raw file is really a port. When writing data to a port, it is effi‐
2244 cient to write a list of binaries. It is not needed to flatten a deep
2245 list before writing. On Unix hosts, scatter output, which writes a set
2246 of buffers in one operation, is used when possible. In this way
2247 write(FD, [Bin1, Bin2 | Bin3]) writes the contents of the binaries
2248 without copying the data at all, except for perhaps deep down in the
2249 operating system kernel.
2250 For raw files, pwrite/2 and pread/2 are efficiently implemented. The
2252 file driver is called only once for the whole operation, and the list
2253 iteration is done in the file driver.
2254 The options delayed_write and read_ahead to open/2 make the file driver
2256 cache data to reduce the number of operating system calls. The function
2257 create_file/2 in the recent example takes 60 seconds without option
2258 delayed_write, which is 2.6 times slower.
2259 As a bad example, create_file_slow/2 without options raw, binary, and
2261 delayed_write, meaning it calls open(Name, [write]), needs 1 min 20
2262 seconds for the job, which is 3.5 times slower than the first example,
2263 and 150 times slower than the optimized create_file/2.
2264 Warning:
2266 If an error occurs when accessing an open file with module io, the
2267 process handling the file exits. The dead file process can hang if a
2268 process tries to access it later. This will be fixed in a future
2269 release.
2270
2273 filename(3)
2274Ericsson AB kernel 5.4.3.2 file(3)