1file(3) Erlang Module Definition file(3)
2
6 file - File interface module.
7
9 This module provides an interface to the file system.
10 Warning:
12 File operations are only guaranteed to appear atomic when going through
13 the same file server. A NIF or other OS process may observe intermedi‐
14 ate steps on certain operations on some operating systems, eg. renaming
15 an existing file on Windows, or write_file_info/2 on any OS at the time
16 of writing.
17 Regarding filename encoding, the Erlang VM can operate in two modes.
20 The current mode can be queried using function native_name_encoding/0.
21 It returns latin1 or utf8.
22 In latin1 mode, the Erlang VM does not change the encoding of file‐
24 names. In utf8 mode, filenames can contain Unicode characters greater
25 than 255 and the VM converts filenames back and forth to the native
26 filename encoding (usually UTF-8, but UTF-16 on Windows).
27 The default mode depends on the operating system. Windows and MacOS X
29 enforce consistent filename encoding and therefore the VM uses utf8
30 mode.
31 On operating systems with transparent naming (for example, all Unix
33 systems except MacOS X), default is utf8 if the terminal supports
34 UTF-8, otherwise latin1. The default can be overridden using +fnl (to
35 force latin1 mode) or +fnu (to force utf8 mode) when starting erl.
36 On operating systems with transparent naming, files can be inconsis‐
38 tently named, for example, some files are encoded in UTF-8 while others
39 are encoded in ISO Latin-1. The concept of raw filenames is introduced
40 to handle file systems with inconsistent naming when running in utf8
41 mode.
42 A raw filename is a filename specified as a binary. The Erlang VM does
44 not translate a filename specified as a binary on systems with trans‐
45 parent naming.
46 When running in utf8 mode, functions list_dir/1 and read_link/1 never
48 return raw filenames. To return all filenames including raw filenames,
49 use functions list_dir_all/1 and read_link_all/1.
50 See also section Notes About Raw Filenames in the STDLIB User's Guide.
52 Note:
54 File operations used to accept filenames containing null characters
55 (integer value zero). This caused the name to be truncated and in some
56 cases arguments to primitive operations to be mixed up. Filenames con‐
57 taining null characters inside the filename are now rejected and will
58 cause primitive file operations fail.
59
62 deep_list() = [char() | atom() | deep_list()]
63 fd()
65 A file descriptor representing a file opened in raw mode.
67 filename() = string()
69 See also the documentation of the name_all() type.
71 filename_all() = string() | binary()
73 See also the documentation of the name_all() type.
75 io_device() = pid() | fd()
77 As returned by open/2; pid() is a process handling I/O-proto‐
79 cols.
80 name() = string() | atom() | deep_list()
82 If VM is in Unicode filename mode, string() and char() are
84 allowed to be > 255. See also the documentation of the
85 name_all() type.
86 name_all() =
88 string() | atom() | deep_list() | (RawFilename :: binary())
89 If VM is in Unicode filename mode, characters are allowed to be
91 > 255. RawFilename is a filename not subject to Unicode transla‐
92 tion, meaning that it can contain characters not conforming to
93 the Unicode encoding expected from the file system (that is,
94 non-UTF-8 characters although the VM is started in Unicode file‐
95 name mode). Null characters (integer value zero) are not allowed
96 in filenames (not even at the end).
97 posix() =
99 eacces | eagain | ebadf | ebadmsg | ebusy | edeadlk |
100 edeadlock | edquot | eexist | efault | efbig | eftype |
101 eintr | einval | eio | eisdir | eloop | emfile | emlink |
102 emultihop | enametoolong | enfile | enobufs | enodev |
103 enolck | enolink | enoent | enomem | enospc | enosr | enostr |
104 enosys | enotblk | enotdir | enotsup | enxio | eopnotsupp |
105 eoverflow | eperm | epipe | erange | erofs | espipe | esrch |
106 estale | etxtbsy | exdev
107 An atom that is named from the POSIX error codes used in Unix,
109 and in the runtime libraries of most C compilers.
110 date_time() = calendar:datetime()
112 Must denote a valid date and time.
114 file_info() =
116 #file_info{size = integer() >= 0 | undefined,
117 type =
118 device | directory | other | regular |
119 symlink | undefined,
120 access =
121 read | write | read_write | none | undefined,
122 atime =
123 file:date_time() |
124 integer() >= 0 |
125 undefined,
126 mtime =
127 file:date_time() |
128 integer() >= 0 |
129 undefined,
130 ctime =
131 file:date_time() |
132 integer() >= 0 |
133 undefined,
134 mode = integer() >= 0 | undefined,
135 links = integer() >= 0 | undefined,
136 major_device = integer() >= 0 | undefined,
137 minor_device = integer() >= 0 | undefined,
138 inode = integer() >= 0 | undefined,
139 uid = integer() >= 0 | undefined,
140 gid = integer() >= 0 | undefined}
141 location() =
143 integer() |
144 {bof, Offset :: integer()} |
145 {cur, Offset :: integer()} |
146 {eof, Offset :: integer()} |
147 bof | cur | eof
148 mode() =
150 read | write | append | exclusive | raw | binary |
151 {delayed_write,
152 Size :: integer() >= 0,
153 Delay :: integer() >= 0} |
154 delayed_write |
155 {read_ahead, Size :: integer() >= 1} |
156 read_ahead | compressed |
157 {encoding, unicode:encoding()} |
158 sync
159 file_info_option() =
161 {time, local} | {time, universal} | {time, posix} | raw
162
164 advise(IoDevice, Offset, Length, Advise) -> ok | {error, Reason}
165 Types:
167 IoDevice = io_device()
169 Offset = Length = integer()
170 Advise = posix_file_advise()
171 Reason = posix() | badarg
172 posix_file_advise() =
173 normal | sequential | random | no_reuse | will_need |
174 dont_need
175 advise/4 can be used to announce an intention to access file
177 data in a specific pattern in the future, thus allowing the
178 operating system to perform appropriate optimizations.
179 On some platforms, this function might have no effect.
181 allocate(File, Offset, Length) -> ok | {error, posix()}
183 Types:
185 File = io_device()
187 Offset = Length = integer() >= 0
188 allocate/3 can be used to preallocate space for a file.
190 This function only succeeds in platforms that provide this fea‐
192 ture. When it succeeds, space is preallocated for the file but
193 the file size might not be updated. This behaviour depends on
194 the preallocation implementation. To guarantee that the file
195 size is updated, truncate the file to the new size.
196 change_group(Filename, Gid) -> ok | {error, Reason}
198 Types:
200 Filename = name_all()
202 Gid = integer()
203 Reason = posix() | badarg
204 Changes group of a file. See write_file_info/2.
206 change_mode(Filename, Mode) -> ok | {error, Reason}
208 Types:
210 Filename = name_all()
212 Mode = integer()
213 Reason = posix() | badarg
214 Changes permissions of a file. See write_file_info/2.
216 change_owner(Filename, Uid) -> ok | {error, Reason}
218 Types:
220 Filename = name_all()
222 Uid = integer()
223 Reason = posix() | badarg
224 Changes owner of a file. See write_file_info/2.
226 change_owner(Filename, Uid, Gid) -> ok | {error, Reason}
228 Types:
230 Filename = name_all()
232 Uid = Gid = integer()
233 Reason = posix() | badarg
234 Changes owner and group of a file. See write_file_info/2.
236 change_time(Filename, Mtime) -> ok | {error, Reason}
238 Types:
240 Filename = name_all()
242 Mtime = date_time()
243 Reason = posix() | badarg
244 Changes the modification and access times of a file. See
246 write_file_info/2.
247 change_time(Filename, Atime, Mtime) -> ok | {error, Reason}
249 Types:
251 Filename = name_all()
253 Atime = Mtime = date_time()
254 Reason = posix() | badarg
255 Changes the modification and last access times of a file. See
257 write_file_info/2.
258 close(IoDevice) -> ok | {error, Reason}
260 Types:
262 IoDevice = io_device()
264 Reason = posix() | badarg | terminated
265 Closes the file referenced by IoDevice. It mostly returns ok,
267 except for some severe errors such as out of memory.
268 Notice that if option delayed_write was used when opening the
270 file, close/1 can return an old write error and not even try to
271 close the file. See open/2.
272 consult(Filename) -> {ok, Terms} | {error, Reason}
274 Types:
276 Filename = name_all()
278 Terms = [term()]
279 Reason =
280 posix() |
281 badarg | terminated | system_limit |
282 {Line :: integer(), Mod :: module(), Term :: term()}
283 Reads Erlang terms, separated by '.', from Filename. Returns one
285 of the following:
286 {ok, Terms}:
288 The file was successfully read.
289 {error, atom()}:
291 An error occurred when opening the file or reading it. For a
292 list of typical error codes, see open/2.
293 {error, {Line, Mod, Term}}:
295 An error occurred when interpreting the Erlang terms in the
296 file. To convert the three-element tuple to an English
297 description of the error, use format_error/1.
298 Example:
300 f.txt: {person, "kalle", 25}.
302 {person, "pelle", 30}.
303 1> file:consult("f.txt").
305 {ok,[{person,"kalle",25},{person,"pelle",30}]}
306 The encoding of Filename can be set by a comment, as described
308 in epp(3).
309 copy(Source, Destination) -> {ok, BytesCopied} | {error, Reason}
311 copy(Source, Destination, ByteCount) ->
313 {ok, BytesCopied} | {error, Reason}
314 Types:
316 Source = Destination = io_device() | Filename | {Filename,
318 Modes}
319 Filename = name_all()
320 Modes = [mode()]
321 ByteCount = integer() >= 0 | infinity
322 BytesCopied = integer() >= 0
323 Reason = posix() | badarg | terminated
324 Copies ByteCount bytes from Source to Destination. Source and
326 Destination refer to either filenames or IO devices from, for
327 example, open/2. ByteCount defaults to infinity, denoting an
328 infinite number of bytes.
329 Argument Modes is a list of possible modes, see open/2, and
331 defaults to [].
332 If both Source and Destination refer to filenames, the files are
334 opened with [read, binary] and [write, binary] prepended to
335 their mode lists, respectively, to optimize the copy.
336 If Source refers to a filename, it is opened with read mode
338 prepended to the mode list before the copy, and closed when
339 done.
340 If Destination refers to a filename, it is opened with write
342 mode prepended to the mode list before the copy, and closed when
343 done.
344 Returns {ok, BytesCopied}, where BytesCopied is the number of
346 bytes that was copied, which can be less than ByteCount if end
347 of file was encountered on the source. If the operation fails,
348 {error, Reason} is returned.
349 Typical error reasons: as for open/2 if a file had to be opened,
351 and as for read/2 and write/2.
352 datasync(IoDevice) -> ok | {error, Reason}
354 Types:
356 IoDevice = io_device()
358 Reason = posix() | badarg | terminated
359 Ensures that any buffers kept by the operating system (not by
361 the Erlang runtime system) are written to disk. In many ways it
362 resembles fsync but it does not update some of the metadata of
363 the file, such as the access time. On some platforms this func‐
364 tion has no effect.
365 Applications that access databases or log files often write a
367 tiny data fragment (for example, one line in a log file) and
368 then call fsync() immediately to ensure that the written data is
369 physically stored on the hard disk. Unfortunately, fsync()
370 always initiates two write operations: one for the newly written
371 data and another one to update the modification time stored in
372 the inode. If the modification time is not a part of the trans‐
373 action concept, fdatasync() can be used to avoid unnecessary
374 inode disk write operations.
375 Available only in some POSIX systems, this call results in a
377 call to fsync(), or has no effect in systems not providing the
378 fdatasync() syscall.
379 del_dir(Dir) -> ok | {error, Reason}
381 Types:
383 Dir = name_all()
385 Reason = posix() | badarg
386 Tries to delete directory Dir. The directory must be empty
388 before it can be deleted. Returns ok if successful.
389 Typical error reasons:
391 eacces:
393 Missing search or write permissions for the parent directo‐
394 ries of Dir.
395 eexist:
397 The directory is not empty.
398 enoent:
400 The directory does not exist.
401 enotdir:
403 A component of Dir is not a directory. On some platforms,
404 enoent is returned instead.
405 einval:
407 Attempt to delete the current directory. On some platforms,
408 eacces is returned instead.
409 delete(Filename) -> ok | {error, Reason}
411 Types:
413 Filename = name_all()
415 Reason = posix() | badarg
416 Tries to delete file Filename. Returns ok if successful.
418 Typical error reasons:
420 enoent:
422 The file does not exist.
423 eacces:
425 Missing permission for the file or one of its parents.
426 eperm:
428 The file is a directory and the user is not superuser.
429 enotdir:
431 A component of the filename is not a directory. On some
432 platforms, enoent is returned instead.
433 einval:
435 Filename has an improper type, such as tuple.
436 Warning:
438 In a future release, a bad type for argument Filename will prob‐
439 ably generate an exception.
440 eval(Filename) -> ok | {error, Reason}
443 Types:
445 Filename = name_all()
447 Reason =
448 posix() |
449 badarg | terminated | system_limit |
450 {Line :: integer(), Mod :: module(), Term :: term()}
451 Reads and evaluates Erlang expressions, separated by '.' (or
453 ',', a sequence of expressions is also an expression) from File‐
454 name. The result of the evaluation is not returned; any expres‐
455 sion sequence in the file must be there for its side effect.
456 Returns one of the following:
457 ok:
459 The file was read and evaluated.
460 {error, atom()}:
462 An error occurred when opening the file or reading it. For a
463 list of typical error codes, see open/2.
464 {error, {Line, Mod, Term}}:
466 An error occurred when interpreting the Erlang expressions
467 in the file. To convert the three-element tuple to an Eng‐
468 lish description of the error, use format_error/1.
469 The encoding of Filename can be set by a comment, as described
471 in epp(3).
472 eval(Filename, Bindings) -> ok | {error, Reason}
474 Types:
476 Filename = name_all()
478 Bindings = erl_eval:binding_struct()
479 Reason =
480 posix() |
481 badarg | terminated | system_limit |
482 {Line :: integer(), Mod :: module(), Term :: term()}
483 The same as eval/1, but the variable bindings Bindings are used
485 in the evaluation. For information about the variable bindings,
486 see erl_eval(3).
487 format_error(Reason) -> Chars
489 Types:
491 Reason =
493 posix() |
494 badarg | terminated | system_limit |
495 {Line :: integer(), Mod :: module(), Term :: term()}
496 Chars = string()
497 Given the error reason returned by any function in this module,
499 returns a descriptive string of the error in English.
500 get_cwd() -> {ok, Dir} | {error, Reason}
502 Types:
504 Dir = filename()
506 Reason = posix()
507 Returns {ok, Dir}, where Dir is the current working directory of
509 the file server.
510 Note:
512 In rare circumstances, this function can fail on Unix. It can
513 occur if read permission does not exist for the parent directo‐
514 ries of the current directory.
515 A typical error reason:
518 eacces:
520 Missing read permission for one of the parents of the cur‐
521 rent directory.
522 get_cwd(Drive) -> {ok, Dir} | {error, Reason}
524 Types:
526 Drive = string()
528 Dir = filename()
529 Reason = posix() | badarg
530 Returns {ok, Dir} or {error, Reason}, where Dir is the current
532 working directory of the specified drive.
533 Drive is to be of the form "Letter:", for example, "c:".
535 Returns {error, enotsup} on platforms that have no concept of
537 current drive (Unix, for example).
538 Typical error reasons:
540 enotsup:
542 The operating system has no concept of drives.
543 eacces:
545 The drive does not exist.
546 einval:
548 The format of Drive is invalid.
549 list_dir(Dir) -> {ok, Filenames} | {error, Reason}
551 Types:
553 Dir = name_all()
555 Filenames = [filename()]
556 Reason =
557 posix() |
558 badarg |
559 {no_translation, Filename :: unicode:latin1_binary()}
560 Lists all files in a directory, except files with raw filenames.
562 Returns {ok, Filenames} if successful, otherwise {error, Rea‐
563 son}. Filenames is a list of the names of all the files in the
564 directory. The names are not sorted.
565 Typical error reasons:
567 eacces:
569 Missing search or write permissions for Dir or one of its
570 parent directories.
571 enoent:
573 The directory does not exist.
574 {no_translation, Filename}:
576 Filename is a binary() with characters coded in ISO Latin-1
577 and the VM was started with parameter +fnue.
578 list_dir_all(Dir) -> {ok, Filenames} | {error, Reason}
580 Types:
582 Dir = name_all()
584 Filenames = [filename_all()]
585 Reason = posix() | badarg
586 Lists all the files in a directory, including files with raw
588 filenames. Returns {ok, Filenames} if successful, otherwise
589 {error, Reason}. Filenames is a list of the names of all the
590 files in the directory. The names are not sorted.
591 Typical error reasons:
593 eacces:
595 Missing search or write permissions for Dir or one of its
596 parent directories.
597 enoent:
599 The directory does not exist.
600 make_dir(Dir) -> ok | {error, Reason}
602 Types:
604 Dir = name_all()
606 Reason = posix() | badarg
607 Tries to create directory Dir. Missing parent directories are
609 not created. Returns ok if successful.
610 Typical error reasons:
612 eacces:
614 Missing search or write permissions for the parent directo‐
615 ries of Dir.
616 eexist:
618 A file or directory named Dir exists already.
619 enoent:
621 A component of Dir does not exist.
622 enospc:
624 No space is left on the device.
625 enotdir:
627 A component of Dir is not a directory. On some platforms,
628 enoent is returned instead.
629 make_link(Existing, New) -> ok | {error, Reason}
631 Types:
633 Existing = New = name_all()
635 Reason = posix() | badarg
636 Makes a hard link from Existing to New on platforms supporting
638 links (Unix and Windows). This function returns ok if the link
639 was successfully created, otherwise {error, Reason}. On plat‐
640 forms not supporting links, {error,enotsup} is returned.
641 Typical error reasons:
643 eacces:
645 Missing read or write permissions for the parent directories
646 of Existing or New.
647 eexist:
649 New already exists.
650 enotsup:
652 Hard links are not supported on this platform.
653 make_symlink(Existing, New) -> ok | {error, Reason}
655 Types:
657 Existing = New = name_all()
659 Reason = posix() | badarg
660 Creates a symbolic link New to the file or directory Existing on
662 platforms supporting symbolic links (most Unix systems and Win‐
663 dows, beginning with Vista). Existing does not need to exist.
664 Returns ok if the link is successfully created, otherwise
665 {error, Reason}. On platforms not supporting symbolic links,
666 {error, enotsup} is returned.
667 Typical error reasons:
669 eacces:
671 Missing read or write permissions for the parent directories
672 of Existing or New.
673 eexist:
675 New already exists.
676 enotsup:
678 Symbolic links are not supported on this platform.
679 eperm:
681 User does not have privileges to create symbolic links
682 (SeCreateSymbolicLinkPrivilege on Windows).
683 native_name_encoding() -> latin1 | utf8
685 Returns the filename encoding mode. If it is latin1, the system
687 translates no filenames. If it is utf8, filenames are converted
688 back and forth to the native filename encoding (usually UTF-8,
689 but UTF-16 on Windows).
690 open(File, Modes) -> {ok, IoDevice} | {error, Reason}
692 Types:
694 File = Filename | iodata()
696 Filename = name_all()
697 Modes = [mode() | ram]
698 IoDevice = io_device()
699 Reason = posix() | badarg | system_limit
700 Opens file File in the mode determined by Modes, which can con‐
702 tain one or more of the following options:
703 read:
705 The file, which must exist, is opened for reading.
706 write:
708 The file is opened for writing. It is created if it does not
709 exist. If the file exists and write is not combined with
710 read, the file is truncated.
711 append:
713 The file is opened for writing. It is created if it does not
714 exist. Every write operation to a file opened with append
715 takes place at the end of the file.
716 exclusive:
718 The file is opened for writing. It is created if it does not
719 exist. If the file exists, {error, eexist} is returned.
720 Warning:
722 This option does not guarantee exclusiveness on file systems
723 not supporting O_EXCL properly, such as NFS. Do not depend on
724 this option unless you know that the file system supports it
725 (in general, local file systems are safe).
726 raw:
729 Allows faster access to a file, as no Erlang process is
730 needed to handle the file. However, a file opened in this
731 way has the following limitations:
732 * The functions in the io module cannot be used, as they can
734 only talk to an Erlang process. Instead, use functions
735 read/2, read_line/1, and write/2.
736 * Especially if read_line/1 is to be used on a raw file, it
738 is recommended to combine this option with option
739 {read_ahead, Size} as line-oriented I/O is inefficient
740 without buffering.
741 * Only the Erlang process that opened the file can use it.
743 * A remote Erlang file server cannot be used. The computer
745 on which the Erlang node is running must have access to
746 the file system (directly or through NFS).
747 binary:
749 Read operations on the file return binaries rather than
750 lists.
751 {delayed_write, Size, Delay}:
753 Data in subsequent write/2 calls is buffered until at least
754 Size bytes are buffered, or until the oldest buffered data
755 is Delay milliseconds old. Then all buffered data is written
756 in one operating system call. The buffered data is also
757 flushed before some other file operation than write/2 is
758 executed.
759 The purpose of this option is to increase performance by
761 reducing the number of operating system calls. Thus, the
762 write/2 calls must be for sizes significantly less than
763 Size, and not interspersed by too many other file opera‐
764 tions.
765 When this option is used, the result of write/2 calls can
767 prematurely be reported as successful, and if a write error
768 occurs, the error is reported as the result of the next file
769 operation, which is not executed.
770 For example, when delayed_write is used, after a number of
772 write/2 calls, close/1 can return {error, enospc}, as there
773 is not enough space on the disc for previously written data.
774 close/1 must probably be called again, as the file is still
775 open.
776 delayed_write:
778 The same as {delayed_write, Size, Delay} with reasonable
779 default values for Size and Delay (roughly some 64 KB, 2
780 seconds).
781 {read_ahead, Size}:
783 Activates read data buffering. If read/2 calls are for sig‐
784 nificantly less than Size bytes, read operations to the
785 operating system are still performed for blocks of Size
786 bytes. The extra data is buffered and returned in subsequent
787 read/2 calls, giving a performance gain as the number of
788 operating system calls is reduced.
789 The read_ahead buffer is also highly used by function
791 read_line/1 in raw mode, therefore this option is recom‐
792 mended (for performance reasons) when accessing raw files
793 using that function.
794 If read/2 calls are for sizes not significantly less than,
796 or even greater than Size bytes, no performance gain can be
797 expected.
798 read_ahead:
800 The same as {read_ahead, Size} with a reasonable default
801 value for Size (roughly some 64 KB).
802 compressed:
804 Makes it possible to read or write gzip compressed files.
805 Option compressed must be combined with read or write, but
806 not both. Notice that the file size obtained with
807 read_file_info/1 does probably not match the number of bytes
808 that can be read from a compressed file.
809 {encoding, Encoding}:
811 Makes the file perform automatic translation of characters
812 to and from a specific (Unicode) encoding. Notice that the
813 data supplied to write/2 or returned by read/2 still is
814 byte-oriented; this option denotes only how data is stored
815 in the disk file.
816 Depending on the encoding, different methods of reading and
818 writing data is preferred. The default encoding of latin1
819 implies using this module (file) for reading and writing
820 data as the interfaces provided here work with byte-oriented
821 data. Using other (Unicode) encodings makes the io(3) func‐
822 tions get_chars, get_line, and put_chars more suitable, as
823 they can work with the full Unicode range.
824 If data is sent to an io_device() in a format that cannot be
826 converted to the specified encoding, or if data is read by a
827 function that returns data in a format that cannot cope with
828 the character range of the data, an error occurs and the
829 file is closed.
830 Allowed values for Encoding:
832 latin1:
834 The default encoding. Bytes supplied to the file, that is,
835 write/2 are written "as is" on the file. Likewise, bytes
836 read from the file, that is, read/2 are returned "as is".
837 If module io(3) is used for writing, the file can only
838 cope with Unicode characters up to code point 255 (the ISO
839 Latin-1 range).
840 unicode or utf8:
842 Characters are translated to and from UTF-8 encoding
843 before they are written to or read from the file. A file
844 opened in this way can be readable using function read/2,
845 as long as no data stored on the file lies beyond the ISO
846 Latin-1 range (0..255), but failure occurs if the data
847 contains Unicode code points beyond that range. The file
848 is best read with the functions in the Unicode aware mod‐
849 ule io(3).
850 Bytes written to the file by any means are translated to
852 UTF-8 encoding before being stored on the disk file.
853 utf16 or {utf16,big}:
855 Works like unicode, but translation is done to and from
856 big endian UTF-16 instead of UTF-8.
857 {utf16,little}:
859 Works like unicode, but translation is done to and from
860 little endian UTF-16 instead of UTF-8.
861 utf32 or {utf32,big}:
863 Works like unicode, but translation is done to and from
864 big endian UTF-32 instead of UTF-8.
865 {utf32,little}:
867 Works like unicode, but translation is done to and from
868 little endian UTF-32 instead of UTF-8.
869 The Encoding can be changed for a file "on the fly" by using
871 function io:setopts/2. So a file can be analyzed in latin1
872 encoding for, for example, a BOM, positioned beyond the BOM
873 and then be set for the right encoding before further read‐
874 ing. For functions identifying BOMs, see module unicode(3).
875 This option is not allowed on raw files.
877 ram:
879 File must be iodata(). Returns an fd(), which lets module
880 file operate on the data in-memory as if it is a file.
881 sync:
883 On platforms supporting it, enables the POSIX O_SYNC syn‐
884 chronous I/O flag or its platform-dependent equivalent (for
885 example, FILE_FLAG_WRITE_THROUGH on Windows) so that writes
886 to the file block until the data is physically written to
887 disk. However, be aware that the exact semantics of this
888 flag differ from platform to platform. For example, none of
889 Linux or Windows guarantees that all file metadata are also
890 written before the call returns. For precise semantics,
891 check the details of your platform documentation. On plat‐
892 forms with no support for POSIX O_SYNC or equivalent, use of
893 the sync flag causes open to return {error, enotsup}.
894 Returns:
896 {ok, IoDevice}:
898 The file is opened in the requested mode. IoDevice is a ref‐
899 erence to the file.
900 {error, Reason}:
902 The file cannot be opened.
903 IoDevice is really the pid of the process that handles the file.
905 This process is linked to the process that originally opened the
906 file. If any process to which the IoDevice is linked terminates,
907 the file is closed and the process itself is terminated. An
908 IoDevice returned from this call can be used as an argument to
909 the I/O functions (see io(3)).
910 Note:
912 In previous versions of file, modes were specified as one of the
913 atoms read, write, or read_write instead of a list. This is
914 still allowed for reasons of backwards compatibility, but is not
915 to be used for new code. Also note that read_write is not
916 allowed in a mode list.
917 Typical error reasons:
920 enoent:
922 The file does not exist.
923 eacces:
925 Missing permission for reading the file or searching one of
926 the parent directories.
927 eisdir:
929 The named file is a directory.
930 enotdir:
932 A component of the filename is not a directory. On some
933 platforms, enoent is returned instead.
934 enospc:
936 There is no space left on the device (if write access was
937 specified).
938 path_consult(Path, Filename) ->
940 {ok, Terms, FullName} | {error, Reason}
941 Types:
943 Path = [Dir]
945 Dir = Filename = name_all()
946 Terms = [term()]
947 FullName = filename_all()
948 Reason =
949 posix() |
950 badarg | terminated | system_limit |
951 {Line :: integer(), Mod :: module(), Term :: term()}
952 Searches the path Path (a list of directory names) until the
954 file Filename is found. If Filename is an absolute filename,
955 Path is ignored. Then reads Erlang terms, separated by '.', from
956 the file.
957 Returns one of the following:
959 {ok, Terms, FullName}:
961 The file is successfully read. FullName is the full name of
962 the file.
963 {error, enoent}:
965 The file cannot be found in any of the directories in Path.
966 {error, atom()}:
968 An error occurred when opening the file or reading it. For a
969 list of typical error codes, see open/2.
970 {error, {Line, Mod, Term}}:
972 An error occurred when interpreting the Erlang terms in the
973 file. Use format_error/1 to convert the three-element tuple
974 to an English description of the error.
975 The encoding of Filename can be set by a comment as described in
977 epp(3).
978 path_eval(Path, Filename) -> {ok, FullName} | {error, Reason}
980 Types:
982 Path = [Dir :: name_all()]
984 Filename = name_all()
985 FullName = filename_all()
986 Reason =
987 posix() |
988 badarg | terminated | system_limit |
989 {Line :: integer(), Mod :: module(), Term :: term()}
990 Searches the path Path (a list of directory names) until the
992 file Filename is found. If Filename is an absolute filename,
993 Path is ignored. Then reads and evaluates Erlang expressions,
994 separated by '.' (or ',', a sequence of expressions is also an
995 expression), from the file. The result of evaluation is not
996 returned; any expression sequence in the file must be there for
997 its side effect.
998 Returns one of the following:
1000 {ok, FullName}:
1002 The file is read and evaluated. FullName is the full name of
1003 the file.
1004 {error, enoent}:
1006 The file cannot be found in any of the directories in Path.
1007 {error, atom()}:
1009 An error occurred when opening the file or reading it. For a
1010 list of typical error codes, see open/2.
1011 {error, {Line, Mod, Term}}:
1013 An error occurred when interpreting the Erlang expressions
1014 in the file. Use format_error/1 to convert the three-element
1015 tuple to an English description of the error.
1016 The encoding of Filename can be set by a comment as described in
1018 epp(3).
1019 path_open(Path, Filename, Modes) ->
1021 {ok, IoDevice, FullName} | {error, Reason}
1022 Types:
1024 Path = [Dir :: name_all()]
1026 Filename = name_all()
1027 Modes = [mode()]
1028 IoDevice = io_device()
1029 FullName = filename_all()
1030 Reason = posix() | badarg | system_limit
1031 Searches the path Path (a list of directory names) until the
1033 file Filename is found. If Filename is an absolute filename,
1034 Path is ignored. Then opens the file in the mode determined by
1035 Modes.
1036 Returns one of the following:
1038 {ok, IoDevice, FullName}:
1040 The file is opened in the requested mode. IoDevice is a ref‐
1041 erence to the file and FullName is the full name of the
1042 file.
1043 {error, enoent}:
1045 The file cannot be found in any of the directories in Path.
1046 {error, atom()}:
1048 The file cannot be opened.
1049 path_script(Path, Filename) ->
1051 {ok, Value, FullName} | {error, Reason}
1052 Types:
1054 Path = [Dir :: name_all()]
1056 Filename = name_all()
1057 Value = term()
1058 FullName = filename_all()
1059 Reason =
1060 posix() |
1061 badarg | terminated | system_limit |
1062 {Line :: integer(), Mod :: module(), Term :: term()}
1063 Searches the path Path (a list of directory names) until the
1065 file Filename is found. If Filename is an absolute filename,
1066 Path is ignored. Then reads and evaluates Erlang expressions,
1067 separated by '.' (or ',', a sequence of expressions is also an
1068 expression), from the file.
1069 Returns one of the following:
1071 {ok, Value, FullName}:
1073 The file is read and evaluated. FullName is the full name of
1074 the file and Value the value of the last expression.
1075 {error, enoent}:
1077 The file cannot be found in any of the directories in Path.
1078 {error, atom()}:
1080 An error occurred when opening the file or reading it. For a
1081 list of typical error codes, see open/2.
1082 {error, {Line, Mod, Term}}:
1084 An error occurred when interpreting the Erlang expressions
1085 in the file. Use format_error/1 to convert the three-element
1086 tuple to an English description of the error.
1087 The encoding of Filename can be set by a comment as described in
1089 epp(3).
1090 path_script(Path, Filename, Bindings) ->
1092 {ok, Value, FullName} | {error, Reason}
1093 Types:
1095 Path = [Dir :: name_all()]
1097 Filename = name_all()
1098 Bindings = erl_eval:binding_struct()
1099 Value = term()
1100 FullName = filename_all()
1101 Reason =
1102 posix() |
1103 badarg | terminated | system_limit |
1104 {Line :: integer(), Mod :: module(), Term :: term()}
1105 The same as path_script/2 but the variable bindings Bindings are
1107 used in the evaluation. See erl_eval(3) about variable bindings.
1108 pid2name(Pid) -> {ok, Filename} | undefined
1110 Types:
1112 Filename = filename_all()
1114 Pid = pid()
1115 If Pid is an I/O device, that is, a pid returned from open/2,
1117 this function returns the filename, or rather:
1118 {ok, Filename}:
1120 If the file server of this node is not a slave, the file was
1121 opened by the file server of this node (this implies that
1122 Pid must be a local pid) and the file is not closed. File‐
1123 name is the filename in flat string format.
1124 undefined:
1126 In all other cases.
1127 Warning:
1129 This function is intended for debugging only.
1130 position(IoDevice, Location) ->
1133 {ok, NewPosition} | {error, Reason}
1134 Types:
1136 IoDevice = io_device()
1138 Location = location()
1139 NewPosition = integer()
1140 Reason = posix() | badarg | terminated
1141 Sets the position of the file referenced by IoDevice to Loca‐
1143 tion. Returns {ok, NewPosition} (as absolute offset) if success‐
1144 ful, otherwise {error, Reason}. Location is one of the follow‐
1145 ing:
1146 Offset:
1148 The same as {bof, Offset}.
1149 {bof, Offset}:
1151 Absolute offset.
1152 {cur, Offset}:
1154 Offset from the current position.
1155 {eof, Offset}:
1157 Offset from the end of file.
1158 bof | cur | eof:
1160 The same as above with Offset 0.
1161 Notice that offsets are counted in bytes, not in characters. If
1163 the file is opened using some other encoding than latin1, one
1164 byte does not correspond to one character. Positioning in such a
1165 file can only be done to known character boundaries. That is, to
1166 a position earlier retrieved by getting a current position, to
1167 the beginning/end of the file or to some other position known to
1168 be on a correct character boundary by some other means (typi‐
1169 cally beyond a byte order mark in the file, which has a known
1170 byte-size).
1171 A typical error reason is:
1173 einval:
1175 Either Location is illegal, or it is evaluated to a negative
1176 offset in the file. Notice that if the resulting position is
1177 a negative value, the result is an error, and after the call
1178 the file position is undefined.
1179 pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason}
1181 Types:
1183 IoDevice = io_device()
1185 LocNums =
1186 [{Location :: location(), Number :: integer() >= 0}]
1187 DataL = [Data]
1188 Data = string() | binary() | eof
1189 Reason = posix() | badarg | terminated
1190 Performs a sequence of pread/3 in one operation, which is more
1192 efficient than calling them one at a time. Returns {ok, [Data,
1193 ...]} or {error, Reason}, where each Data, the result of the
1194 corresponding pread, is either a list or a binary depending on
1195 the mode of the file, or eof if the requested position is beyond
1196 end of file.
1197 As the position is specified as a byte-offset, take special cau‐
1199 tion when working with files where encoding is set to something
1200 else than latin1, as not every byte position is a valid charac‐
1201 ter boundary on such a file.
1202 pread(IoDevice, Location, Number) ->
1204 {ok, Data} | eof | {error, Reason}
1205 Types:
1207 IoDevice = io_device()
1209 Location = location()
1210 Number = integer() >= 0
1211 Data = string() | binary()
1212 Reason = posix() | badarg | terminated
1213 Combines position/2 and read/2 in one operation, which is more
1215 efficient than calling them one at a time. If IoDevice is opened
1216 in raw mode, some restrictions apply:
1217 * Location is only allowed to be an integer.
1219 * The current position of the file is undefined after the
1221 operation.
1222 As the position is specified as a byte-offset, take special cau‐
1224 tion when working with files where encoding is set to something
1225 else than latin1, as not every byte position is a valid charac‐
1226 ter boundary on such a file.
1227 pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}}
1229 Types:
1231 IoDevice = io_device()
1233 LocBytes = [{Location :: location(), Bytes :: iodata()}]
1234 N = integer() >= 0
1235 Reason = posix() | badarg | terminated
1236 Performs a sequence of pwrite/3 in one operation, which is more
1238 efficient than calling them one at a time. Returns ok or {error,
1239 {N, Reason}}, where N is the number of successful writes done
1240 before the failure.
1241 When positioning in a file with other encoding than latin1, cau‐
1243 tion must be taken to set the position on a correct character
1244 boundary. For details, see position/2.
1245 pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason}
1247 Types:
1249 IoDevice = io_device()
1251 Location = location()
1252 Bytes = iodata()
1253 Reason = posix() | badarg | terminated
1254 Combines position/2 and write/2 in one operation, which is more
1256 efficient than calling them one at a time. If IoDevice has been
1257 opened in raw mode, some restrictions apply:
1258 * Location is only allowed to be an integer.
1260 * The current position of the file is undefined after the
1262 operation.
1263 When positioning in a file with other encoding than latin1, cau‐
1265 tion must be taken to set the position on a correct character
1266 boundary. For details, see position/2.
1267 read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}
1269 Types:
1271 IoDevice = io_device() | atom()
1273 Number = integer() >= 0
1274 Data = string() | binary()
1275 Reason =
1276 posix() |
1277 badarg | terminated |
1278 {no_translation, unicode, latin1}
1279 Reads Number bytes/characters from the file referenced by IoDe‐
1281 vice. The functions read/2, pread/3, and read_line/1 are the
1282 only ways to read from a file opened in raw mode (although they
1283 work for normally opened files, too).
1284 For files where encoding is set to something else than latin1,
1286 one character can be represented by more than one byte on the
1287 file. The parameter Number always denotes the number of charac‐
1288 ters read from the file, while the position in the file can be
1289 moved much more than this number when reading a Unicode file.
1290 Also, if encoding is set to something else than latin1, the
1292 read/3 call fails if the data contains characters larger than
1293 255, which is why module io(3) is to be preferred when reading
1294 such a file.
1295 The function returns:
1297 {ok, Data}:
1299 If the file was opened in binary mode, the read bytes are
1300 returned in a binary, otherwise in a list. The list or
1301 binary is shorter than the number of bytes requested if end
1302 of file was reached.
1303 eof:
1305 Returned if Number>0 and end of file was reached before any‐
1306 thing at all could be read.
1307 {error, Reason}:
1309 An error occurred.
1310 Typical error reasons:
1312 ebadf:
1314 The file is not opened for reading.
1315 {no_translation, unicode, latin1}:
1317 The file is opened with another encoding than latin1 and the
1318 data in the file cannot be translated to the byte-oriented
1319 data that this function returns.
1320 read_file(Filename) -> {ok, Binary} | {error, Reason}
1322 Types:
1324 Filename = name_all()
1326 Binary = binary()
1327 Reason = posix() | badarg | terminated | system_limit
1328 Returns {ok, Binary}, where Binary is a binary data object that
1330 contains the contents of Filename, or {error, Reason} if an
1331 error occurs.
1332 Typical error reasons:
1334 enoent:
1336 The file does not exist.
1337 eacces:
1339 Missing permission for reading the file, or for searching
1340 one of the parent directories.
1341 eisdir:
1343 The named file is a directory.
1344 enotdir:
1346 A component of the filename is not a directory. On some
1347 platforms, enoent is returned instead.
1348 enomem:
1350 There is not enough memory for the contents of the file.
1351 read_file_info(Filename) -> {ok, FileInfo} | {error, Reason}
1353 read_file_info(Filename, Opts) -> {ok, FileInfo} | {error, Reason}
1355 Types:
1357 Filename = name_all()
1359 Opts = [file_info_option()]
1360 FileInfo = file_info()
1361 Reason = posix() | badarg
1362 Retrieves information about a file. Returns {ok, FileInfo} if
1364 successful, otherwise {error, Reason}. FileInfo is a record
1365 file_info, defined in the Kernel include file file.hrl. Include
1366 the following directive in the module from which the function is
1367 called:
1368 -include_lib("kernel/include/file.hrl").
1370 The time type returned in atime, mtime, and ctime is dependent
1372 on the time type set in Opts :: {time, Type} as follows:
1373 local:
1375 Returns local time.
1376 universal:
1378 Returns universal time.
1379 posix:
1381 Returns seconds since or before Unix time epoch, which is
1382 1970-01-01 00:00 UTC.
1383 Default is {time, local}.
1385 If the option raw is set, the file server is not called and only
1387 information about local files is returned. Note that this will
1388 break this module's atomicity guarantees as it can race with a
1389 concurrent call to write_file_info/1,2
1390 Note:
1392 As file times are stored in POSIX time on most OS, it is faster
1393 to query file information with option posix.
1394 The record file_info contains the following fields:
1397 size = integer() >= 0:
1399 Size of file in bytes.
1400 type = device | directory | other | regular | symlink:
1402 The type of the file.
1403 access = read | write | read_write | none:
1405 The current system access to the file.
1406 atime = date_time() | integer() >= 0:
1408 The last time the file was read.
1409 mtime = date_time() | integer() >= 0:
1411 The last time the file was written.
1412 ctime = date_time() | integer() >=0:
1414 The interpretation of this time field depends on the operat‐
1415 ing system. On Unix, it is the last time the file or the
1416 inode was changed. In Windows, it is the create time.
1417 mode = integer() >= 0:
1419 The file permissions as the sum of the following bit values:
1420 8#00400:
1422 read permission: owner
1423 8#00200:
1425 write permission: owner
1426 8#00100:
1428 execute permission: owner
1429 8#00040:
1431 read permission: group
1432 8#00020:
1434 write permission: group
1435 8#00010:
1437 execute permission: group
1438 8#00004:
1440 read permission: other
1441 8#00002:
1443 write permission: other
1444 8#00001:
1446 execute permission: other
1447 16#800:
1449 set user id on execution
1450 16#400:
1452 set group id on execution
1453 On Unix platforms, other bits than those listed above may be
1455 set.
1456 links = integer() >= 0:
1458 Number of links to the file (this is always 1 for file sys‐
1459 tems that have no concept of links).
1460 major_device = integer() >= 0:
1462 Identifies the file system where the file is located. In
1463 Windows, the number indicates a drive as follows: 0 means
1464 A:, 1 means B:, and so on.
1465 minor_device = integer() >= 0:
1467 Only valid for character devices on Unix. In all other
1468 cases, this field is zero.
1469 inode = integer() >= 0:
1471 Gives the inode number. On non-Unix file systems, this field
1472 is zero.
1473 uid = integer() >= 0:
1475 Indicates the owner of the file. On non-Unix file systems,
1476 this field is zero.
1477 gid = integer() >= 0:
1479 Gives the group that the owner of the file belongs to. On
1480 non-Unix file systems, this field is zero.
1481 Typical error reasons:
1483 eacces:
1485 Missing search permission for one of the parent directories
1486 of the file.
1487 enoent:
1489 The file does not exist.
1490 enotdir:
1492 A component of the filename is not a directory. On some
1493 platforms, enoent is returned instead.
1494 read_line(IoDevice) -> {ok, Data} | eof | {error, Reason}
1496 Types:
1498 IoDevice = io_device() | atom()
1500 Data = string() | binary()
1501 Reason =
1502 posix() |
1503 badarg | terminated |
1504 {no_translation, unicode, latin1}
1505 Reads a line of bytes/characters from the file referenced by
1507 IoDevice. Lines are defined to be delimited by the linefeed (LF,
1508 \n) character, but any carriage return (CR, \r) followed by a
1509 newline is also treated as a single LF character (the carriage
1510 return is silently ignored). The line is returned including the
1511 LF, but excluding any CR immediately followed by an LF. This be‐
1512 haviour is consistent with the behaviour of io:get_line/2. If
1513 end of file is reached without any LF ending the last line, a
1514 line with no trailing LF is returned.
1515 The function can be used on files opened in raw mode. However,
1517 it is inefficient to use it on raw files if the file is not
1518 opened with option {read_ahead, Size} specified. Thus, combining
1519 raw and {read_ahead, Size} is highly recommended when opening a
1520 text file for raw line-oriented reading.
1521 If encoding is set to something else than latin1, the
1523 read_line/1 call fails if the data contains characters larger
1524 than 255, why module io(3) is to be preferred when reading such
1525 a file.
1526 The function returns:
1528 {ok, Data}:
1530 One line from the file is returned, including the trailing
1531 LF, but with CRLF sequences replaced by a single LF (see
1532 above).
1533 If the file is opened in binary mode, the read bytes are
1535 returned in a binary, otherwise in a list.
1536 eof:
1538 Returned if end of file was reached before anything at all
1539 could be read.
1540 {error, Reason}:
1542 An error occurred.
1543 Typical error reasons:
1545 ebadf:
1547 The file is not opened for reading.
1548 {no_translation, unicode, latin1}:
1550 The file is opened with another encoding than latin1 and the
1551 data on the file cannot be translated to the byte-oriented
1552 data that this function returns.
1553 read_link(Name) -> {ok, Filename} | {error, Reason}
1555 Types:
1557 Name = name_all()
1559 Filename = filename()
1560 Reason = posix() | badarg
1561 Returns {ok, Filename} if Name refers to a symbolic link that is
1563 not a raw filename, or {error, Reason} otherwise. On platforms
1564 that do not support symbolic links, the return value is
1565 {error,enotsup}.
1566 Typical error reasons:
1568 einval:
1570 Name does not refer to a symbolic link or the name of the
1571 file that it refers to does not conform to the expected
1572 encoding.
1573 enoent:
1575 The file does not exist.
1576 enotsup:
1578 Symbolic links are not supported on this platform.
1579 read_link_all(Name) -> {ok, Filename} | {error, Reason}
1581 Types:
1583 Name = name_all()
1585 Filename = filename_all()
1586 Reason = posix() | badarg
1587 Returns {ok, Filename} if Name refers to a symbolic link or
1589 {error, Reason} otherwise. On platforms that do not support sym‐
1590 bolic links, the return value is {error,enotsup}.
1591 Notice that Filename can be either a list or a binary.
1593 Typical error reasons:
1595 einval:
1597 Name does not refer to a symbolic link.
1598 enoent:
1600 The file does not exist.
1601 enotsup:
1603 Symbolic links are not supported on this platform.
1604 read_link_info(Name) -> {ok, FileInfo} | {error, Reason}
1606 read_link_info(Name, Opts) -> {ok, FileInfo} | {error, Reason}
1608 Types:
1610 Name = name_all()
1612 Opts = [file_info_option()]
1613 FileInfo = file_info()
1614 Reason = posix() | badarg
1615 Works like read_file_info/1,2 except that if Name is a symbolic
1617 link, information about the link is returned in the file_info
1618 record and the type field of the record is set to symlink.
1619 If the option raw is set, the file server is not called and only
1621 information about local files is returned. Note that this will
1622 break this module's atomicity guarantees as it can race with a
1623 concurrent call to write_file_info/1,2
1624 If Name is not a symbolic link, this function returns the same
1626 result as read_file_info/1. On platforms that do not support
1627 symbolic links, this function is always equivalent to
1628 read_file_info/1.
1629 rename(Source, Destination) -> ok | {error, Reason}
1631 Types:
1633 Source = Destination = name_all()
1635 Reason = posix() | badarg
1636 Tries to rename the file Source to Destination. It can be used
1638 to move files (and directories) between directories, but it is
1639 not sufficient to specify the destination only. The destination
1640 filename must also be specified. For example, if bar is a normal
1641 file and foo and baz are directories, rename("foo/bar", "baz")
1642 returns an error, but rename("foo/bar", "baz/bar") succeeds.
1643 Returns ok if it is successful.
1644 Note:
1646 Renaming of open files is not allowed on most platforms (see
1647 eacces below).
1648 Typical error reasons:
1651 eacces:
1653 Missing read or write permissions for the parent directories
1654 of Source or Destination. On some platforms, this error is
1655 given if either Source or Destination is open.
1656 eexist:
1658 Destination is not an empty directory. On some platforms,
1659 also given when Source and Destination are not of the same
1660 type.
1661 einval:
1663 Source is a root directory, or Destination is a subdirectory
1664 of Source.
1665 eisdir:
1667 Destination is a directory, but Source is not.
1668 enoent:
1670 Source does not exist.
1671 enotdir:
1673 Source is a directory, but Destination is not.
1674 exdev:
1676 Source and Destination are on different file systems.
1677 script(Filename) -> {ok, Value} | {error, Reason}
1679 Types:
1681 Filename = name_all()
1683 Value = term()
1684 Reason =
1685 posix() |
1686 badarg | terminated | system_limit |
1687 {Line :: integer(), Mod :: module(), Term :: term()}
1688 Reads and evaluates Erlang expressions, separated by '.' (or
1690 ',', a sequence of expressions is also an expression), from the
1691 file.
1692 Returns one of the following:
1694 {ok, Value}:
1696 The file is read and evaluated. Value is the value of the
1697 last expression.
1698 {error, atom()}:
1700 An error occurred when opening the file or reading it. For a
1701 list of typical error codes, see open/2.
1702 {error, {Line, Mod, Term}}:
1704 An error occurred when interpreting the Erlang expressions
1705 in the file. Use format_error/1 to convert the three-element
1706 tuple to an English description of the error.
1707 The encoding of Filename can be set by a comment as described in
1709 epp(3).
1710 script(Filename, Bindings) -> {ok, Value} | {error, Reason}
1712 Types:
1714 Filename = name_all()
1716 Bindings = erl_eval:binding_struct()
1717 Value = term()
1718 Reason =
1719 posix() |
1720 badarg | terminated | system_limit |
1721 {Line :: integer(), Mod :: module(), Term :: term()}
1722 The same as script/1 but the variable bindings Bindings are used
1724 in the evaluation. See erl_eval(3) about variable bindings.
1725 sendfile(Filename, Socket) ->
1727 {ok, integer() >= 0} |
1728 {error, inet:posix() | closed | badarg | not_owner}
1729 Types:
1731 Filename = name_all()
1733 Socket = inet:socket()
1734 Sends the file Filename to Socket. Returns {ok, BytesSent} if
1736 successful, otherwise {error, Reason}.
1737 sendfile(RawFile, Socket, Offset, Bytes, Opts) ->
1739 {ok, integer() >= 0} |
1740 {error, inet:posix() | closed | badarg | not_owner}
1741 Types:
1743 RawFile = fd()
1745 Socket = inet:socket()
1746 Offset = Bytes = integer() >= 0
1747 Opts = [sendfile_option()]
1748 sendfile_option() =
1749 {chunk_size, integer() >= 0} | {use_threads, boolean()}
1750 Sends Bytes from the file referenced by RawFile beginning at
1752 Offset to Socket. Returns {ok, BytesSent} if successful, other‐
1753 wise {error, Reason}. If Bytes is set to 0 all data after the
1754 specified Offset is sent.
1755 The file used must be opened using the raw flag, and the process
1757 calling sendfile must be the controlling process of the socket.
1758 See gen_tcp:controlling_process/2.
1759 If the OS used does not support non-blocking sendfile, an Erlang
1761 fallback using read/2 and gen_tcp:send/2 is used.
1762 The option list can contain the following options:
1764 chunk_size:
1766 The chunk size used by the Erlang fallback to send data. If
1767 using the fallback, set this to a value that comfortably
1768 fits in the systems memory. Default is 20 MB.
1769 set_cwd(Dir) -> ok | {error, Reason}
1771 Types:
1773 Dir = name() | EncodedBinary
1775 EncodedBinary = binary()
1776 Reason = posix() | badarg | no_translation
1777 Sets the current working directory of the file server to Dir.
1779 Returns ok if successful.
1780 The functions in the module file usually treat binaries as raw
1782 filenames, that is, they are passed "as is" even when the encod‐
1783 ing of the binary does not agree with native_name_encoding().
1784 However, this function expects binaries to be encoded according
1785 to the value returned by native_name_encoding().
1786 Typical error reasons are:
1788 enoent:
1790 The directory does not exist.
1791 enotdir:
1793 A component of Dir is not a directory. On some platforms,
1794 enoent is returned.
1795 eacces:
1797 Missing permission for the directory or one of its parents.
1798 badarg:
1800 Dir has an improper type, such as tuple.
1801 no_translation:
1803 Dir is a binary() with characters coded in ISO-latin-1 and
1804 the VM is operating with unicode filename encoding.
1805 Warning:
1807 In a future release, a bad type for argument Dir will probably
1808 generate an exception.
1809 sync(IoDevice) -> ok | {error, Reason}
1812 Types:
1814 IoDevice = io_device()
1816 Reason = posix() | badarg | terminated
1817 Ensures that any buffers kept by the operating system (not by
1819 the Erlang runtime system) are written to disk. On some plat‐
1820 forms, this function might have no effect.
1821 A typical error reason is:
1823 enospc:
1825 Not enough space left to write the file.
1826 truncate(IoDevice) -> ok | {error, Reason}
1828 Types:
1830 IoDevice = io_device()
1832 Reason = posix() | badarg | terminated
1833 Truncates the file referenced by IoDevice at the current posi‐
1835 tion. Returns ok if successful, otherwise {error, Reason}.
1836 write(IoDevice, Bytes) -> ok | {error, Reason}
1838 Types:
1840 IoDevice = io_device() | atom()
1842 Bytes = iodata()
1843 Reason = posix() | badarg | terminated
1844 Writes Bytes to the file referenced by IoDevice. This function
1846 is the only way to write to a file opened in raw mode (although
1847 it works for normally opened files too). Returns ok if success‐
1848 ful, and {error, Reason} otherwise.
1849 If the file is opened with encoding set to something else than
1851 latin1, each byte written can result in many bytes being written
1852 to the file, as the byte range 0..255 can represent anything
1853 between one and four bytes depending on value and UTF encoding
1854 type.
1855 Typical error reasons:
1857 ebadf:
1859 The file is not opened for writing.
1860 enospc:
1862 No space is left on the device.
1863 write_file(Filename, Bytes) -> ok | {error, Reason}
1865 Types:
1867 Filename = name_all()
1869 Bytes = iodata()
1870 Reason = posix() | badarg | terminated | system_limit
1871 Writes the contents of the iodata term Bytes to file Filename.
1873 The file is created if it does not exist. If it exists, the pre‐
1874 vious contents are overwritten. Returns ok if successful, other‐
1875 wise {error, Reason}.
1876 Typical error reasons:
1878 enoent:
1880 A component of the filename does not exist.
1881 enotdir:
1883 A component of the filename is not a directory. On some
1884 platforms, enoent is returned instead.
1885 enospc:
1887 No space is left on the device.
1888 eacces:
1890 Missing permission for writing the file or searching one of
1891 the parent directories.
1892 eisdir:
1894 The named file is a directory.
1895 write_file(Filename, Bytes, Modes) -> ok | {error, Reason}
1897 Types:
1899 Filename = name_all()
1901 Bytes = iodata()
1902 Modes = [mode()]
1903 Reason = posix() | badarg | terminated | system_limit
1904 Same as write_file/2, but takes a third argument Modes, a list
1906 of possible modes, see open/2. The mode flags binary and write
1907 are implicit, so they are not to be used.
1908 write_file_info(Filename, FileInfo) -> ok | {error, Reason}
1910 write_file_info(Filename, FileInfo, Opts) -> ok | {error, Reason}
1912 Types:
1914 Filename = name_all()
1916 Opts = [file_info_option()]
1917 FileInfo = file_info()
1918 Reason = posix() | badarg
1919 Changes file information. Returns ok if successful, otherwise
1921 {error, Reason}. FileInfo is a record file_info, defined in the
1922 Kernel include file file.hrl. Include the following directive in
1923 the module from which the function is called:
1924 -include_lib("kernel/include/file.hrl").
1926 The time type set in atime, mtime, and ctime depends on the time
1928 type set in Opts :: {time, Type} as follows:
1929 local:
1931 Interprets the time set as local.
1932 universal:
1934 Interprets it as universal time.
1935 posix:
1937 Must be seconds since or before Unix time epoch, which is
1938 1970-01-01 00:00 UTC.
1939 Default is {time, local}.
1941 If the option raw is set, the file server is not called and only
1943 information about local files is returned.
1944 The following fields are used from the record, if they are spec‐
1946 ified:
1947 atime = date_time() | integer() >= 0:
1949 The last time the file was read.
1950 mtime = date_time() | integer() >= 0:
1952 The last time the file was written.
1953 ctime = date_time() | integer() >= 0:
1955 On Unix, any value specified for this field is ignored (the
1956 "ctime" for the file is set to the current time). On Win‐
1957 dows, this field is the new creation time to set for the
1958 file.
1959 mode = integer() >= 0:
1961 The file permissions as the sum of the following bit values:
1962 8#00400:
1964 Read permission: owner
1965 8#00200:
1967 Write permission: owner
1968 8#00100:
1970 Execute permission: owner
1971 8#00040:
1973 Read permission: group
1974 8#00020:
1976 Write permission: group
1977 8#00010:
1979 Execute permission: group
1980 8#00004:
1982 Read permission: other
1983 8#00002:
1985 Write permission: other
1986 8#00001:
1988 Execute permission: other
1989 16#800:
1991 Set user id on execution
1992 16#400:
1994 Set group id on execution
1995 On Unix platforms, other bits than those listed above may be
1997 set.
1998 uid = integer() >= 0:
2000 Indicates the file owner. Ignored for non-Unix file systems.
2001 gid = integer() >= 0:
2003 Gives the group that the file owner belongs to. Ignored for
2004 non-Unix file systems.
2005 Typical error reasons:
2007 eacces:
2009 Missing search permission for one of the parent directories
2010 of the file.
2011 enoent:
2013 The file does not exist.
2014 enotdir:
2016 A component of the filename is not a directory. On some
2017 platforms, enoent is returned instead.
2018
2020 * eacces - Permission denied
2021 * eagain - Resource temporarily unavailable
2023 * ebadf - Bad file number
2025 * ebusy - File busy
2027 * edquot - Disk quota exceeded
2029 * eexist - File already exists
2031 * efault - Bad address in system call argument
2033 * efbig - File too large
2035 * eintr - Interrupted system call
2037 * einval - Invalid argument
2039 * eio - I/O error
2041 * eisdir - Illegal operation on a directory
2043 * eloop - Too many levels of symbolic links
2045 * emfile - Too many open files
2047 * emlink - Too many links
2049 * enametoolong - Filename too long
2051 * enfile - File table overflow
2053 * enodev - No such device
2055 * enoent - No such file or directory
2057 * enomem - Not enough memory
2059 * enospc - No space left on device
2061 * enotblk - Block device required
2063 * enotdir - Not a directory
2065 * enotsup - Operation not supported
2067 * enxio - No such device or address
2069 * eperm - Not owner
2071 * epipe - Broken pipe
2073 * erofs - Read-only file system
2075 * espipe - Invalid seek
2077 * esrch - No such process
2079 * estale - Stale remote file handle
2081 * exdev - Cross-domain link
2083
2085 For increased performance, raw files are recommended.
2086 A normal file is really a process so it can be used as an I/O device
2088 (see io). Therefore, when data is written to a normal file, the sending
2089 of the data to the file process, copies all data that are not binaries.
2090 Opening the file in binary mode and writing binaries is therefore rec‐
2091 ommended. If the file is opened on another node, or if the file server
2092 runs as slave to the file server of another node, also binaries are
2093 copied.
2094 Note:
2096 Raw files use the file system of the host machine of the node. For nor‐
2097 mal files (non-raw), the file server is used to find the files, and if
2098 the node is running its file server as slave to the file server of
2099 another node, and the other node runs on some other host machine, they
2100 can have different file systems. However, this is seldom a problem.
2101 open/2 can be given the options delayed_write and read_ahead to turn on
2104 caching, which will reduce the number of operating system calls and
2105 greatly improve performance for small reads and writes. However, the
2106 overhead won't disappear completely and it's best to keep the number of
2107 file operations to a minimum. As a contrived example, the following
2108 function writes 4MB in 2.5 seconds when tested:
2109 create_file_slow(Name) ->
2111 {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2112 create_file_slow_1(Fd, 4 bsl 20),
2113 file:close(Fd).
2114 create_file_slow_1(_Fd, 0) ->
2116 ok;
2117 create_file_slow_1(Fd, M) ->
2118 ok = file:write(Fd, <<0>>),
2119 create_file_slow_1(Fd, M - 1).
2120 The following functionally equivalent code writes 128 bytes per call to
2122 write/2 and so does the same work in 0.08 seconds, which is roughly 30
2123 times faster:
2124 create_file(Name) ->
2126 {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2127 create_file_1(Fd, 4 bsl 20),
2128 file:close(Fd),
2129 ok.
2130 create_file_1(_Fd, 0) ->
2132 ok;
2133 create_file_1(Fd, M) when M >= 128 ->
2134 ok = file:write(Fd, <<0:(128)/unit:8>>),
2135 create_file_1(Fd, M - 128);
2136 create_file_1(Fd, M) ->
2137 ok = file:write(Fd, <<0:(M)/unit:8>>),
2138 create_file_1(Fd, M - 1).
2139 When writing data it's generally more efficient to write a list of
2141 binaries rather than a list of integers. It is not needed to flatten a
2142 deep list before writing. On Unix hosts, scatter output, which writes a
2143 set of buffers in one operation, is used when possible. In this way
2144 write(FD, [Bin1, Bin2 | Bin3]) writes the contents of the binaries
2145 without copying the data at all, except for perhaps deep down in the
2146 operating system kernel.
2147 Warning:
2149 If an error occurs when accessing an open file with module io, the
2150 process handling the file exits. The dead file process can hang if a
2151 process tries to access it later. This will be fixed in a future
2152 release.
2153
2156 filename(3)
2157Ericsson AB kernel 6.5.2 file(3)