1file(3) Erlang Module Definition file(3)
2
6 file - File interface module.
7
9 This module provides an interface to the file system.
10 Warning:
12 File operations are only guaranteed to appear atomic when going through
13 the same file server. A NIF or other OS process may observe intermedi‐
14 ate steps on certain operations on some operating systems, eg. renaming
15 an existing file on Windows, or write_file_info/2 on any OS at the time
16 of writing.
17 Regarding filename encoding, the Erlang VM can operate in two modes.
20 The current mode can be queried using function native_name_encoding/0.
21 It returns latin1 or utf8.
22 In latin1 mode, the Erlang VM does not change the encoding of file‐
24 names. In utf8 mode, filenames can contain Unicode characters greater
25 than 255 and the VM converts filenames back and forth to the native
26 filename encoding (usually UTF-8, but UTF-16 on Windows).
27 The default mode depends on the operating system. Windows, MacOS X and
29 Android enforce consistent filename encoding and therefore the VM uses
30 utf8 mode.
31 On operating systems with transparent naming (for example, all Unix
33 systems except MacOS X), default is utf8 if the terminal supports
34 UTF-8, otherwise latin1. The default can be overridden using +fnl (to
35 force latin1 mode) or +fnu (to force utf8 mode) when starting erl.
36 On operating systems with transparent naming, files can be inconsis‐
38 tently named, for example, some files are encoded in UTF-8 while others
39 are encoded in ISO Latin-1. The concept of raw filenames is introduced
40 to handle file systems with inconsistent naming when running in utf8
41 mode.
42 A raw filename is a filename specified as a binary. The Erlang VM does
44 not translate a filename specified as a binary on systems with trans‐
45 parent naming.
46 When running in utf8 mode, functions list_dir/1 and read_link/1 never
48 return raw filenames. To return all filenames including raw filenames,
49 use functions list_dir_all/1 and read_link_all/1.
50 See also section Notes About Raw Filenames in the STDLIB User's Guide.
52 Note:
54 File operations used to accept filenames containing null characters
55 (integer value zero). This caused the name to be truncated and in some
56 cases arguments to primitive operations to be mixed up. Filenames con‐
57 taining null characters inside the filename are now rejected and will
58 cause primitive file operations fail.
59
62 deep_list() = [char() | atom() | deep_list()]
63 fd()
65 A file descriptor representing a file opened in raw mode.
67 filename() = string()
69 See also the documentation of the name_all() type.
71 filename_all() = string() | binary()
73 See also the documentation of the name_all() type.
75 io_device() = pid() | fd()
77 As returned by open/2; pid() is a process handling I/O-proto‐
79 cols.
80 name() = string() | atom() | deep_list()
82 If VM is in Unicode filename mode, string() and char() are
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 | eagain | ebadf | ebadmsg | ebusy | edeadlk |
100 edeadlock | edquot | eexist | efault | efbig | eftype |
101 eintr | einval | eio | eisdir | eloop | emfile | emlink |
102 emultihop | enametoolong | enfile | enobufs | enodev |
103 enolck | enolink | enoent | enomem | enospc | enosr | enostr |
104 enosys | enotblk | enotdir | enotsup | enxio | eopnotsupp |
105 eoverflow | eperm | epipe | erange | erofs | espipe | esrch |
106 estale | etxtbsy | exdev
107 An atom that is named from the POSIX error codes used in Unix,
109 and in the runtime libraries of most C compilers.
110 date_time() = calendar:datetime()
112 Must denote a valid date and time.
114 file_info() =
116 #file_info{size = integer() >= 0 | undefined,
117 type =
118 device | directory | other | regular |
119 symlink | undefined,
120 access =
121 read | write | read_write | none | undefined,
122 atime =
123 file:date_time() |
124 integer() >= 0 |
125 undefined,
126 mtime =
127 file:date_time() |
128 integer() >= 0 |
129 undefined,
130 ctime =
131 file:date_time() |
132 integer() >= 0 |
133 undefined,
134 mode = integer() >= 0 | undefined,
135 links = integer() >= 0 | undefined,
136 major_device = integer() >= 0 | undefined,
137 minor_device = integer() >= 0 | undefined,
138 inode = integer() >= 0 | undefined,
139 uid = integer() >= 0 | undefined,
140 gid = integer() >= 0 | undefined}
141 location() =
143 integer() |
144 {bof, Offset :: integer()} |
145 {cur, Offset :: integer()} |
146 {eof, Offset :: integer()} |
147 bof | cur | eof
148 mode() =
150 read | write | append | exclusive | raw | binary |
151 {delayed_write,
152 Size :: integer() >= 0,
153 Delay :: integer() >= 0} |
154 delayed_write |
155 {read_ahead, Size :: integer() >= 1} |
156 read_ahead | compressed |
157 {encoding, unicode:encoding()} |
158 sync
159 file_info_option() =
161 {time, local} | {time, universal} | {time, posix} | raw
162
164 advise(IoDevice, Offset, Length, Advise) -> ok | {error, Reason}
165 Types:
167 IoDevice = io_device()
169 Offset = Length = integer()
170 Advise = posix_file_advise()
171 Reason = posix() | badarg
172 posix_file_advise() =
173 normal | sequential | random | no_reuse | will_need |
174 dont_need
175 advise/4 can be used to announce an intention to access file
177 data in a specific pattern in the future, thus allowing the
178 operating system to perform appropriate optimizations.
179 On some platforms, this function might have no effect.
181 allocate(File, Offset, Length) -> ok | {error, posix()}
183 Types:
185 File = io_device()
187 Offset = Length = integer() >= 0
188 allocate/3 can be used to preallocate space for a file.
190 This function only succeeds in platforms that provide this fea‐
192 ture.
193 change_group(Filename, Gid) -> ok | {error, Reason}
195 Types:
197 Filename = name_all()
199 Gid = integer()
200 Reason = posix() | badarg
201 Changes group of a file. See write_file_info/2.
203 change_mode(Filename, Mode) -> ok | {error, Reason}
205 Types:
207 Filename = name_all()
209 Mode = integer()
210 Reason = posix() | badarg
211 Changes permissions of a file. See write_file_info/2.
213 change_owner(Filename, Uid) -> ok | {error, Reason}
215 Types:
217 Filename = name_all()
219 Uid = integer()
220 Reason = posix() | badarg
221 Changes owner of a file. See write_file_info/2.
223 change_owner(Filename, Uid, Gid) -> ok | {error, Reason}
225 Types:
227 Filename = name_all()
229 Uid = Gid = integer()
230 Reason = posix() | badarg
231 Changes owner and group of a file. See write_file_info/2.
233 change_time(Filename, Mtime) -> ok | {error, Reason}
235 Types:
237 Filename = name_all()
239 Mtime = date_time()
240 Reason = posix() | badarg
241 Changes the modification and access times of a file. See
243 write_file_info/2.
244 change_time(Filename, Atime, Mtime) -> ok | {error, Reason}
246 Types:
248 Filename = name_all()
250 Atime = Mtime = date_time()
251 Reason = posix() | badarg
252 Changes the modification and last access times of a file. See
254 write_file_info/2.
255 close(IoDevice) -> ok | {error, Reason}
257 Types:
259 IoDevice = io_device()
261 Reason = posix() | badarg | terminated
262 Closes the file referenced by IoDevice. It mostly returns ok,
264 except for some severe errors such as out of memory.
265 Notice that if option delayed_write was used when opening the
267 file, close/1 can return an old write error and not even try to
268 close the file. See open/2.
269 consult(Filename) -> {ok, Terms} | {error, Reason}
271 Types:
273 Filename = name_all()
275 Terms = [term()]
276 Reason =
277 posix() |
278 badarg | terminated | system_limit |
279 {Line :: integer(), Mod :: module(), Term :: term()}
280 Reads Erlang terms, separated by '.', from Filename. Returns one
282 of the following:
283 {ok, Terms}:
285 The file was successfully read.
286 {error, atom()}:
288 An error occurred when opening the file or reading it. For a
289 list of typical error codes, see open/2.
290 {error, {Line, Mod, Term}}:
292 An error occurred when interpreting the Erlang terms in the
293 file. To convert the three-element tuple to an English
294 description of the error, use format_error/1.
295 Example:
297 f.txt: {person, "kalle", 25}.
299 {person, "pelle", 30}.
300 1> file:consult("f.txt").
302 {ok,[{person,"kalle",25},{person,"pelle",30}]}
303 The encoding of Filename can be set by a comment, as described
305 in epp(3).
306 copy(Source, Destination) -> {ok, BytesCopied} | {error, Reason}
308 copy(Source, Destination, ByteCount) ->
310 {ok, BytesCopied} | {error, Reason}
311 Types:
313 Source = Destination = io_device() | Filename | {Filename,
315 Modes}
316 Filename = name_all()
317 Modes = [mode()]
318 ByteCount = integer() >= 0 | infinity
319 BytesCopied = integer() >= 0
320 Reason = posix() | badarg | terminated
321 Copies ByteCount bytes from Source to Destination. Source and
323 Destination refer to either filenames or IO devices from, for
324 example, open/2. ByteCount defaults to infinity, denoting an
325 infinite number of bytes.
326 Argument Modes is a list of possible modes, see open/2, and
328 defaults to [].
329 If both Source and Destination refer to filenames, the files are
331 opened with [read, binary] and [write, binary] prepended to
332 their mode lists, respectively, to optimize the copy.
333 If Source refers to a filename, it is opened with read mode
335 prepended to the mode list before the copy, and closed when
336 done.
337 If Destination refers to a filename, it is opened with write
339 mode prepended to the mode list before the copy, and closed when
340 done.
341 Returns {ok, BytesCopied}, where BytesCopied is the number of
343 bytes that was copied, which can be less than ByteCount if end
344 of file was encountered on the source. If the operation fails,
345 {error, Reason} is returned.
346 Typical error reasons: as for open/2 if a file had to be opened,
348 and as for read/2 and write/2.
349 datasync(IoDevice) -> ok | {error, Reason}
351 Types:
353 IoDevice = io_device()
355 Reason = posix() | badarg | terminated
356 Ensures that any buffers kept by the operating system (not by
358 the Erlang runtime system) are written to disk. In many ways it
359 resembles fsync but it does not update some of the metadata of
360 the file, such as the access time. On some platforms this func‐
361 tion has no effect.
362 Applications that access databases or log files often write a
364 tiny data fragment (for example, one line in a log file) and
365 then call fsync() immediately to ensure that the written data is
366 physically stored on the hard disk. Unfortunately, fsync()
367 always initiates two write operations: one for the newly written
368 data and another one to update the modification time stored in
369 the inode. If the modification time is not a part of the trans‐
370 action concept, fdatasync() can be used to avoid unnecessary
371 inode disk write operations.
372 Available only in some POSIX systems, this call results in a
374 call to fsync(), or has no effect in systems not providing the
375 fdatasync() syscall.
376 del_dir(Dir) -> ok | {error, Reason}
378 Types:
380 Dir = name_all()
382 Reason = posix() | badarg
383 Tries to delete directory Dir. The directory must be empty
385 before it can be deleted. Returns ok if successful.
386 Typical error reasons:
388 eacces:
390 Missing search or write permissions for the parent directo‐
391 ries of Dir.
392 eexist:
394 The directory is not empty.
395 enoent:
397 The directory does not exist.
398 enotdir:
400 A component of Dir is not a directory. On some platforms,
401 enoent is returned instead.
402 einval:
404 Attempt to delete the current directory. On some platforms,
405 eacces is returned instead.
406 del_dir_r(File) -> ok | {error, Reason}
408 Types:
410 File = name_all()
412 Reason = posix() | badarg
413 Deletes file or directory File. If File is a directory, its con‐
415 tents is first recursively deleted. Returns:
416 ok:
418 The operation completed without errors.
419 {error, posix()}:
421 An error occurred when accessing or deleting File. If some
422 file or directory under File could not be deleted, File can‐
423 not be deleted as it is non-empty, and {error, eexist} is
424 returned.
425 delete(Filename) -> ok | {error, Reason}
427 Types:
429 Filename = name_all()
431 Reason = posix() | badarg
432 Tries to delete file Filename. Returns ok if successful.
434 Typical error reasons:
436 enoent:
438 The file does not exist.
439 eacces:
441 Missing permission for the file or one of its parents.
442 eperm:
444 The file is a directory and the user is not superuser.
445 enotdir:
447 A component of the filename is not a directory. On some
448 platforms, enoent is returned instead.
449 einval:
451 Filename has an improper type, such as tuple.
452 Warning:
454 In a future release, a bad type for argument Filename will prob‐
455 ably generate an exception.
456 eval(Filename) -> ok | {error, Reason}
459 Types:
461 Filename = name_all()
463 Reason =
464 posix() |
465 badarg | terminated | system_limit |
466 {Line :: integer(), Mod :: module(), Term :: term()}
467 Reads and evaluates Erlang expressions, separated by '.' (or
469 ',', a sequence of expressions is also an expression) from File‐
470 name. The result of the evaluation is not returned; any expres‐
471 sion sequence in the file must be there for its side effect.
472 Returns one of the following:
473 ok:
475 The file was read and evaluated.
476 {error, atom()}:
478 An error occurred when opening the file or reading it. For a
479 list of typical error codes, see open/2.
480 {error, {Line, Mod, Term}}:
482 An error occurred when interpreting the Erlang expressions
483 in the file. To convert the three-element tuple to an Eng‐
484 lish description of the error, use format_error/1.
485 The encoding of Filename can be set by a comment, as described
487 in epp(3).
488 eval(Filename, Bindings) -> ok | {error, Reason}
490 Types:
492 Filename = name_all()
494 Bindings = erl_eval:binding_struct()
495 Reason =
496 posix() |
497 badarg | terminated | system_limit |
498 {Line :: integer(), Mod :: module(), Term :: term()}
499 The same as eval/1, but the variable bindings Bindings are used
501 in the evaluation. For information about the variable bindings,
502 see erl_eval(3).
503 format_error(Reason) -> Chars
505 Types:
507 Reason =
509 posix() |
510 badarg | terminated | system_limit |
511 {Line :: integer(), Mod :: module(), Term :: term()}
512 Chars = string()
513 Given the error reason returned by any function in this module,
515 returns a descriptive string of the error in English.
516 get_cwd() -> {ok, Dir} | {error, Reason}
518 Types:
520 Dir = filename()
522 Reason = posix()
523 Returns {ok, Dir}, where Dir is the current working directory of
525 the file server.
526 Note:
528 In rare circumstances, this function can fail on Unix. It can
529 occur if read permission does not exist for the parent directo‐
530 ries of the current directory.
531 A typical error reason:
534 eacces:
536 Missing read permission for one of the parents of the cur‐
537 rent directory.
538 get_cwd(Drive) -> {ok, Dir} | {error, Reason}
540 Types:
542 Drive = string()
544 Dir = filename()
545 Reason = posix() | badarg
546 Returns {ok, Dir} or {error, Reason}, where Dir is the current
548 working directory of the specified drive.
549 Drive is to be of the form "Letter:", for example, "c:".
551 Returns {error, enotsup} on platforms that have no concept of
553 current drive (Unix, for example).
554 Typical error reasons:
556 enotsup:
558 The operating system has no concept of drives.
559 eacces:
561 The drive does not exist.
562 einval:
564 The format of Drive is invalid.
565 list_dir(Dir) -> {ok, Filenames} | {error, Reason}
567 Types:
569 Dir = name_all()
571 Filenames = [filename()]
572 Reason =
573 posix() |
574 badarg |
575 {no_translation, Filename :: unicode:latin1_binary()}
576 Lists all files in a directory, except files with raw filenames.
578 Returns {ok, Filenames} if successful, otherwise {error, Rea‐
579 son}. Filenames is a list of the names of all the files in the
580 directory. The names are not sorted.
581 Typical error reasons:
583 eacces:
585 Missing search or write permissions for Dir or one of its
586 parent directories.
587 enoent:
589 The directory does not exist.
590 {no_translation, Filename}:
592 Filename is a binary() with characters coded in ISO Latin-1
593 and the VM was started with parameter +fnue.
594 list_dir_all(Dir) -> {ok, Filenames} | {error, Reason}
596 Types:
598 Dir = name_all()
600 Filenames = [filename_all()]
601 Reason = posix() | badarg
602 Lists all the files in a directory, including files with raw
604 filenames. Returns {ok, Filenames} if successful, otherwise
605 {error, Reason}. Filenames is a list of the names of all the
606 files in the directory. The names are not sorted.
607 Typical error reasons:
609 eacces:
611 Missing search or write permissions for Dir or one of its
612 parent directories.
613 enoent:
615 The directory does not exist.
616 make_dir(Dir) -> ok | {error, Reason}
618 Types:
620 Dir = name_all()
622 Reason = posix() | badarg
623 Tries to create directory Dir. Missing parent directories are
625 not created. Returns ok if successful.
626 Typical error reasons:
628 eacces:
630 Missing search or write permissions for the parent directo‐
631 ries of Dir.
632 eexist:
634 A file or directory named Dir exists already.
635 enoent:
637 A component of Dir does not exist.
638 enospc:
640 No space is left on the device.
641 enotdir:
643 A component of Dir is not a directory. On some platforms,
644 enoent is returned instead.
645 make_link(Existing, New) -> ok | {error, Reason}
647 Types:
649 Existing = New = name_all()
651 Reason = posix() | badarg
652 Makes a hard link from Existing to New on platforms supporting
654 links (Unix and Windows). This function returns ok if the link
655 was successfully created, otherwise {error, Reason}. On plat‐
656 forms not supporting links, {error,enotsup} is returned.
657 Typical error reasons:
659 eacces:
661 Missing read or write permissions for the parent directories
662 of Existing or New.
663 eexist:
665 New already exists.
666 enotsup:
668 Hard links are not supported on this platform.
669 make_symlink(Existing, New) -> ok | {error, Reason}
671 Types:
673 Existing = New = name_all()
675 Reason = posix() | badarg
676 Creates a symbolic link New to the file or directory Existing on
678 platforms supporting symbolic links (most Unix systems and Win‐
679 dows, beginning with Vista). Existing does not need to exist.
680 Returns ok if the link is successfully created, otherwise
681 {error, Reason}. On platforms not supporting symbolic links,
682 {error, enotsup} is returned.
683 Typical error reasons:
685 eacces:
687 Missing read or write permissions for the parent directories
688 of Existing or New.
689 eexist:
691 New already exists.
692 enotsup:
694 Symbolic links are not supported on this platform.
695 eperm:
697 User does not have privileges to create symbolic links
698 (SeCreateSymbolicLinkPrivilege on Windows).
699 native_name_encoding() -> latin1 | utf8
701 Returns the filename encoding mode. If it is latin1, the system
703 translates no filenames. If it is utf8, filenames are converted
704 back and forth to the native filename encoding (usually UTF-8,
705 but UTF-16 on Windows).
706 open(File, Modes) -> {ok, IoDevice} | {error, Reason}
708 Types:
710 File = Filename | iodata()
712 Filename = name_all()
713 Modes = [mode() | ram | directory]
714 IoDevice = io_device()
715 Reason = posix() | badarg | system_limit
716 Opens file File in the mode determined by Modes, which can con‐
718 tain one or more of the following options:
719 read:
721 The file, which must exist, is opened for reading.
722 write:
724 The file is opened for writing. It is created if it does not
725 exist. If the file exists and write is not combined with
726 read, the file is truncated.
727 append:
729 The file is opened for writing. It is created if it does not
730 exist. Every write operation to a file opened with append
731 takes place at the end of the file.
732 exclusive:
734 The file is opened for writing. It is created if it does not
735 exist. If the file exists, {error, eexist} is returned.
736 Warning:
738 This option does not guarantee exclusiveness on file systems
739 not supporting O_EXCL properly, such as NFS. Do not depend on
740 this option unless you know that the file system supports it
741 (in general, local file systems are safe).
742 raw:
745 Allows faster access to a file, as no Erlang process is
746 needed to handle the file. However, a file opened in this
747 way has the following limitations:
748 * The functions in the io module cannot be used, as they can
750 only talk to an Erlang process. Instead, use functions
751 read/2, read_line/1, and write/2.
752 * Especially if read_line/1 is to be used on a raw file, it
754 is recommended to combine this option with option
755 {read_ahead, Size} as line-oriented I/O is inefficient
756 without buffering.
757 * Only the Erlang process that opened the file can use it.
759 * A remote Erlang file server cannot be used. The computer
761 on which the Erlang node is running must have access to
762 the file system (directly or through NFS).
763 binary:
765 Read operations on the file return binaries rather than
766 lists.
767 {delayed_write, Size, Delay}:
769 Data in subsequent write/2 calls is buffered until at least
770 Size bytes are buffered, or until the oldest buffered data
771 is Delay milliseconds old. Then all buffered data is written
772 in one operating system call. The buffered data is also
773 flushed before some other file operation than write/2 is
774 executed.
775 The purpose of this option is to increase performance by
777 reducing the number of operating system calls. Thus, the
778 write/2 calls must be for sizes significantly less than
779 Size, and not interspersed by too many other file opera‐
780 tions.
781 When this option is used, the result of write/2 calls can
783 prematurely be reported as successful, and if a write error
784 occurs, the error is reported as the result of the next file
785 operation, which is not executed.
786 For example, when delayed_write is used, after a number of
788 write/2 calls, close/1 can return {error, enospc}, as there
789 is not enough space on the disc for previously written data.
790 close/1 must probably be called again, as the file is still
791 open.
792 delayed_write:
794 The same as {delayed_write, Size, Delay} with reasonable
795 default values for Size and Delay (roughly some 64 KB, 2
796 seconds).
797 {read_ahead, Size}:
799 Activates read data buffering. If read/2 calls are for sig‐
800 nificantly less than Size bytes, read operations to the
801 operating system are still performed for blocks of Size
802 bytes. The extra data is buffered and returned in subsequent
803 read/2 calls, giving a performance gain as the number of
804 operating system calls is reduced.
805 The read_ahead buffer is also highly used by function
807 read_line/1 in raw mode, therefore this option is recom‐
808 mended (for performance reasons) when accessing raw files
809 using that function.
810 If read/2 calls are for sizes not significantly less than,
812 or even greater than Size bytes, no performance gain can be
813 expected.
814 read_ahead:
816 The same as {read_ahead, Size} with a reasonable default
817 value for Size (roughly some 64 KB).
818 compressed:
820 Makes it possible to read or write gzip compressed files.
821 Option compressed must be combined with read or write, but
822 not both. Notice that the file size obtained with
823 read_file_info/1 does probably not match the number of bytes
824 that can be read from a compressed file.
825 {encoding, Encoding}:
827 Makes the file perform automatic translation of characters
828 to and from a specific (Unicode) encoding. Notice that the
829 data supplied to write/2 or returned by read/2 still is
830 byte-oriented; this option denotes only how data is stored
831 in the disk file.
832 Depending on the encoding, different methods of reading and
834 writing data is preferred. The default encoding of latin1
835 implies using this module (file) for reading and writing
836 data as the interfaces provided here work with byte-oriented
837 data. Using other (Unicode) encodings makes the io(3) func‐
838 tions get_chars, get_line, and put_chars more suitable, as
839 they can work with the full Unicode range.
840 If data is sent to an io_device() in a format that cannot be
842 converted to the specified encoding, or if data is read by a
843 function that returns data in a format that cannot cope with
844 the character range of the data, an error occurs and the
845 file is closed.
846 Allowed values for Encoding:
848 latin1:
850 The default encoding. Bytes supplied to the file, that is,
851 write/2 are written "as is" on the file. Likewise, bytes
852 read from the file, that is, read/2 are returned "as is".
853 If module io(3) is used for writing, the file can only
854 cope with Unicode characters up to code point 255 (the ISO
855 Latin-1 range).
856 unicode or utf8:
858 Characters are translated to and from UTF-8 encoding
859 before they are written to or read from the file. A file
860 opened in this way can be readable using function read/2,
861 as long as no data stored on the file lies beyond the ISO
862 Latin-1 range (0..255), but failure occurs if the data
863 contains Unicode code points beyond that range. The file
864 is best read with the functions in the Unicode aware mod‐
865 ule io(3).
866 Bytes written to the file by any means are translated to
868 UTF-8 encoding before being stored on the disk file.
869 utf16 or {utf16,big}:
871 Works like unicode, but translation is done to and from
872 big endian UTF-16 instead of UTF-8.
873 {utf16,little}:
875 Works like unicode, but translation is done to and from
876 little endian UTF-16 instead of UTF-8.
877 utf32 or {utf32,big}:
879 Works like unicode, but translation is done to and from
880 big endian UTF-32 instead of UTF-8.
881 {utf32,little}:
883 Works like unicode, but translation is done to and from
884 little endian UTF-32 instead of UTF-8.
885 The Encoding can be changed for a file "on the fly" by using
887 function io:setopts/2. So a file can be analyzed in latin1
888 encoding for, for example, a BOM, positioned beyond the BOM
889 and then be set for the right encoding before further read‐
890 ing. For functions identifying BOMs, see module unicode(3).
891 This option is not allowed on raw files.
893 ram:
895 File must be iodata(). Returns an fd(), which lets module
896 file operate on the data in-memory as if it is a file.
897 sync:
899 On platforms supporting it, enables the POSIX O_SYNC syn‐
900 chronous I/O flag or its platform-dependent equivalent (for
901 example, FILE_FLAG_WRITE_THROUGH on Windows) so that writes
902 to the file block until the data is physically written to
903 disk. However, be aware that the exact semantics of this
904 flag differ from platform to platform. For example, none of
905 Linux or Windows guarantees that all file metadata are also
906 written before the call returns. For precise semantics,
907 check the details of your platform documentation. On plat‐
908 forms with no support for POSIX O_SYNC or equivalent, use of
909 the sync flag causes open to return {error, enotsup}.
910 directory:
912 Allows open to work on directories.
913 Returns:
915 {ok, IoDevice}:
917 The file is opened in the requested mode. IoDevice is a ref‐
918 erence to the file.
919 {error, Reason}:
921 The file cannot be opened.
922 IoDevice is really the pid of the process that handles the file.
924 This process monitors the process that originally opened the
925 file (the owner process). If the owner process terminates, the
926 file is closed and the process itself terminates too. An IoDe‐
927 vice returned from this call can be used as an argument to the
928 I/O functions (see io(3)).
929 Note:
931 In previous versions of file, modes were specified as one of the
932 atoms read, write, or read_write instead of a list. This is
933 still allowed for reasons of backwards compatibility, but is not
934 to be used for new code. Also note that read_write is not
935 allowed in a mode list.
936 Typical error reasons:
939 enoent:
941 The file does not exist.
942 eacces:
944 Missing permission for reading the file or searching one of
945 the parent directories.
946 eisdir:
948 The named file is a directory.
949 enotdir:
951 A component of the filename is not a directory, or the file‐
952 name itself is not a directory if directory mode was speci‐
953 fied. On some platforms, enoent is returned instead.
954 enospc:
956 There is no space left on the device (if write access was
957 specified).
958 path_consult(Path, Filename) ->
960 {ok, Terms, FullName} | {error, Reason}
961 Types:
963 Path = [Dir]
965 Dir = Filename = name_all()
966 Terms = [term()]
967 FullName = filename_all()
968 Reason =
969 posix() |
970 badarg | terminated | system_limit |
971 {Line :: integer(), Mod :: module(), Term :: term()}
972 Searches the path Path (a list of directory names) until the
974 file Filename is found. If Filename is an absolute filename,
975 Path is ignored. Then reads Erlang terms, separated by '.', from
976 the file.
977 Returns one of the following:
979 {ok, Terms, FullName}:
981 The file is successfully read. FullName is the full name of
982 the file.
983 {error, enoent}:
985 The file cannot be found in any of the directories in Path.
986 {error, atom()}:
988 An error occurred when opening the file or reading it. For a
989 list of typical error codes, see open/2.
990 {error, {Line, Mod, Term}}:
992 An error occurred when interpreting the Erlang terms in the
993 file. Use format_error/1 to convert the three-element tuple
994 to an English description of the error.
995 The encoding of Filename can be set by a comment as described in
997 epp(3).
998 path_eval(Path, Filename) -> {ok, FullName} | {error, Reason}
1000 Types:
1002 Path = [Dir :: name_all()]
1004 Filename = name_all()
1005 FullName = filename_all()
1006 Reason =
1007 posix() |
1008 badarg | terminated | system_limit |
1009 {Line :: integer(), Mod :: module(), Term :: term()}
1010 Searches the path Path (a list of directory names) until the
1012 file Filename is found. If Filename is an absolute filename,
1013 Path is ignored. Then reads and evaluates Erlang expressions,
1014 separated by '.' (or ',', a sequence of expressions is also an
1015 expression), from the file. The result of evaluation is not
1016 returned; any expression sequence in the file must be there for
1017 its side effect.
1018 Returns one of the following:
1020 {ok, FullName}:
1022 The file is read and evaluated. FullName is the full name of
1023 the file.
1024 {error, enoent}:
1026 The file cannot be found in any of the directories in Path.
1027 {error, atom()}:
1029 An error occurred when opening the file or reading it. For a
1030 list of typical error codes, see open/2.
1031 {error, {Line, Mod, Term}}:
1033 An error occurred when interpreting the Erlang expressions
1034 in the file. Use format_error/1 to convert the three-element
1035 tuple to an English description of the error.
1036 The encoding of Filename can be set by a comment as described in
1038 epp(3).
1039 path_open(Path, Filename, Modes) ->
1041 {ok, IoDevice, FullName} | {error, Reason}
1042 Types:
1044 Path = [Dir :: name_all()]
1046 Filename = name_all()
1047 Modes = [mode() | directory]
1048 IoDevice = io_device()
1049 FullName = filename_all()
1050 Reason = posix() | badarg | system_limit
1051 Searches the path Path (a list of directory names) until the
1053 file Filename is found. If Filename is an absolute filename,
1054 Path is ignored. Then opens the file in the mode determined by
1055 Modes.
1056 Returns one of the following:
1058 {ok, IoDevice, FullName}:
1060 The file is opened in the requested mode. IoDevice is a ref‐
1061 erence to the file and FullName is the full name of the
1062 file.
1063 {error, enoent}:
1065 The file cannot be found in any of the directories in Path.
1066 {error, atom()}:
1068 The file cannot be opened.
1069 path_script(Path, Filename) ->
1071 {ok, Value, FullName} | {error, Reason}
1072 Types:
1074 Path = [Dir :: name_all()]
1076 Filename = name_all()
1077 Value = term()
1078 FullName = filename_all()
1079 Reason =
1080 posix() |
1081 badarg | terminated | system_limit |
1082 {Line :: integer(), Mod :: module(), Term :: term()}
1083 Searches the path Path (a list of directory names) until the
1085 file Filename is found. If Filename is an absolute filename,
1086 Path is ignored. Then reads and evaluates Erlang expressions,
1087 separated by '.' (or ',', a sequence of expressions is also an
1088 expression), from the file.
1089 Returns one of the following:
1091 {ok, Value, FullName}:
1093 The file is read and evaluated. FullName is the full name of
1094 the file and Value the value of the last expression.
1095 {error, enoent}:
1097 The file cannot be found in any of the directories in Path.
1098 {error, atom()}:
1100 An error occurred when opening the file or reading it. For a
1101 list of typical error codes, see open/2.
1102 {error, {Line, Mod, Term}}:
1104 An error occurred when interpreting the Erlang expressions
1105 in the file. Use format_error/1 to convert the three-element
1106 tuple to an English description of the error.
1107 The encoding of Filename can be set by a comment as described in
1109 epp(3).
1110 path_script(Path, Filename, Bindings) ->
1112 {ok, Value, FullName} | {error, Reason}
1113 Types:
1115 Path = [Dir :: name_all()]
1117 Filename = name_all()
1118 Bindings = erl_eval:binding_struct()
1119 Value = term()
1120 FullName = filename_all()
1121 Reason =
1122 posix() |
1123 badarg | terminated | system_limit |
1124 {Line :: integer(), Mod :: module(), Term :: term()}
1125 The same as path_script/2 but the variable bindings Bindings are
1127 used in the evaluation. See erl_eval(3) about variable bindings.
1128 pid2name(Pid) -> {ok, Filename} | undefined
1130 Types:
1132 Filename = filename_all()
1134 Pid = pid()
1135 If Pid is an I/O device, that is, a pid returned from open/2,
1137 this function returns the filename, or rather:
1138 {ok, Filename}:
1140 If the file server of this node is not a slave, the file was
1141 opened by the file server of this node (this implies that
1142 Pid must be a local pid) and the file is not closed. File‐
1143 name is the filename in flat string format.
1144 undefined:
1146 In all other cases.
1147 Warning:
1149 This function is intended for debugging only.
1150 position(IoDevice, Location) ->
1153 {ok, NewPosition} | {error, Reason}
1154 Types:
1156 IoDevice = io_device()
1158 Location = location()
1159 NewPosition = integer()
1160 Reason = posix() | badarg | terminated
1161 Sets the position of the file referenced by IoDevice to Loca‐
1163 tion. Returns {ok, NewPosition} (as absolute offset) if success‐
1164 ful, otherwise {error, Reason}. Location is one of the follow‐
1165 ing:
1166 Offset:
1168 The same as {bof, Offset}.
1169 {bof, Offset}:
1171 Absolute offset.
1172 {cur, Offset}:
1174 Offset from the current position.
1175 {eof, Offset}:
1177 Offset from the end of file.
1178 bof | cur | eof:
1180 The same as above with Offset 0.
1181 Notice that offsets are counted in bytes, not in characters. If
1183 the file is opened using some other encoding than latin1, one
1184 byte does not correspond to one character. Positioning in such a
1185 file can only be done to known character boundaries. That is, to
1186 a position earlier retrieved by getting a current position, to
1187 the beginning/end of the file or to some other position known to
1188 be on a correct character boundary by some other means (typi‐
1189 cally beyond a byte order mark in the file, which has a known
1190 byte-size).
1191 A typical error reason is:
1193 einval:
1195 Either Location is illegal, or it is evaluated to a negative
1196 offset in the file. Notice that if the resulting position is
1197 a negative value, the result is an error, and after the call
1198 the file position is undefined.
1199 pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason}
1201 Types:
1203 IoDevice = io_device()
1205 LocNums =
1206 [{Location :: location(), Number :: integer() >= 0}]
1207 DataL = [Data]
1208 Data = string() | binary() | eof
1209 Reason = posix() | badarg | terminated
1210 Performs a sequence of pread/3 in one operation, which is more
1212 efficient than calling them one at a time. Returns {ok, [Data,
1213 ...]} or {error, Reason}, where each Data, the result of the
1214 corresponding pread, is either a list or a binary depending on
1215 the mode of the file, or eof if the requested position is beyond
1216 end of file.
1217 As the position is specified as a byte-offset, take special cau‐
1219 tion when working with files where encoding is set to something
1220 else than latin1, as not every byte position is a valid charac‐
1221 ter boundary on such a file.
1222 pread(IoDevice, Location, Number) ->
1224 {ok, Data} | eof | {error, Reason}
1225 Types:
1227 IoDevice = io_device()
1229 Location = location()
1230 Number = integer() >= 0
1231 Data = string() | binary()
1232 Reason = posix() | badarg | terminated
1233 Combines position/2 and read/2 in one operation, which is more
1235 efficient than calling them one at a time.
1236 Location is only allowed to be an integer for raw and ram modes.
1238 The current position of the file after the operation is unde‐
1240 fined for raw mode and unchanged for ram mode.
1241 As the position is specified as a byte-offset, take special cau‐
1243 tion when working with files where encoding is set to something
1244 else than latin1, as not every byte position is a valid charac‐
1245 ter boundary on such a file.
1246 pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}}
1248 Types:
1250 IoDevice = io_device()
1252 LocBytes = [{Location :: location(), Bytes :: iodata()}]
1253 N = integer() >= 0
1254 Reason = posix() | badarg | terminated
1255 Performs a sequence of pwrite/3 in one operation, which is more
1257 efficient than calling them one at a time. Returns ok or {error,
1258 {N, Reason}}, where N is the number of successful writes done
1259 before the failure.
1260 When positioning in a file with other encoding than latin1, cau‐
1262 tion must be taken to set the position on a correct character
1263 boundary. For details, see position/2.
1264 pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason}
1266 Types:
1268 IoDevice = io_device()
1270 Location = location()
1271 Bytes = iodata()
1272 Reason = posix() | badarg | terminated
1273 Combines position/2 and write/2 in one operation, which is more
1275 efficient than calling them one at a time.
1276 Location is only allowed to be an integer for raw and ram modes.
1278 The current position of the file after the operation is unde‐
1280 fined for raw mode and unchanged for ram mode.
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 read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}
1287 Types:
1289 IoDevice = io_device() | atom()
1291 Number = integer() >= 0
1292 Data = string() | binary()
1293 Reason =
1294 posix() |
1295 badarg | terminated |
1296 {no_translation, unicode, latin1}
1297 Reads Number bytes/characters from the file referenced by IoDe‐
1299 vice. The functions read/2, pread/3, and read_line/1 are the
1300 only ways to read from a file opened in raw mode (although they
1301 work for normally opened files, too).
1302 For files where encoding is set to something else than latin1,
1304 one character can be represented by more than one byte on the
1305 file. The parameter Number always denotes the number of charac‐
1306 ters read from the file, while the position in the file can be
1307 moved much more than this number when reading a Unicode file.
1308 Also, if encoding is set to something else than latin1, the
1310 read/3 call fails if the data contains characters larger than
1311 255, which is why module io(3) is to be preferred when reading
1312 such a file.
1313 The function returns:
1315 {ok, Data}:
1317 If the file was opened in binary mode, the read bytes are
1318 returned in a binary, otherwise in a list. The list or
1319 binary is shorter than the number of bytes requested if end
1320 of file was reached.
1321 eof:
1323 Returned if Number>0 and end of file was reached before any‐
1324 thing at all could be read.
1325 {error, Reason}:
1327 An error occurred.
1328 Typical error reasons:
1330 ebadf:
1332 The file is not opened for reading.
1333 {no_translation, unicode, latin1}:
1335 The file is opened with another encoding than latin1 and the
1336 data in the file cannot be translated to the byte-oriented
1337 data that this function returns.
1338 read_file(Filename) -> {ok, Binary} | {error, Reason}
1340 Types:
1342 Filename = name_all()
1344 Binary = binary()
1345 Reason = posix() | badarg | terminated | system_limit
1346 Returns {ok, Binary}, where Binary is a binary data object that
1348 contains the contents of Filename, or {error, Reason} if an
1349 error occurs.
1350 Typical error reasons:
1352 enoent:
1354 The file does not exist.
1355 eacces:
1357 Missing permission for reading the file, or for searching
1358 one of the parent directories.
1359 eisdir:
1361 The named file is a directory.
1362 enotdir:
1364 A component of the filename is not a directory. On some
1365 platforms, enoent is returned instead.
1366 enomem:
1368 There is not enough memory for the contents of the file.
1369 read_file_info(File) -> {ok, FileInfo} | {error, Reason}
1371 read_file_info(File, Opts) -> {ok, FileInfo} | {error, Reason}
1373 Types:
1375 File = name_all() | io_device()
1377 Opts = [file_info_option()]
1378 FileInfo = file_info()
1379 Reason = posix() | badarg
1380 Retrieves information about a file. Returns {ok, FileInfo} if
1382 successful, otherwise {error, Reason}. FileInfo is a record
1383 file_info, defined in the Kernel include file file.hrl. Include
1384 the following directive in the module from which the function is
1385 called:
1386 -include_lib("kernel/include/file.hrl").
1388 The time type returned in atime, mtime, and ctime is dependent
1390 on the time type set in Opts :: {time, Type} as follows:
1391 local:
1393 Returns local time.
1394 universal:
1396 Returns universal time.
1397 posix:
1399 Returns seconds since or before Unix time epoch, which is
1400 1970-01-01 00:00 UTC.
1401 Default is {time, local}.
1403 If the option raw is set, the file server is not called and only
1405 information about local files is returned. Note that this will
1406 break this module's atomicity guarantees as it can race with a
1407 concurrent call to write_file_info/1,2.
1408 This option has no effect when the function is given an I/O
1410 device instead of a file name. Use open/2 with the raw mode to
1411 obtain a file descriptor first.
1412 Note:
1414 As file times are stored in POSIX time on most OS, it is faster
1415 to query file information with option posix.
1416 The record file_info contains the following fields:
1419 size = integer() >= 0:
1421 Size of file in bytes.
1422 type = device | directory | other | regular | symlink:
1424 The type of the file.
1425 access = read | write | read_write | none:
1427 The current system access to the file.
1428 atime = date_time() | integer() >= 0:
1430 The last time the file was read.
1431 mtime = date_time() | integer() >= 0:
1433 The last time the file was written.
1434 ctime = date_time() | integer() >=0:
1436 The interpretation of this time field depends on the operat‐
1437 ing system. On Unix, it is the last time the file or the
1438 inode was changed. In Windows, it is the create time.
1439 mode = integer() >= 0:
1441 The file permissions as the sum of the following bit values:
1442 8#00400:
1444 read permission: owner
1445 8#00200:
1447 write permission: owner
1448 8#00100:
1450 execute permission: owner
1451 8#00040:
1453 read permission: group
1454 8#00020:
1456 write permission: group
1457 8#00010:
1459 execute permission: group
1460 8#00004:
1462 read permission: other
1463 8#00002:
1465 write permission: other
1466 8#00001:
1468 execute permission: other
1469 16#800:
1471 set user id on execution
1472 16#400:
1474 set group id on execution
1475 On Unix platforms, other bits than those listed above may be
1477 set.
1478 links = integer() >= 0:
1480 Number of links to the file (this is always 1 for file sys‐
1481 tems that have no concept of links).
1482 major_device = integer() >= 0:
1484 Identifies the file system where the file is located. In
1485 Windows, the number indicates a drive as follows: 0 means
1486 A:, 1 means B:, and so on.
1487 minor_device = integer() >= 0:
1489 Only valid for character devices on Unix. In all other
1490 cases, this field is zero.
1491 inode = integer() >= 0:
1493 Gives the inode number. On non-Unix file systems, this field
1494 is zero.
1495 uid = integer() >= 0:
1497 Indicates the owner of the file. On non-Unix file systems,
1498 this field is zero.
1499 gid = integer() >= 0:
1501 Gives the group that the owner of the file belongs to. On
1502 non-Unix file systems, this field is zero.
1503 Typical error reasons:
1505 eacces:
1507 Missing search permission for one of the parent directories
1508 of the file.
1509 enoent:
1511 The file does not exist.
1512 enotdir:
1514 A component of the filename is not a directory. On some
1515 platforms, enoent is returned instead.
1516 read_line(IoDevice) -> {ok, Data} | eof | {error, Reason}
1518 Types:
1520 IoDevice = io_device() | atom()
1522 Data = string() | binary()
1523 Reason =
1524 posix() |
1525 badarg | terminated |
1526 {no_translation, unicode, latin1}
1527 Reads a line of bytes/characters from the file referenced by
1529 IoDevice. Lines are defined to be delimited by the linefeed (LF,
1530 \n) character, but any carriage return (CR, \r) followed by a
1531 newline is also treated as a single LF character (the carriage
1532 return is silently ignored). The line is returned including the
1533 LF, but excluding any CR immediately followed by an LF. This be‐
1534 haviour is consistent with the behaviour of io:get_line/2. If
1535 end of file is reached without any LF ending the last line, a
1536 line with no trailing LF is returned.
1537 The function can be used on files opened in raw mode. However,
1539 it is inefficient to use it on raw files if the file is not
1540 opened with option {read_ahead, Size} specified. Thus, combining
1541 raw and {read_ahead, Size} is highly recommended when opening a
1542 text file for raw line-oriented reading.
1543 If encoding is set to something else than latin1, the
1545 read_line/1 call fails if the data contains characters larger
1546 than 255, why module io(3) is to be preferred when reading such
1547 a file.
1548 The function returns:
1550 {ok, Data}:
1552 One line from the file is returned, including the trailing
1553 LF, but with CRLF sequences replaced by a single LF (see
1554 above).
1555 If the file is opened in binary mode, the read bytes are
1557 returned in a binary, otherwise in a list.
1558 eof:
1560 Returned if end of file was reached before anything at all
1561 could be read.
1562 {error, Reason}:
1564 An error occurred.
1565 Typical error reasons:
1567 ebadf:
1569 The file is not opened for reading.
1570 {no_translation, unicode, latin1}:
1572 The file is opened with another encoding than latin1 and the
1573 data on the file cannot be translated to the byte-oriented
1574 data that this function returns.
1575 read_link(Name) -> {ok, Filename} | {error, Reason}
1577 Types:
1579 Name = name_all()
1581 Filename = filename()
1582 Reason = posix() | badarg
1583 Returns {ok, Filename} if Name refers to a symbolic link that is
1585 not a raw filename, or {error, Reason} otherwise. On platforms
1586 that do not support symbolic links, the return value is
1587 {error,enotsup}.
1588 Typical error reasons:
1590 einval:
1592 Name does not refer to a symbolic link or the name of the
1593 file that it refers to does not conform to the expected
1594 encoding.
1595 enoent:
1597 The file does not exist.
1598 enotsup:
1600 Symbolic links are not supported on this platform.
1601 read_link_all(Name) -> {ok, Filename} | {error, Reason}
1603 Types:
1605 Name = name_all()
1607 Filename = filename_all()
1608 Reason = posix() | badarg
1609 Returns {ok, Filename} if Name refers to a symbolic link or
1611 {error, Reason} otherwise. On platforms that do not support sym‐
1612 bolic links, the return value is {error,enotsup}.
1613 Notice that Filename can be either a list or a binary.
1615 Typical error reasons:
1617 einval:
1619 Name does not refer to a symbolic link.
1620 enoent:
1622 The file does not exist.
1623 enotsup:
1625 Symbolic links are not supported on this platform.
1626 read_link_info(Name) -> {ok, FileInfo} | {error, Reason}
1628 read_link_info(Name, Opts) -> {ok, FileInfo} | {error, Reason}
1630 Types:
1632 Name = name_all()
1634 Opts = [file_info_option()]
1635 FileInfo = file_info()
1636 Reason = posix() | badarg
1637 Works like read_file_info/1,2 except that if Name is a symbolic
1639 link, information about the link is returned in the file_info
1640 record and the type field of the record is set to symlink.
1641 If the option raw is set, the file server is not called and only
1643 information about local files is returned. Note that this will
1644 break this module's atomicity guarantees as it can race with a
1645 concurrent call to write_file_info/1,2
1646 If Name is not a symbolic link, this function returns the same
1648 result as read_file_info/1. On platforms that do not support
1649 symbolic links, this function is always equivalent to
1650 read_file_info/1.
1651 rename(Source, Destination) -> ok | {error, Reason}
1653 Types:
1655 Source = Destination = name_all()
1657 Reason = posix() | badarg
1658 Tries to rename the file Source to Destination. It can be used
1660 to move files (and directories) between directories, but it is
1661 not sufficient to specify the destination only. The destination
1662 filename must also be specified. For example, if bar is a normal
1663 file and foo and baz are directories, rename("foo/bar", "baz")
1664 returns an error, but rename("foo/bar", "baz/bar") succeeds.
1665 Returns ok if it is successful.
1666 Note:
1668 Renaming of open files is not allowed on most platforms (see
1669 eacces below).
1670 Typical error reasons:
1673 eacces:
1675 Missing read or write permissions for the parent directories
1676 of Source or Destination. On some platforms, this error is
1677 given if either Source or Destination is open.
1678 eexist:
1680 Destination is not an empty directory. On some platforms,
1681 also given when Source and Destination are not of the same
1682 type.
1683 einval:
1685 Source is a root directory, or Destination is a subdirectory
1686 of Source.
1687 eisdir:
1689 Destination is a directory, but Source is not.
1690 enoent:
1692 Source does not exist.
1693 enotdir:
1695 Source is a directory, but Destination is not.
1696 exdev:
1698 Source and Destination are on different file systems.
1699 script(Filename) -> {ok, Value} | {error, Reason}
1701 Types:
1703 Filename = name_all()
1705 Value = term()
1706 Reason =
1707 posix() |
1708 badarg | terminated | system_limit |
1709 {Line :: integer(), Mod :: module(), Term :: term()}
1710 Reads and evaluates Erlang expressions, separated by '.' (or
1712 ',', a sequence of expressions is also an expression), from the
1713 file.
1714 Returns one of the following:
1716 {ok, Value}:
1718 The file is read and evaluated. Value is the value of the
1719 last expression.
1720 {error, atom()}:
1722 An error occurred when opening the file or reading it. For a
1723 list of typical error codes, see open/2.
1724 {error, {Line, Mod, Term}}:
1726 An error occurred when interpreting the Erlang expressions
1727 in the file. Use format_error/1 to convert the three-element
1728 tuple to an English description of the error.
1729 The encoding of Filename can be set by a comment as described in
1731 epp(3).
1732 script(Filename, Bindings) -> {ok, Value} | {error, Reason}
1734 Types:
1736 Filename = name_all()
1738 Bindings = erl_eval:binding_struct()
1739 Value = term()
1740 Reason =
1741 posix() |
1742 badarg | terminated | system_limit |
1743 {Line :: integer(), Mod :: module(), Term :: term()}
1744 The same as script/1 but the variable bindings Bindings are used
1746 in the evaluation. See erl_eval(3) about variable bindings.
1747 sendfile(Filename, Socket) ->
1749 {ok, integer() >= 0} |
1750 {error, inet:posix() | closed | badarg | not_owner}
1751 Types:
1753 Filename = name_all()
1755 Socket = inet:socket()
1756 Sends the file Filename to Socket. Returns {ok, BytesSent} if
1758 successful, otherwise {error, Reason}.
1759 sendfile(RawFile, Socket, Offset, Bytes, Opts) ->
1761 {ok, integer() >= 0} |
1762 {error, inet:posix() | closed | badarg | not_owner}
1763 Types:
1765 RawFile = fd()
1767 Socket = inet:socket()
1768 Offset = Bytes = integer() >= 0
1769 Opts = [sendfile_option()]
1770 sendfile_option() =
1771 {chunk_size, integer() >= 0} | {use_threads, boolean()}
1772 Sends Bytes from the file referenced by RawFile beginning at
1774 Offset to Socket. Returns {ok, BytesSent} if successful, other‐
1775 wise {error, Reason}. If Bytes is set to 0 all data after the
1776 specified Offset is sent.
1777 The file used must be opened using the raw flag, and the process
1779 calling sendfile must be the controlling process of the socket.
1780 See gen_tcp:controlling_process/2.
1781 If the OS used does not support non-blocking sendfile, an Erlang
1783 fallback using read/2 and gen_tcp:send/2 is used.
1784 The option list can contain the following options:
1786 chunk_size:
1788 The chunk size used by the Erlang fallback to send data. If
1789 using the fallback, set this to a value that comfortably
1790 fits in the systems memory. Default is 20 MB.
1791 set_cwd(Dir) -> ok | {error, Reason}
1793 Types:
1795 Dir = name() | EncodedBinary
1797 EncodedBinary = binary()
1798 Reason = posix() | badarg | no_translation
1799 Sets the current working directory of the file server to Dir.
1801 Returns ok if successful.
1802 The functions in the module file usually treat binaries as raw
1804 filenames, that is, they are passed "as is" even when the encod‐
1805 ing of the binary does not agree with native_name_encoding().
1806 However, this function expects binaries to be encoded according
1807 to the value returned by native_name_encoding().
1808 Typical error reasons are:
1810 enoent:
1812 The directory does not exist.
1813 enotdir:
1815 A component of Dir is not a directory. On some platforms,
1816 enoent is returned.
1817 eacces:
1819 Missing permission for the directory or one of its parents.
1820 badarg:
1822 Dir has an improper type, such as tuple.
1823 no_translation:
1825 Dir is a binary() with characters coded in ISO-latin-1 and
1826 the VM is operating with unicode filename encoding.
1827 Warning:
1829 In a future release, a bad type for argument Dir will probably
1830 generate an exception.
1831 sync(IoDevice) -> ok | {error, Reason}
1834 Types:
1836 IoDevice = io_device()
1838 Reason = posix() | badarg | terminated
1839 Ensures that any buffers kept by the operating system (not by
1841 the Erlang runtime system) are written to disk. On some plat‐
1842 forms, this function might have no effect.
1843 A typical error reason is:
1845 enospc:
1847 Not enough space left to write the file.
1848 truncate(IoDevice) -> ok | {error, Reason}
1850 Types:
1852 IoDevice = io_device()
1854 Reason = posix() | badarg | terminated
1855 Truncates the file referenced by IoDevice at the current posi‐
1857 tion. Returns ok if successful, otherwise {error, Reason}.
1858 write(IoDevice, Bytes) -> ok | {error, Reason}
1860 Types:
1862 IoDevice = io_device() | atom()
1864 Bytes = iodata()
1865 Reason = posix() | badarg | terminated
1866 Writes Bytes to the file referenced by IoDevice. This function
1868 is the only way to write to a file opened in raw mode (although
1869 it works for normally opened files too). Returns ok if success‐
1870 ful, and {error, Reason} otherwise.
1871 If the file is opened with encoding set to something else than
1873 latin1, each byte written can result in many bytes being written
1874 to the file, as the byte range 0..255 can represent anything
1875 between one and four bytes depending on value and UTF encoding
1876 type.
1877 Typical error reasons:
1879 ebadf:
1881 The file is not opened for writing.
1882 enospc:
1884 No space is left on the device.
1885 write_file(Filename, Bytes) -> ok | {error, Reason}
1887 Types:
1889 Filename = name_all()
1891 Bytes = iodata()
1892 Reason = posix() | badarg | terminated | system_limit
1893 Writes the contents of the iodata term Bytes to file Filename.
1895 The file is created if it does not exist. If it exists, the pre‐
1896 vious contents are overwritten. Returns ok if successful, other‐
1897 wise {error, Reason}.
1898 Typical error reasons:
1900 enoent:
1902 A component of the filename does not exist.
1903 enotdir:
1905 A component of the filename is not a directory. On some
1906 platforms, enoent is returned instead.
1907 enospc:
1909 No space is left on the device.
1910 eacces:
1912 Missing permission for writing the file or searching one of
1913 the parent directories.
1914 eisdir:
1916 The named file is a directory.
1917 write_file(Filename, Bytes, Modes) -> ok | {error, Reason}
1919 Types:
1921 Filename = name_all()
1923 Bytes = iodata()
1924 Modes = [mode()]
1925 Reason = posix() | badarg | terminated | system_limit
1926 Same as write_file/2, but takes a third argument Modes, a list
1928 of possible modes, see open/2. The mode flags binary and write
1929 are implicit, so they are not to be used.
1930 write_file_info(Filename, FileInfo) -> ok | {error, Reason}
1932 write_file_info(Filename, FileInfo, Opts) -> ok | {error, Reason}
1934 Types:
1936 Filename = name_all()
1938 Opts = [file_info_option()]
1939 FileInfo = file_info()
1940 Reason = posix() | badarg
1941 Changes file information. Returns ok if successful, otherwise
1943 {error, Reason}. FileInfo is a record file_info, defined in the
1944 Kernel include file file.hrl. Include the following directive in
1945 the module from which the function is called:
1946 -include_lib("kernel/include/file.hrl").
1948 The time type set in atime, mtime, and ctime depends on the time
1950 type set in Opts :: {time, Type} as follows:
1951 local:
1953 Interprets the time set as local.
1954 universal:
1956 Interprets it as universal time.
1957 posix:
1959 Must be seconds since or before Unix time epoch, which is
1960 1970-01-01 00:00 UTC.
1961 Default is {time, local}.
1963 If the option raw is set, the file server is not called and only
1965 information about local files is returned.
1966 The following fields are used from the record, if they are spec‐
1968 ified:
1969 atime = date_time() | integer() >= 0:
1971 The last time the file was read.
1972 mtime = date_time() | integer() >= 0:
1974 The last time the file was written.
1975 ctime = date_time() | integer() >= 0:
1977 On Unix, any value specified for this field is ignored (the
1978 "ctime" for the file is set to the current time). On Win‐
1979 dows, this field is the new creation time to set for the
1980 file.
1981 mode = integer() >= 0:
1983 The file permissions as the sum of the following bit values:
1984 8#00400:
1986 Read permission: owner
1987 8#00200:
1989 Write permission: owner
1990 8#00100:
1992 Execute permission: owner
1993 8#00040:
1995 Read permission: group
1996 8#00020:
1998 Write permission: group
1999 8#00010:
2001 Execute permission: group
2002 8#00004:
2004 Read permission: other
2005 8#00002:
2007 Write permission: other
2008 8#00001:
2010 Execute permission: other
2011 16#800:
2013 Set user id on execution
2014 16#400:
2016 Set group id on execution
2017 On Unix platforms, other bits than those listed above may be
2019 set.
2020 uid = integer() >= 0:
2022 Indicates the file owner. Ignored for non-Unix file systems.
2023 gid = integer() >= 0:
2025 Gives the group that the file owner belongs to. Ignored for
2026 non-Unix file systems.
2027 Typical error reasons:
2029 eacces:
2031 Missing search permission for one of the parent directories
2032 of the file.
2033 enoent:
2035 The file does not exist.
2036 enotdir:
2038 A component of the filename is not a directory. On some
2039 platforms, enoent is returned instead.
2040
2042 * eacces - Permission denied
2043 * eagain - Resource temporarily unavailable
2045 * ebadf - Bad file number
2047 * ebusy - File busy
2049 * edquot - Disk quota exceeded
2051 * eexist - File already exists
2053 * efault - Bad address in system call argument
2055 * efbig - File too large
2057 * eintr - Interrupted system call
2059 * einval - Invalid argument
2061 * eio - I/O error
2063 * eisdir - Illegal operation on a directory
2065 * eloop - Too many levels of symbolic links
2067 * emfile - Too many open files
2069 * emlink - Too many links
2071 * enametoolong - Filename too long
2073 * enfile - File table overflow
2075 * enodev - No such device
2077 * enoent - No such file or directory
2079 * enomem - Not enough memory
2081 * enospc - No space left on device
2083 * enotblk - Block device required
2085 * enotdir - Not a directory
2087 * enotsup - Operation not supported
2089 * enxio - No such device or address
2091 * eperm - Not owner
2093 * epipe - Broken pipe
2095 * erofs - Read-only file system
2097 * espipe - Invalid seek
2099 * esrch - No such process
2101 * estale - Stale remote file handle
2103 * exdev - Cross-domain link
2105
2107 For increased performance, raw files are recommended.
2108 A normal file is really a process so it can be used as an I/O device
2110 (see io). Therefore, when data is written to a normal file, the sending
2111 of the data to the file process, copies all data that are not binaries.
2112 Opening the file in binary mode and writing binaries is therefore rec‐
2113 ommended. If the file is opened on another node, or if the file server
2114 runs as slave to the file server of another node, also binaries are
2115 copied.
2116 Note:
2118 Raw files use the file system of the host machine of the node. For nor‐
2119 mal files (non-raw), the file server is used to find the files, and if
2120 the node is running its file server as slave to the file server of
2121 another node, and the other node runs on some other host machine, they
2122 can have different file systems. However, this is seldom a problem.
2123 open/2 can be given the options delayed_write and read_ahead to turn on
2126 caching, which will reduce the number of operating system calls and
2127 greatly improve performance for small reads and writes. However, the
2128 overhead won't disappear completely and it's best to keep the number of
2129 file operations to a minimum. As a contrived example, the following
2130 function writes 4MB in 2.5 seconds when tested:
2131 create_file_slow(Name) ->
2133 {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2134 create_file_slow_1(Fd, 4 bsl 20),
2135 file:close(Fd).
2136 create_file_slow_1(_Fd, 0) ->
2138 ok;
2139 create_file_slow_1(Fd, M) ->
2140 ok = file:write(Fd, <<0>>),
2141 create_file_slow_1(Fd, M - 1).
2142 The following functionally equivalent code writes 128 bytes per call to
2144 write/2 and so does the same work in 0.08 seconds, which is roughly 30
2145 times faster:
2146 create_file(Name) ->
2148 {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2149 create_file_1(Fd, 4 bsl 20),
2150 file:close(Fd),
2151 ok.
2152 create_file_1(_Fd, 0) ->
2154 ok;
2155 create_file_1(Fd, M) when M >= 128 ->
2156 ok = file:write(Fd, <<0:(128)/unit:8>>),
2157 create_file_1(Fd, M - 128);
2158 create_file_1(Fd, M) ->
2159 ok = file:write(Fd, <<0:(M)/unit:8>>),
2160 create_file_1(Fd, M - 1).
2161 When writing data it's generally more efficient to write a list of
2163 binaries rather than a list of integers. It is not needed to flatten a
2164 deep list before writing. On Unix hosts, scatter output, which writes a
2165 set of buffers in one operation, is used when possible. In this way
2166 write(FD, [Bin1, Bin2 | Bin3]) writes the contents of the binaries
2167 without copying the data at all, except for perhaps deep down in the
2168 operating system kernel.
2169 Warning:
2171 If an error occurs when accessing an open file with module io, the
2172 process handling the file exits. The dead file process can hang if a
2173 process tries to access it later. This will be fixed in a future
2174 release.
2175
2178 filename(3)
2179Ericsson AB kernel 7.3 file(3)