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 If Pid is an I/O device, that is, a pid returned from open/2,
1159 this function returns the filename, or rather:
1160 {ok, Filename}:
1162 If the file server of this node is not a slave, the file was
1163 opened by the file server of this node (this implies that
1164 Pid must be a local pid) and the file is not closed. File‐
1165 name is the filename in flat string format.
1166 undefined:
1168 In all other cases.
1169 Warning:
1171 This function is intended for debugging only.
1172 position(IoDevice, Location) ->
1175 {ok, NewPosition} | {error, Reason}
1176 Types:
1178 IoDevice = io_device()
1180 Location = location()
1181 NewPosition = integer()
1182 Reason = posix() | badarg | terminated
1183 Sets the position of the file referenced by IoDevice to Loca‐
1185 tion. Returns {ok, NewPosition} (as absolute offset) if success‐
1186 ful, otherwise {error, Reason}. Location is one of the follow‐
1187 ing:
1188 Offset:
1190 The same as {bof, Offset}.
1191 {bof, Offset}:
1193 Absolute offset.
1194 {cur, Offset}:
1196 Offset from the current position.
1197 {eof, Offset}:
1199 Offset from the end of file.
1200 bof | cur | eof:
1202 The same as above with Offset 0.
1203 Notice that offsets are counted in bytes, not in characters. If
1205 the file is opened using some other encoding than latin1, one
1206 byte does not correspond to one character. Positioning in such a
1207 file can only be done to known character boundaries. That is, to
1208 a position earlier retrieved by getting a current position, to
1209 the beginning/end of the file or to some other position known to
1210 be on a correct character boundary by some other means (typi‐
1211 cally beyond a byte order mark in the file, which has a known
1212 byte-size).
1213 A typical error reason is:
1215 einval:
1217 Either Location is illegal, or it is evaluated to a negative
1218 offset in the file. Notice that if the resulting position is
1219 a negative value, the result is an error, and after the call
1220 the file position is undefined.
1221 pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason}
1223 Types:
1225 IoDevice = io_device()
1227 LocNums =
1228 [{Location :: location(), Number :: integer() >= 0}]
1229 DataL = [Data]
1230 Data = string() | binary() | eof
1231 Reason = posix() | badarg | terminated
1232 Performs a sequence of pread/3 in one operation, which is more
1234 efficient than calling them one at a time. Returns {ok, [Data,
1235 ...]} or {error, Reason}, where each Data, the result of the
1236 corresponding pread, is either a list or a binary depending on
1237 the mode of the file, or eof if the requested position is beyond
1238 end of file.
1239 As the position is specified as a byte-offset, take special cau‐
1241 tion when working with files where encoding is set to something
1242 else than latin1, as not every byte position is a valid charac‐
1243 ter boundary on such a file.
1244 pread(IoDevice, Location, Number) ->
1246 {ok, Data} | eof | {error, Reason}
1247 Types:
1249 IoDevice = io_device()
1251 Location = location()
1252 Number = integer() >= 0
1253 Data = string() | binary()
1254 Reason = posix() | badarg | terminated
1255 Combines position/2 and read/2 in one operation, which is more
1257 efficient than calling them one at a time.
1258 Location is only allowed to be an integer for raw and ram modes.
1260 The current position of the file after the operation is unde‐
1262 fined for raw mode and unchanged for ram mode.
1263 As the position is specified as a byte-offset, take special cau‐
1265 tion when working with files where encoding is set to something
1266 else than latin1, as not every byte position is a valid charac‐
1267 ter boundary on such a file.
1268 pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}}
1270 Types:
1272 IoDevice = io_device()
1274 LocBytes = [{Location :: location(), Bytes :: iodata()}]
1275 N = integer() >= 0
1276 Reason = posix() | badarg | terminated
1277 Performs a sequence of pwrite/3 in one operation, which is more
1279 efficient than calling them one at a time. Returns ok or {error,
1280 {N, Reason}}, where N is the number of successful writes done
1281 before the failure.
1282 When positioning in a file with other encoding than latin1, cau‐
1284 tion must be taken to set the position on a correct character
1285 boundary. For details, see position/2.
1286 pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason}
1288 Types:
1290 IoDevice = io_device()
1292 Location = location()
1293 Bytes = iodata()
1294 Reason = posix() | badarg | terminated
1295 Combines position/2 and write/2 in one operation, which is more
1297 efficient than calling them one at a time.
1298 Location is only allowed to be an integer for raw and ram modes.
1300 The current position of the file after the operation is unde‐
1302 fined for raw mode and unchanged for ram mode.
1303 When positioning in a file with other encoding than latin1, cau‐
1305 tion must be taken to set the position on a correct character
1306 boundary. For details, see position/2.
1307 read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}
1309 Types:
1311 IoDevice = io_device() | atom()
1313 Number = integer() >= 0
1314 Data = string() | binary()
1315 Reason =
1316 posix() |
1317 badarg | terminated |
1318 {no_translation, unicode, latin1}
1319 Reads Number bytes/characters from the file referenced by IoDe‐
1321 vice. The functions read/2, pread/3, and read_line/1 are the
1322 only ways to read from a file opened in raw mode (although they
1323 work for normally opened files, too).
1324 For files where encoding is set to something else than latin1,
1326 one character can be represented by more than one byte on the
1327 file. The parameter Number always denotes the number of charac‐
1328 ters read from the file, while the position in the file can be
1329 moved much more than this number when reading a Unicode file.
1330 Also, if encoding is set to something else than latin1, the
1332 read/3 call fails if the data contains characters larger than
1333 255, which is why module io(3) is to be preferred when reading
1334 such a file.
1335 The function returns:
1337 {ok, Data}:
1339 If the file was opened in binary mode, the read bytes are
1340 returned in a binary, otherwise in a list. The list or bi‐
1341 nary is shorter than the number of bytes requested if end of
1342 file was reached.
1343 eof:
1345 Returned if Number>0 and end of file was reached before any‐
1346 thing at all could be read.
1347 {error, Reason}:
1349 An error occurred.
1350 Typical error reasons:
1352 ebadf:
1354 The file is not opened for reading.
1355 {no_translation, unicode, latin1}:
1357 The file is opened with another encoding than latin1 and the
1358 data in the file cannot be translated to the byte-oriented
1359 data that this function returns.
1360 read_file(Filename) -> {ok, Binary} | {error, Reason}
1362 Types:
1364 Filename = name_all()
1366 Binary = binary()
1367 Reason = posix() | badarg | terminated | system_limit
1368 Returns {ok, Binary}, where Binary is a binary data object that
1370 contains the contents of Filename, or {error, Reason} if an er‐
1371 ror occurs.
1372 Typical error reasons:
1374 enoent:
1376 The file does not exist.
1377 eacces:
1379 Missing permission for reading the file, or for searching
1380 one of the parent directories.
1381 eisdir:
1383 The named file is a directory.
1384 enotdir:
1386 A component of the filename is not a directory. On some
1387 platforms, enoent is returned instead.
1388 enomem:
1390 There is not enough memory for the contents of the file.
1391 read_file_info(File) -> {ok, FileInfo} | {error, Reason}
1393 read_file_info(File, Opts) -> {ok, FileInfo} | {error, Reason}
1395 Types:
1397 File = name_all() | io_device()
1399 Opts = [file_info_option()]
1400 FileInfo = file_info()
1401 Reason = posix() | badarg
1402 Retrieves information about a file. Returns {ok, FileInfo} if
1404 successful, otherwise {error, Reason}. FileInfo is a record
1405 file_info, defined in the Kernel include file file.hrl. Include
1406 the following directive in the module from which the function is
1407 called:
1408 -include_lib("kernel/include/file.hrl").
1410 The time type returned in atime, mtime, and ctime is dependent
1412 on the time type set in Opts :: {time, Type} as follows:
1413 local:
1415 Returns local time.
1416 universal:
1418 Returns universal time.
1419 posix:
1421 Returns seconds since or before Unix time epoch, which is
1422 1970-01-01 00:00 UTC.
1423 Default is {time, local}.
1425 If the option raw is set, the file server is not called and only
1427 information about local files is returned. Note that this will
1428 break this module's atomicity guarantees as it can race with a
1429 concurrent call to write_file_info/1,2.
1430 This option has no effect when the function is given an I/O de‐
1432 vice instead of a file name. Use open/2 with the raw mode to ob‐
1433 tain a file descriptor first.
1434 Note:
1436 As file times are stored in POSIX time on most OS, it is faster
1437 to query file information with option posix.
1438 The record file_info contains the following fields:
1441 size = integer() >= 0:
1443 Size of file in bytes.
1444 type = device | directory | other | regular:
1446 The type of the file. Can also contain symlink when returned
1447 from read_link_info/1,2.
1448 access = read | write | read_write | none:
1450 The current system access to the file.
1451 atime = date_time() | integer() >= 0:
1453 The last time the file was read.
1454 mtime = date_time() | integer() >= 0:
1456 The last time the file was written.
1457 ctime = date_time() | integer() >=0:
1459 The interpretation of this time field depends on the operat‐
1460 ing system. On Unix, it is the last time the file or the in‐
1461 ode was changed. In Windows, it is the create time.
1462 mode = integer() >= 0:
1464 The file permissions as the sum of the following bit values:
1465 8#00400:
1467 read permission: owner
1468 8#00200:
1470 write permission: owner
1471 8#00100:
1473 execute permission: owner
1474 8#00040:
1476 read permission: group
1477 8#00020:
1479 write permission: group
1480 8#00010:
1482 execute permission: group
1483 8#00004:
1485 read permission: other
1486 8#00002:
1488 write permission: other
1489 8#00001:
1491 execute permission: other
1492 16#800:
1494 set user id on execution
1495 16#400:
1497 set group id on execution
1498 On Unix platforms, other bits than those listed above may be
1500 set.
1501 links = integer() >= 0:
1503 Number of links to the file (this is always 1 for file sys‐
1504 tems that have no concept of links).
1505 major_device = integer() >= 0:
1507 Identifies the file system where the file is located. In
1508 Windows, the number indicates a drive as follows: 0 means
1509 A:, 1 means B:, and so on.
1510 minor_device = integer() >= 0:
1512 Only valid for character devices on Unix. In all other
1513 cases, this field is zero.
1514 inode = integer() >= 0:
1516 Gives the inode number. On non-Unix file systems, this field
1517 is zero.
1518 uid = integer() >= 0:
1520 Indicates the owner of the file. On non-Unix file systems,
1521 this field is zero.
1522 gid = integer() >= 0:
1524 Gives the group that the owner of the file belongs to. On
1525 non-Unix file systems, this field is zero.
1526 Typical error reasons:
1528 eacces:
1530 Missing search permission for one of the parent directories
1531 of the file.
1532 enoent:
1534 The file does not exist.
1535 enotdir:
1537 A component of the filename is not a directory. On some
1538 platforms, enoent is returned instead.
1539 read_line(IoDevice) -> {ok, Data} | eof | {error, Reason}
1541 Types:
1543 IoDevice = io_device() | atom()
1545 Data = string() | binary()
1546 Reason =
1547 posix() |
1548 badarg | terminated |
1549 {no_translation, unicode, latin1}
1550 Reads a line of bytes/characters from the file referenced by
1552 IoDevice. Lines are defined to be delimited by the linefeed (LF,
1553 \n) character, but any carriage return (CR, \r) followed by a
1554 newline is also treated as a single LF character (the carriage
1555 return is silently ignored). The line is returned including the
1556 LF, but excluding any CR immediately followed by an LF. This be‐
1557 haviour is consistent with the behaviour of io:get_line/2. If
1558 end of file is reached without any LF ending the last line, a
1559 line with no trailing LF is returned.
1560 The function can be used on files opened in raw mode. However,
1562 it is inefficient to use it on raw files if the file is not
1563 opened with option {read_ahead, Size} specified. Thus, combining
1564 raw and {read_ahead, Size} is highly recommended when opening a
1565 text file for raw line-oriented reading.
1566 If encoding is set to something else than latin1, the
1568 read_line/1 call fails if the data contains characters larger
1569 than 255, why module io(3) is to be preferred when reading such
1570 a file.
1571 The function returns:
1573 {ok, Data}:
1575 One line from the file is returned, including the trailing
1576 LF, but with CRLF sequences replaced by a single LF (see
1577 above).
1578 If the file is opened in binary mode, the read bytes are re‐
1580 turned in a binary, otherwise in a list.
1581 eof:
1583 Returned if end of file was reached before anything at all
1584 could be read.
1585 {error, Reason}:
1587 An error occurred.
1588 Typical error reasons:
1590 ebadf:
1592 The file is not opened for reading.
1593 {no_translation, unicode, latin1}:
1595 The file is opened with another encoding than latin1 and the
1596 data on the file cannot be translated to the byte-oriented
1597 data that this function returns.
1598 read_link(Name) -> {ok, Filename} | {error, Reason}
1600 Types:
1602 Name = name_all()
1604 Filename = filename()
1605 Reason = posix() | badarg
1606 Returns {ok, Filename} if Name refers to a symbolic link that is
1608 not a raw filename, or {error, Reason} otherwise. On platforms
1609 that do not support symbolic links, the return value is {er‐
1610 ror,enotsup}.
1611 Typical error reasons:
1613 einval:
1615 Name does not refer to a symbolic link or the name of the
1616 file that it refers to does not conform to the expected en‐
1617 coding.
1618 enoent:
1620 The file does not exist.
1621 enotsup:
1623 Symbolic links are not supported on this platform.
1624 read_link_all(Name) -> {ok, Filename} | {error, Reason}
1626 Types:
1628 Name = name_all()
1630 Filename = filename_all()
1631 Reason = posix() | badarg
1632 Returns {ok, Filename} if Name refers to a symbolic link or {er‐
1634 ror, Reason} otherwise. On platforms that do not support sym‐
1635 bolic links, the return value is {error,enotsup}.
1636 Notice that Filename can be either a list or a binary.
1638 Typical error reasons:
1640 einval:
1642 Name does not refer to a symbolic link.
1643 enoent:
1645 The file does not exist.
1646 enotsup:
1648 Symbolic links are not supported on this platform.
1649 read_link_info(Name) -> {ok, FileInfo} | {error, Reason}
1651 read_link_info(Name, Opts) -> {ok, FileInfo} | {error, Reason}
1653 Types:
1655 Name = name_all()
1657 Opts = [file_info_option()]
1658 FileInfo = file_info()
1659 Reason = posix() | badarg
1660 Works like read_file_info/1,2 except that if Name is a symbolic
1662 link, information about the link is returned in the file_info
1663 record and the type field of the record is set to symlink.
1664 If the option raw is set, the file server is not called and only
1666 information about local files is returned. Note that this will
1667 break this module's atomicity guarantees as it can race with a
1668 concurrent call to write_file_info/1,2
1669 If Name is not a symbolic link, this function returns the same
1671 result as read_file_info/1. On platforms that do not support
1672 symbolic links, this function is always equivalent to
1673 read_file_info/1.
1674 rename(Source, Destination) -> ok | {error, Reason}
1676 Types:
1678 Source = Destination = name_all()
1680 Reason = posix() | badarg
1681 Tries to rename the file Source to Destination. It can be used
1683 to move files (and directories) between directories, but it is
1684 not sufficient to specify the destination only. The destination
1685 filename must also be specified. For example, if bar is a normal
1686 file and foo and baz are directories, rename("foo/bar", "baz")
1687 returns an error, but rename("foo/bar", "baz/bar") succeeds. Re‐
1688 turns ok if it is successful.
1689 Note:
1691 Renaming of open files is not allowed on most platforms (see
1692 eacces below).
1693 Typical error reasons:
1696 eacces:
1698 Missing read or write permissions for the parent directories
1699 of Source or Destination. On some platforms, this error is
1700 given if either Source or Destination is open.
1701 eexist:
1703 Destination is not an empty directory. On some platforms,
1704 also given when Source and Destination are not of the same
1705 type.
1706 einval:
1708 Source is a root directory, or Destination is a subdirectory
1709 of Source.
1710 eisdir:
1712 Destination is a directory, but Source is not.
1713 enoent:
1715 Source does not exist.
1716 enotdir:
1718 Source is a directory, but Destination is not.
1719 exdev:
1721 Source and Destination are on different file systems.
1722 script(Filename) -> {ok, Value} | {error, Reason}
1724 Types:
1726 Filename = name_all()
1728 Value = term()
1729 Reason =
1730 posix() |
1731 badarg | terminated | system_limit |
1732 {Line :: integer(), Mod :: module(), Term :: term()}
1733 Reads and evaluates Erlang expressions, separated by '.' (or
1735 ',', a sequence of expressions is also an expression), from the
1736 file.
1737 Returns one of the following:
1739 {ok, Value}:
1741 The file is read and evaluated. Value is the value of the
1742 last expression.
1743 {error, atom()}:
1745 An error occurred when opening the file or reading it. For a
1746 list of typical error codes, see open/2.
1747 {error, {Line, Mod, Term}}:
1749 An error occurred when interpreting the Erlang expressions
1750 in the file. Use format_error/1 to convert the three-element
1751 tuple to an English description of the error.
1752 The encoding of Filename can be set by a comment as described in
1754 epp(3).
1755 script(Filename, Bindings) -> {ok, Value} | {error, Reason}
1757 Types:
1759 Filename = name_all()
1761 Bindings = erl_eval:binding_struct()
1762 Value = term()
1763 Reason =
1764 posix() |
1765 badarg | terminated | system_limit |
1766 {Line :: integer(), Mod :: module(), Term :: term()}
1767 The same as script/1 but the variable bindings Bindings are used
1769 in the evaluation. See erl_eval(3) about variable bindings.
1770 sendfile(Filename, Socket) ->
1772 {ok, integer() >= 0} |
1773 {error, inet:posix() | closed | badarg | not_owner}
1774 Types:
1776 Filename = name_all()
1778 Socket =
1779 inet:socket() |
1780 socket:socket() |
1781 fun((iolist()) -> ok | {error, inet:posix() | closed})
1782 Sends the file Filename to Socket. Returns {ok, BytesSent} if
1784 successful, otherwise {error, Reason}.
1785 sendfile(RawFile, Socket, Offset, Bytes, Opts) ->
1787 {ok, integer() >= 0} |
1788 {error, inet:posix() | closed | badarg | not_owner}
1789 Types:
1791 RawFile = fd()
1793 Socket =
1794 inet:socket() |
1795 socket:socket() |
1796 fun((iolist()) -> ok | {error, inet:posix() | closed})
1797 Offset = Bytes = integer() >= 0
1798 Opts = [sendfile_option()]
1799 sendfile_option() =
1800 {chunk_size, integer() >= 0} | {use_threads, boolean()}
1801 Sends Bytes from the file referenced by RawFile beginning at
1803 Offset to Socket. Returns {ok, BytesSent} if successful, other‐
1804 wise {error, Reason}. If Bytes is set to 0 all data after the
1805 specified Offset is sent.
1806 The file used must be opened using the raw flag, and the process
1808 calling sendfile must be the controlling process of the socket.
1809 See gen_tcp:controlling_process/2 or module socket's level otp
1810 socket option controlling_process.
1811 If the OS used does not support non-blocking sendfile, an Erlang
1813 fallback using read/2 and gen_tcp:send/2 is used.
1814 The option list can contain the following options:
1816 chunk_size:
1818 The chunk size used by the Erlang fallback to send data. If
1819 using the fallback, set this to a value that comfortably
1820 fits in the systems memory. Default is 20 MB.
1821 set_cwd(Dir) -> ok | {error, Reason}
1823 Types:
1825 Dir = name() | EncodedBinary
1827 EncodedBinary = binary()
1828 Reason = posix() | badarg | no_translation
1829 Sets the current working directory of the file server to Dir.
1831 Returns ok if successful.
1832 The functions in the module file usually treat binaries as raw
1834 filenames, that is, they are passed "as is" even when the encod‐
1835 ing of the binary does not agree with native_name_encoding().
1836 However, this function expects binaries to be encoded according
1837 to the value returned by native_name_encoding().
1838 Typical error reasons are:
1840 enoent:
1842 The directory does not exist.
1843 enotdir:
1845 A component of Dir is not a directory. On some platforms,
1846 enoent is returned.
1847 eacces:
1849 Missing permission for the directory or one of its parents.
1850 badarg:
1852 Dir has an improper type, such as tuple.
1853 no_translation:
1855 Dir is a binary() with characters coded in ISO-latin-1 and
1856 the VM is operating with unicode filename encoding.
1857 Warning:
1859 In a future release, a bad type for argument Dir will probably
1860 generate an exception.
1861 sync(IoDevice) -> ok | {error, Reason}
1864 Types:
1866 IoDevice = io_device()
1868 Reason = posix() | badarg | terminated
1869 Ensures that any buffers kept by the operating system (not by
1871 the Erlang runtime system) are written to disk. On some plat‐
1872 forms, this function might have no effect.
1873 A typical error reason is:
1875 enospc:
1877 Not enough space left to write the file.
1878 truncate(IoDevice) -> ok | {error, Reason}
1880 Types:
1882 IoDevice = io_device()
1884 Reason = posix() | badarg | terminated
1885 Truncates the file referenced by IoDevice at the current posi‐
1887 tion. Returns ok if successful, otherwise {error, Reason}.
1888 write(IoDevice, Bytes) -> ok | {error, Reason}
1890 Types:
1892 IoDevice = io_device() | atom()
1894 Bytes = iodata()
1895 Reason = posix() | badarg | terminated
1896 Writes Bytes to the file referenced by IoDevice. This function
1898 is the only way to write to a file opened in raw mode (although
1899 it works for normally opened files too). Returns ok if success‐
1900 ful, and {error, Reason} otherwise.
1901 If the file is opened with encoding set to something else than
1903 latin1, each byte written can result in many bytes being written
1904 to the file, as the byte range 0..255 can represent anything be‐
1905 tween one and four bytes depending on value and UTF encoding
1906 type.
1907 Typical error reasons:
1909 ebadf:
1911 The file is not opened for writing.
1912 enospc:
1914 No space is left on the device.
1915 write_file(Filename, Bytes) -> ok | {error, Reason}
1917 Types:
1919 Filename = name_all()
1921 Bytes = iodata()
1922 Reason = posix() | badarg | terminated | system_limit
1923 Writes the contents of the iodata term Bytes to file Filename.
1925 The file is created if it does not exist. If it exists, the pre‐
1926 vious contents are overwritten. Returns ok if successful, other‐
1927 wise {error, Reason}.
1928 Typical error reasons:
1930 enoent:
1932 A component of the filename does not exist.
1933 enotdir:
1935 A component of the filename is not a directory. On some
1936 platforms, enoent is returned instead.
1937 enospc:
1939 No space is left on the device.
1940 eacces:
1942 Missing permission for writing the file or searching one of
1943 the parent directories.
1944 eisdir:
1946 The named file is a directory.
1947 write_file(Filename, Bytes, Modes) -> ok | {error, Reason}
1949 Types:
1951 Filename = name_all()
1953 Bytes = iodata()
1954 Modes = [mode()]
1955 Reason = posix() | badarg | terminated | system_limit
1956 Same as write_file/2, but takes a third argument Modes, a list
1958 of possible modes, see open/2. The mode flags binary and write
1959 are implicit, so they are not to be used.
1960 write_file_info(Filename, FileInfo) -> ok | {error, Reason}
1962 write_file_info(Filename, FileInfo, Opts) -> ok | {error, Reason}
1964 Types:
1966 Filename = name_all()
1968 Opts = [file_info_option()]
1969 FileInfo = file_info()
1970 Reason = posix() | badarg
1971 Changes file information. Returns ok if successful, otherwise
1973 {error, Reason}. FileInfo is a record file_info, defined in the
1974 Kernel include file file.hrl. Include the following directive in
1975 the module from which the function is called:
1976 -include_lib("kernel/include/file.hrl").
1978 The time type set in atime, mtime, and ctime depends on the time
1980 type set in Opts :: {time, Type} as follows:
1981 local:
1983 Interprets the time set as local.
1984 universal:
1986 Interprets it as universal time.
1987 posix:
1989 Must be seconds since or before Unix time epoch, which is
1990 1970-01-01 00:00 UTC.
1991 Default is {time, local}.
1993 If the option raw is set, the file server is not called and only
1995 information about local files is returned.
1996 The following fields are used from the record, if they are spec‐
1998 ified:
1999 atime = date_time() | integer() >= 0:
2001 The last time the file was read.
2002 mtime = date_time() | integer() >= 0:
2004 The last time the file was written.
2005 ctime = date_time() | integer() >= 0:
2007 On Unix, any value specified for this field is ignored (the
2008 "ctime" for the file is set to the current time). On Win‐
2009 dows, this field is the new creation time to set for the
2010 file.
2011 mode = integer() >= 0:
2013 The file permissions as the sum of the following bit values:
2014 8#00400:
2016 Read permission: owner
2017 8#00200:
2019 Write permission: owner
2020 8#00100:
2022 Execute permission: owner
2023 8#00040:
2025 Read permission: group
2026 8#00020:
2028 Write permission: group
2029 8#00010:
2031 Execute permission: group
2032 8#00004:
2034 Read permission: other
2035 8#00002:
2037 Write permission: other
2038 8#00001:
2040 Execute permission: other
2041 16#800:
2043 Set user id on execution
2044 16#400:
2046 Set group id on execution
2047 On Unix platforms, other bits than those listed above may be
2049 set.
2050 uid = integer() >= 0:
2052 Indicates the file owner. Ignored for non-Unix file systems.
2053 gid = integer() >= 0:
2055 Gives the group that the file owner belongs to. Ignored for
2056 non-Unix file systems.
2057 Typical error reasons:
2059 eacces:
2061 Missing search permission for one of the parent directories
2062 of the file.
2063 enoent:
2065 The file does not exist.
2066 enotdir:
2068 A component of the filename is not a directory. On some
2069 platforms, enoent is returned instead.
2070
2072 * eacces - Permission denied
2073 * eagain - Resource temporarily unavailable
2075 * ebadf - Bad file number
2077 * ebusy - File busy
2079 * edquot - Disk quota exceeded
2081 * eexist - File already exists
2083 * efault - Bad address in system call argument
2085 * efbig - File too large
2087 * eintr - Interrupted system call
2089 * einval - Invalid argument
2091 * eio - I/O error
2093 * eisdir - Illegal operation on a directory
2095 * eloop - Too many levels of symbolic links
2097 * emfile - Too many open files
2099 * emlink - Too many links
2101 * enametoolong - Filename too long
2103 * enfile - File table overflow
2105 * enodev - No such device
2107 * enoent - No such file or directory
2109 * enomem - Not enough memory
2111 * enospc - No space left on device
2113 * enotblk - Block device required
2115 * enotdir - Not a directory
2117 * enotsup - Operation not supported
2119 * enxio - No such device or address
2121 * eperm - Not owner
2123 * epipe - Broken pipe
2125 * erofs - Read-only file system
2127 * espipe - Invalid seek
2129 * esrch - No such process
2131 * estale - Stale remote file handle
2133 * exdev - Cross-domain link
2135
2137 For increased performance, raw files are recommended.
2138 A normal file is really a process so it can be used as an I/O device
2140 (see io). Therefore, when data is written to a normal file, the sending
2141 of the data to the file process, copies all data that are not binaries.
2142 Opening the file in binary mode and writing binaries is therefore rec‐
2143 ommended. If the file is opened on another node, or if the file server
2144 runs as slave to the file server of another node, also binaries are
2145 copied.
2146 Note:
2148 Raw files use the file system of the host machine of the node. For nor‐
2149 mal files (non-raw), the file server is used to find the files, and if
2150 the node is running its file server as slave to the file server of an‐
2151 other node, and the other node runs on some other host machine, they
2152 can have different file systems. However, this is seldom a problem.
2153 open/2 can be given the options delayed_write and read_ahead to turn on
2156 caching, which will reduce the number of operating system calls and
2157 greatly improve performance for small reads and writes. However, the
2158 overhead won't disappear completely and it's best to keep the number of
2159 file operations to a minimum. As a contrived example, the following
2160 function writes 4MB in 2.5 seconds when tested:
2161 create_file_slow(Name) ->
2163 {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2164 create_file_slow_1(Fd, 4 bsl 20),
2165 file:close(Fd).
2166 create_file_slow_1(_Fd, 0) ->
2168 ok;
2169 create_file_slow_1(Fd, M) ->
2170 ok = file:write(Fd, <<0>>),
2171 create_file_slow_1(Fd, M - 1).
2172 The following functionally equivalent code writes 128 bytes per call to
2174 write/2 and so does the same work in 0.08 seconds, which is roughly 30
2175 times faster:
2176 create_file(Name) ->
2178 {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2179 create_file_1(Fd, 4 bsl 20),
2180 file:close(Fd),
2181 ok.
2182 create_file_1(_Fd, 0) ->
2184 ok;
2185 create_file_1(Fd, M) when M >= 128 ->
2186 ok = file:write(Fd, <<0:(128)/unit:8>>),
2187 create_file_1(Fd, M - 128);
2188 create_file_1(Fd, M) ->
2189 ok = file:write(Fd, <<0:(M)/unit:8>>),
2190 create_file_1(Fd, M - 1).
2191 When writing data it's generally more efficient to write a list of bi‐
2193 naries rather than a list of integers. It is not needed to flatten a
2194 deep list before writing. On Unix hosts, scatter output, which writes a
2195 set of buffers in one operation, is used when possible. In this way
2196 write(FD, [Bin1, Bin2 | Bin3]) writes the contents of the binaries
2197 without copying the data at all, except for perhaps deep down in the
2198 operating system kernel.
2199 Warning:
2201 If an error occurs when accessing an open file with module io, the
2202 process handling the file exits. The dead file process can hang if a
2203 process tries to access it later. This will be fixed in a future re‐
2204 lease.
2205
2208 filename(3)
2209Ericsson AB kernel 8.5.3 file(3)