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