1file(3)                    Erlang Module Definition                    file(3)
2
3
4

NAME

6       file - File interface module.
7

DESCRIPTION

9       This module provides an interface to the file system.
10
11   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
18
19       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
23       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
28       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
32       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
37       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
43       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
47       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
51       See also section Notes About Raw Filenames in the STDLIB User's Guide.
52
53   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
60

DATA TYPES

62       deep_list() = [char() | atom() | deep_list()]
63
64       fd()
65
66              A file descriptor representing a file opened in raw mode.
67
68       filename() = string()
69
70              See also the documentation of the name_all() type.
71
72       filename_all() = string() | binary()
73
74              See also the documentation of the name_all() type.
75
76       io_device() = pid() | fd()
77
78              As  returned  by  open/2; pid() is a process handling I/O-proto‐
79              cols.
80
81       name() = string() | atom() | deep_list()
82
83              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
87       name_all() =
88           string() | atom() | deep_list() | (RawFilename :: binary())
89
90              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
98       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
108              An atom that is named from the POSIX error codes used  in  Unix,
109              and in the runtime libraries of most C compilers.
110
111       date_time() = calendar:datetime()
112
113              Must denote a valid date and time.
114
115       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
142       location() =
143           integer() |
144           {bof, Offset :: integer()} |
145           {cur, Offset :: integer()} |
146           {eof, Offset :: integer()} |
147           bof | cur | eof
148
149       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
160       file_info_option() =
161           {time, local} | {time, universal} | {time, posix} | raw
162

EXPORTS

164       advise(IoDevice, Offset, Length, Advise) -> ok | {error, Reason}
165
166              Types:
167
168                 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
176              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
180              On some platforms, this function might have no effect.
181
182       allocate(File, Offset, Length) -> ok | {error, posix()}
183
184              Types:
185
186                 File = io_device()
187                 Offset = Length = integer() >= 0
188
189              allocate/3 can be used to preallocate space for a file.
190
191              This  function only succeeds in platforms that provide this fea‐
192              ture.
193
194       change_group(Filename, Gid) -> ok | {error, Reason}
195
196              Types:
197
198                 Filename = name_all()
199                 Gid = integer()
200                 Reason = posix() | badarg
201
202              Changes group of a file. See write_file_info/2.
203
204       change_mode(Filename, Mode) -> ok | {error, Reason}
205
206              Types:
207
208                 Filename = name_all()
209                 Mode = integer()
210                 Reason = posix() | badarg
211
212              Changes permissions of a file. See write_file_info/2.
213
214       change_owner(Filename, Uid) -> ok | {error, Reason}
215
216              Types:
217
218                 Filename = name_all()
219                 Uid = integer()
220                 Reason = posix() | badarg
221
222              Changes owner of a file. See write_file_info/2.
223
224       change_owner(Filename, Uid, Gid) -> ok | {error, Reason}
225
226              Types:
227
228                 Filename = name_all()
229                 Uid = Gid = integer()
230                 Reason = posix() | badarg
231
232              Changes owner and group of a file. See write_file_info/2.
233
234       change_time(Filename, Mtime) -> ok | {error, Reason}
235
236              Types:
237
238                 Filename = name_all()
239                 Mtime = date_time()
240                 Reason = posix() | badarg
241
242              Changes the  modification  and  access  times  of  a  file.  See
243              write_file_info/2.
244
245       change_time(Filename, Atime, Mtime) -> ok | {error, Reason}
246
247              Types:
248
249                 Filename = name_all()
250                 Atime = Mtime = date_time()
251                 Reason = posix() | badarg
252
253              Changes  the  modification  and last access times of a file. See
254              write_file_info/2.
255
256       close(IoDevice) -> ok | {error, Reason}
257
258              Types:
259
260                 IoDevice = io_device()
261                 Reason = posix() | badarg | terminated
262
263              Closes the file referenced by IoDevice. It  mostly  returns  ok,
264              except for some severe errors such as out of memory.
265
266              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
270       consult(Filename) -> {ok, Terms} | {error, Reason}
271
272              Types:
273
274                 Filename = name_all()
275                 Terms = [term()]
276                 Reason =
277                     posix() |
278                     badarg | terminated | system_limit |
279                     {Line :: integer(), Mod :: module(), Term :: term()}
280
281              Reads Erlang terms, separated by '.', from Filename. Returns one
282              of the following:
283
284                {ok, Terms}:
285                  The file was successfully read.
286
287                {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
291                {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
296              Example:
297
298              f.txt:  {person, "kalle", 25}.
299                      {person, "pelle", 30}.
300
301              1> file:consult("f.txt").
302              {ok,[{person,"kalle",25},{person,"pelle",30}]}
303
304              The  encoding  of Filename can be set by a comment, as described
305              in epp(3).
306
307       copy(Source, Destination) -> {ok, BytesCopied} | {error, Reason}
308
309       copy(Source, Destination, ByteCount) ->
310               {ok, BytesCopied} | {error, Reason}
311
312              Types:
313
314                 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
322              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
327              Argument Modes is a list of possible modes, see open/2, and  de‐
328              faults to [].
329
330              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
334              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
338              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
342              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
347              Typical error reasons: as for open/2 if a file had to be opened,
348              and as for read/2 and write/2.
349
350       datasync(IoDevice) -> ok | {error, Reason}
351
352              Types:
353
354                 IoDevice = io_device()
355                 Reason = posix() | badarg | terminated
356
357              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
363              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
373              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
377       del_dir(Dir) -> ok | {error, Reason}
378
379              Types:
380
381                 Dir = name_all()
382                 Reason = posix() | badarg
383
384              Tries  to  delete directory Dir. The directory must be empty be‐
385              fore it can be deleted. Returns ok if successful.
386
387              Typical error reasons:
388
389                eacces:
390                  Missing search or write permissions for the parent  directo‐
391                  ries of Dir.
392
393                eexist:
394                  The directory is not empty.
395
396                enoent:
397                  The directory does not exist.
398
399                enotdir:
400                  A  component  of  Dir is not a directory. On some platforms,
401                  enoent is returned instead.
402
403                einval:
404                  Attempt to delete the current directory. On some  platforms,
405                  eacces is returned instead.
406
407       del_dir_r(File) -> ok | {error, Reason}
408
409              Types:
410
411                 File = name_all()
412                 Reason = posix() | badarg
413
414              Deletes file or directory File. If File is a directory, its con‐
415              tents is first recursively deleted. Returns:
416
417                ok:
418                  The operation completed without errors.
419
420                {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
426       delete(Filename) -> ok | {error, Reason}
427
428       delete(Filename, Opts) -> ok | {error, Reason}
429
430              Types:
431
432                 Filename = name_all()
433                 Opts = [delete_option()]
434                 Reason = posix() | badarg
435                 delete_option() = raw
436
437              Tries to delete file Filename. Returns ok if successful.
438
439              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
444              Typical error reasons:
445
446                enoent:
447                  The file does not exist.
448
449                eacces:
450                  Missing permission for the file or one of its parents.
451
452                eperm:
453                  The file is a directory and the user is not superuser.
454
455                enotdir:
456                  A component of the filename is  not  a  directory.  On  some
457                  platforms, enoent is returned instead.
458
459                einval:
460                  Filename has an improper type, such as tuple.
461
462          Warning:
463              In a future release, a bad type for argument Filename will prob‐
464              ably generate an exception.
465
466
467       eval(Filename) -> ok | {error, Reason}
468
469              Types:
470
471                 Filename = name_all()
472                 Reason =
473                     posix() |
474                     badarg | terminated | system_limit |
475                     {Line :: integer(), Mod :: module(), Term :: term()}
476
477              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
483                ok:
484                  The file was read and evaluated.
485
486                {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
490                {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
495              The  encoding  of Filename can be set by a comment, as described
496              in epp(3).
497
498       eval(Filename, Bindings) -> ok | {error, Reason}
499
500              Types:
501
502                 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
509              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
513       format_error(Reason) -> Chars
514
515              Types:
516
517                 Reason =
518                     posix() |
519                     badarg | terminated | system_limit |
520                     {Line :: integer(), Mod :: module(), Term :: term()}
521                 Chars = string()
522
523              Given the error reason returned by any function in this  module,
524              returns a descriptive string of the error in English.
525
526       get_cwd() -> {ok, Dir} | {error, Reason}
527
528              Types:
529
530                 Dir = filename()
531                 Reason = posix()
532
533              Returns {ok, Dir}, where Dir is the current working directory of
534              the file server.
535
536          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
541
542              A typical error reason:
543
544                eacces:
545                  Missing read permission for one of the parents of  the  cur‐
546                  rent directory.
547
548       get_cwd(Drive) -> {ok, Dir} | {error, Reason}
549
550              Types:
551
552                 Drive = string()
553                 Dir = filename()
554                 Reason = posix() | badarg
555
556              Returns  {ok,  Dir} or {error, Reason}, where Dir is the current
557              working directory of the specified drive.
558
559              Drive is to be of the form "Letter:", for example, "c:".
560
561              Returns {error, enotsup} on platforms that have  no  concept  of
562              current drive (Unix, for example).
563
564              Typical error reasons:
565
566                enotsup:
567                  The operating system has no concept of drives.
568
569                eacces:
570                  The drive does not exist.
571
572                einval:
573                  The format of Drive is invalid.
574
575       list_dir(Dir) -> {ok, Filenames} | {error, Reason}
576
577              Types:
578
579                 Dir = name_all()
580                 Filenames = [filename()]
581                 Reason =
582                     posix() |
583                     badarg |
584                     {no_translation, Filename :: unicode:latin1_binary()}
585
586              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
591              Typical error reasons:
592
593                eacces:
594                  Missing search or write permissions for Dir or  one  of  its
595                  parent directories.
596
597                enoent:
598                  The directory does not exist.
599
600                {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
604       list_dir_all(Dir) -> {ok, Filenames} | {error, Reason}
605
606              Types:
607
608                 Dir = name_all()
609                 Filenames = [filename_all()]
610                 Reason = posix() | badarg
611
612              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
617              Typical error reasons:
618
619                eacces:
620                  Missing  search  or  write permissions for Dir or one of its
621                  parent directories.
622
623                enoent:
624                  The directory does not exist.
625
626       make_dir(Dir) -> ok | {error, Reason}
627
628              Types:
629
630                 Dir = name_all()
631                 Reason = posix() | badarg
632
633              Tries to create directory Dir. Missing  parent  directories  are
634              not created. Returns ok if successful.
635
636              Typical error reasons:
637
638                eacces:
639                  Missing  search or write permissions for the parent directo‐
640                  ries of Dir.
641
642                eexist:
643                  A file or directory named Dir exists already.
644
645                enoent:
646                  A component of Dir does not exist.
647
648                enospc:
649                  No space is left on the device.
650
651                enotdir:
652                  A component of Dir is not a directory.  On  some  platforms,
653                  enoent is returned instead.
654
655       make_link(Existing, New) -> ok | {error, Reason}
656
657              Types:
658
659                 Existing = New = name_all()
660                 Reason = posix() | badarg
661
662              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
667              Typical error reasons:
668
669                eacces:
670                  Missing read or write permissions for the parent directories
671                  of Existing or New.
672
673                eexist:
674                  New already exists.
675
676                enotsup:
677                  Hard links are not supported on this platform.
678
679       make_symlink(Existing, New) -> ok | {error, Reason}
680
681              Types:
682
683                 Existing = New = name_all()
684                 Reason = posix() | badarg
685
686              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
693              Typical error reasons:
694
695                eacces:
696                  Missing read or write permissions for the parent directories
697                  of Existing or New.
698
699                eexist:
700                  New already exists.
701
702                enotsup:
703                  Symbolic links are not supported on this platform.
704
705                eperm:
706                  User  does not have privileges to create symbolic links (Se‐
707                  CreateSymbolicLinkPrivilege on Windows).
708
709       native_name_encoding() -> latin1 | utf8
710
711              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
716       open(File, Modes) -> {ok, IoDevice} | {error, Reason}
717
718              Types:
719
720                 File = Filename | iodata()
721                 Filename = name_all()
722                 Modes = [mode() | ram | directory]
723                 IoDevice = io_device()
724                 Reason = posix() | badarg | system_limit
725
726              Opens  file File in the mode determined by Modes, which can con‐
727              tain one or more of the following options:
728
729                read:
730                  The file, which must exist, is opened for reading.
731
732                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
737                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
742                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
746            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
752
753                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
758                  * 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
762                  * 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
767                  * Only the Erlang process that opened the file can use it.
768
769                  * 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
773                binary:
774                  Read  operations  on  the  file  return binaries rather than
775                  lists.
776
777                {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
785                  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
791                  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
796                  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
802                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
807                {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
815                  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
820                  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
824                read_ahead:
825                  The same as {read_ahead, Size}  with  a  reasonable  default
826                  value for Size (roughly some 64 KB).
827
828                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
835                compressed_one:
836                  Read  one  member  of  a  gzip  compressed file. Option com‐
837                  pressed_one can only be combined with read.
838
839                {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
846                  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
854                  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
860                  Allowed values for Encoding:
861
862                  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
870                  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
880                    Bytes written to the file by any means are  translated  to
881                    UTF-8 encoding before being stored on the disk file.
882
883                  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
887                  {utf16,little}:
888                    Works like unicode, but translation is done  to  and  from
889                    little endian UTF-16 instead of UTF-8.
890
891                  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
895                  {utf32,little}:
896                    Works like unicode, but translation is done  to  and  from
897                    little endian UTF-32 instead of UTF-8.
898
899                  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
905                  This option is not allowed on raw files.
906
907                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
911                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
924                directory:
925                  Allows open to work on directories.
926
927              Returns:
928
929                {ok, IoDevice}:
930                  The file is opened in the requested mode. IoDevice is a ref‐
931                  erence to the file.
932
933                {error, Reason}:
934                  The file cannot be opened.
935
936              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
943          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
948              If your application needs to interact with these kinds of  files
949              we recommend breaking out those parts to a port program instead.
950
951
952          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
959
960              Typical error reasons:
961
962                enoent:
963                  The file does not exist.
964
965                eacces:
966                  Missing  permission for reading the file or searching one of
967                  the parent directories.
968
969                eisdir:
970                  The named file is a directory.
971
972                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
977                enospc:
978                  There is no space left on the device (if  write  access  was
979                  specified).
980
981       path_consult(Path, Filename) ->
982                       {ok, Terms, FullName} | {error, Reason}
983
984              Types:
985
986                 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
995              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
1000              Returns one of the following:
1001
1002                {ok, Terms, FullName}:
1003                  The file is successfully read. FullName is the full name  of
1004                  the file.
1005
1006                {error, enoent}:
1007                  The file cannot be found in any of the directories in Path.
1008
1009                {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
1013                {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
1018              The encoding of Filename can be set by a comment as described in
1019              epp(3).
1020
1021       path_eval(Path, Filename) -> {ok, FullName} | {error, Reason}
1022
1023              Types:
1024
1025                 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
1033              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
1041              Returns one of the following:
1042
1043                {ok, FullName}:
1044                  The file is read and evaluated. FullName is the full name of
1045                  the file.
1046
1047                {error, enoent}:
1048                  The file cannot be found in any of the directories in Path.
1049
1050                {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
1054                {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
1059              The encoding of Filename can be set by a comment as described in
1060              epp(3).
1061
1062       path_open(Path, Filename, Modes) ->
1063                    {ok, IoDevice, FullName} | {error, Reason}
1064
1065              Types:
1066
1067                 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
1074              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
1079              Returns one of the following:
1080
1081                {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
1086                {error, enoent}:
1087                  The file cannot be found in any of the directories in Path.
1088
1089                {error, atom()}:
1090                  The file cannot be opened.
1091
1092       path_script(Path, Filename) ->
1093                      {ok, Value, FullName} | {error, Reason}
1094
1095              Types:
1096
1097                 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
1106              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
1112              Returns one of the following:
1113
1114                {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
1118                {error, enoent}:
1119                  The file cannot be found in any of the directories in Path.
1120
1121                {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
1125                {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
1130              The encoding of Filename can be set by a comment as described in
1131              epp(3).
1132
1133       path_script(Path, Filename, Bindings) ->
1134                      {ok, Value, FullName} | {error, Reason}
1135
1136              Types:
1137
1138                 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
1148              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
1151       pid2name(Pid) -> {ok, Filename} | undefined
1152
1153              Types:
1154
1155                 Filename = filename_all()
1156                 Pid = pid()
1157
1158              If  Pid  is  an I/O device, that is, a pid returned from open/2,
1159              this function returns the filename, or rather:
1160
1161                {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
1167                undefined:
1168                  In all other cases.
1169
1170          Warning:
1171              This function is intended for debugging only.
1172
1173
1174       position(IoDevice, Location) ->
1175                   {ok, NewPosition} | {error, Reason}
1176
1177              Types:
1178
1179                 IoDevice = io_device()
1180                 Location = location()
1181                 NewPosition = integer()
1182                 Reason = posix() | badarg | terminated
1183
1184              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
1189                Offset:
1190                  The same as {bof, Offset}.
1191
1192                {bof, Offset}:
1193                  Absolute offset.
1194
1195                {cur, Offset}:
1196                  Offset from the current position.
1197
1198                {eof, Offset}:
1199                  Offset from the end of file.
1200
1201                bof | cur | eof:
1202                  The same as above with Offset 0.
1203
1204              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
1214              A typical error reason is:
1215
1216                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
1222       pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason}
1223
1224              Types:
1225
1226                 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
1233              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
1240              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
1245       pread(IoDevice, Location, Number) ->
1246                {ok, Data} | eof | {error, Reason}
1247
1248              Types:
1249
1250                 IoDevice = io_device()
1251                 Location = location()
1252                 Number = integer() >= 0
1253                 Data = string() | binary()
1254                 Reason = posix() | badarg | terminated
1255
1256              Combines  position/2  and read/2 in one operation, which is more
1257              efficient than calling them one at a time.
1258
1259              Location is only allowed to be an integer for raw and ram modes.
1260
1261              The current position of the file after the  operation  is  unde‐
1262              fined for raw mode and unchanged for ram mode.
1263
1264              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
1269       pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}}
1270
1271              Types:
1272
1273                 IoDevice = io_device()
1274                 LocBytes = [{Location :: location(), Bytes :: iodata()}]
1275                 N = integer() >= 0
1276                 Reason = posix() | badarg | terminated
1277
1278              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
1283              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
1287       pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason}
1288
1289              Types:
1290
1291                 IoDevice = io_device()
1292                 Location = location()
1293                 Bytes = iodata()
1294                 Reason = posix() | badarg | terminated
1295
1296              Combines  position/2 and write/2 in one operation, which is more
1297              efficient than calling them one at a time.
1298
1299              Location is only allowed to be an integer for raw and ram modes.
1300
1301              The current position of the file after the  operation  is  unde‐
1302              fined for raw mode and unchanged for ram mode.
1303
1304              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
1308       read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}
1309
1310              Types:
1311
1312                 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
1320              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
1325              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
1331              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
1336              The function returns:
1337
1338                {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
1344                eof:
1345                  Returned if Number>0 and end of file was reached before any‐
1346                  thing at all could be read.
1347
1348                {error, Reason}:
1349                  An error occurred.
1350
1351              Typical error reasons:
1352
1353                ebadf:
1354                  The file is not opened for reading.
1355
1356                {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
1361       read_file(Filename) -> {ok, Binary} | {error, Reason}
1362
1363              Types:
1364
1365                 Filename = name_all()
1366                 Binary = binary()
1367                 Reason = posix() | badarg | terminated | system_limit
1368
1369              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
1373              Typical error reasons:
1374
1375                enoent:
1376                  The file does not exist.
1377
1378                eacces:
1379                  Missing  permission  for  reading the file, or for searching
1380                  one of the parent directories.
1381
1382                eisdir:
1383                  The named file is a directory.
1384
1385                enotdir:
1386                  A component of the filename is  not  a  directory.  On  some
1387                  platforms, enoent is returned instead.
1388
1389                enomem:
1390                  There is not enough memory for the contents of the file.
1391
1392       read_file_info(File) -> {ok, FileInfo} | {error, Reason}
1393
1394       read_file_info(File, Opts) -> {ok, FileInfo} | {error, Reason}
1395
1396              Types:
1397
1398                 File = name_all() | io_device()
1399                 Opts = [file_info_option()]
1400                 FileInfo = file_info()
1401                 Reason = posix() | badarg
1402
1403              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
1409               -include_lib("kernel/include/file.hrl").
1410
1411              The  time  type returned in atime, mtime, and ctime is dependent
1412              on the time type set in Opts :: {time, Type} as follows:
1413
1414                local:
1415                  Returns local time.
1416
1417                universal:
1418                  Returns universal time.
1419
1420                posix:
1421                  Returns seconds since or before Unix time  epoch,  which  is
1422                  1970-01-01 00:00 UTC.
1423
1424              Default is {time, local}.
1425
1426              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
1431              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
1435          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
1439
1440              The record file_info contains the following fields:
1441
1442                size = integer() >= 0:
1443                  Size of file in bytes.
1444
1445                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
1449                access = read | write | read_write | none:
1450                  The current system access to the file.
1451
1452                atime = date_time() | integer() >= 0:
1453                  The last time the file was read.
1454
1455                mtime = date_time() | integer() >= 0:
1456                  The last time the file was written.
1457
1458                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
1463                mode = integer() >= 0:
1464                  The file permissions as the sum of the following bit values:
1465
1466                  8#00400:
1467                    read permission: owner
1468
1469                  8#00200:
1470                    write permission: owner
1471
1472                  8#00100:
1473                    execute permission: owner
1474
1475                  8#00040:
1476                    read permission: group
1477
1478                  8#00020:
1479                    write permission: group
1480
1481                  8#00010:
1482                    execute permission: group
1483
1484                  8#00004:
1485                    read permission: other
1486
1487                  8#00002:
1488                    write permission: other
1489
1490                  8#00001:
1491                    execute permission: other
1492
1493                  16#800:
1494                    set user id on execution
1495
1496                  16#400:
1497                    set group id on execution
1498
1499                  On Unix platforms, other bits than those listed above may be
1500                  set.
1501
1502                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
1506                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
1511                minor_device = integer() >= 0:
1512                  Only valid for character  devices  on  Unix.  In  all  other
1513                  cases, this field is zero.
1514
1515                inode = integer() >= 0:
1516                  Gives the inode number. On non-Unix file systems, this field
1517                  is zero.
1518
1519                uid = integer() >= 0:
1520                  Indicates the owner of the file. On non-Unix  file  systems,
1521                  this field is zero.
1522
1523                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
1527              Typical error reasons:
1528
1529                eacces:
1530                  Missing search permission for one of the parent  directories
1531                  of the file.
1532
1533                enoent:
1534                  The file does not exist.
1535
1536                enotdir:
1537                  A  component  of  the  filename  is not a directory. On some
1538                  platforms, enoent is returned instead.
1539
1540       read_line(IoDevice) -> {ok, Data} | eof | {error, Reason}
1541
1542              Types:
1543
1544                 IoDevice = io_device() | atom()
1545                 Data = string() | binary()
1546                 Reason =
1547                     posix() |
1548                     badarg | terminated |
1549                     {no_translation, unicode, latin1}
1550
1551              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
1561              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
1567              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
1572              The function returns:
1573
1574                {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
1579                  If the file is opened in binary mode, the read bytes are re‐
1580                  turned in a binary, otherwise in a list.
1581
1582                eof:
1583                  Returned if end of file was reached before anything  at  all
1584                  could be read.
1585
1586                {error, Reason}:
1587                  An error occurred.
1588
1589              Typical error reasons:
1590
1591                ebadf:
1592                  The file is not opened for reading.
1593
1594                {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
1599       read_link(Name) -> {ok, Filename} | {error, Reason}
1600
1601              Types:
1602
1603                 Name = name_all()
1604                 Filename = filename()
1605                 Reason = posix() | badarg
1606
1607              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
1612              Typical error reasons:
1613
1614                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
1619                enoent:
1620                  The file does not exist.
1621
1622                enotsup:
1623                  Symbolic links are not supported on this platform.
1624
1625       read_link_all(Name) -> {ok, Filename} | {error, Reason}
1626
1627              Types:
1628
1629                 Name = name_all()
1630                 Filename = filename_all()
1631                 Reason = posix() | badarg
1632
1633              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
1637              Notice that Filename can be either a list or a binary.
1638
1639              Typical error reasons:
1640
1641                einval:
1642                  Name does not refer to a symbolic link.
1643
1644                enoent:
1645                  The file does not exist.
1646
1647                enotsup:
1648                  Symbolic links are not supported on this platform.
1649
1650       read_link_info(Name) -> {ok, FileInfo} | {error, Reason}
1651
1652       read_link_info(Name, Opts) -> {ok, FileInfo} | {error, Reason}
1653
1654              Types:
1655
1656                 Name = name_all()
1657                 Opts = [file_info_option()]
1658                 FileInfo = file_info()
1659                 Reason = posix() | badarg
1660
1661              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
1665              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
1670              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
1675       rename(Source, Destination) -> ok | {error, Reason}
1676
1677              Types:
1678
1679                 Source = Destination = name_all()
1680                 Reason = posix() | badarg
1681
1682              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
1690          Note:
1691              Renaming of open files is not allowed  on  most  platforms  (see
1692              eacces below).
1693
1694
1695              Typical error reasons:
1696
1697                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
1702                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
1707                einval:
1708                  Source is a root directory, or Destination is a subdirectory
1709                  of Source.
1710
1711                eisdir:
1712                  Destination is a directory, but Source is not.
1713
1714                enoent:
1715                  Source does not exist.
1716
1717                enotdir:
1718                  Source is a directory, but Destination is not.
1719
1720                exdev:
1721                  Source and Destination are on different file systems.
1722
1723       script(Filename) -> {ok, Value} | {error, Reason}
1724
1725              Types:
1726
1727                 Filename = name_all()
1728                 Value = term()
1729                 Reason =
1730                     posix() |
1731                     badarg | terminated | system_limit |
1732                     {Line :: integer(), Mod :: module(), Term :: term()}
1733
1734              Reads and evaluates Erlang expressions,  separated  by  '.'  (or
1735              ',',  a sequence of expressions is also an expression), from the
1736              file.
1737
1738              Returns one of the following:
1739
1740                {ok, Value}:
1741                  The file is read and evaluated. Value is the  value  of  the
1742                  last expression.
1743
1744                {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
1748                {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
1753              The encoding of Filename can be set by a comment as described in
1754              epp(3).
1755
1756       script(Filename, Bindings) -> {ok, Value} | {error, Reason}
1757
1758              Types:
1759
1760                 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
1768              The same as script/1 but the variable bindings Bindings are used
1769              in the evaluation. See erl_eval(3) about variable bindings.
1770
1771       sendfile(Filename, Socket) ->
1772                   {ok, integer() >= 0} |
1773                   {error, inet:posix() | closed | badarg | not_owner}
1774
1775              Types:
1776
1777                 Filename = name_all()
1778                 Socket =
1779                     inet:socket() |
1780                     socket:socket() |
1781                     fun((iolist()) -> ok | {error, inet:posix() | closed})
1782
1783              Sends the file Filename to Socket. Returns  {ok,  BytesSent}  if
1784              successful, otherwise {error, Reason}.
1785
1786       sendfile(RawFile, Socket, Offset, Bytes, Opts) ->
1787                   {ok, integer() >= 0} |
1788                   {error, inet:posix() | closed | badarg | not_owner}
1789
1790              Types:
1791
1792                 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
1802              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
1807              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
1812              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
1815              The option list can contain the following options:
1816
1817                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
1822       set_cwd(Dir) -> ok | {error, Reason}
1823
1824              Types:
1825
1826                 Dir = name() | EncodedBinary
1827                 EncodedBinary = binary()
1828                 Reason = posix() | badarg | no_translation
1829
1830              Sets the current working directory of the file  server  to  Dir.
1831              Returns ok if successful.
1832
1833              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
1839              Typical error reasons are:
1840
1841                enoent:
1842                  The directory does not exist.
1843
1844                enotdir:
1845                  A  component  of  Dir is not a directory. On some platforms,
1846                  enoent is returned.
1847
1848                eacces:
1849                  Missing permission for the directory or one of its parents.
1850
1851                badarg:
1852                  Dir has an improper type, such as tuple.
1853
1854                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
1858          Warning:
1859              In  a  future release, a bad type for argument Dir will probably
1860              generate an exception.
1861
1862
1863       sync(IoDevice) -> ok | {error, Reason}
1864
1865              Types:
1866
1867                 IoDevice = io_device()
1868                 Reason = posix() | badarg | terminated
1869
1870              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
1874              A typical error reason is:
1875
1876                enospc:
1877                  Not enough space left to write the file.
1878
1879       truncate(IoDevice) -> ok | {error, Reason}
1880
1881              Types:
1882
1883                 IoDevice = io_device()
1884                 Reason = posix() | badarg | terminated
1885
1886              Truncates the file referenced by IoDevice at the  current  posi‐
1887              tion. Returns ok if successful, otherwise {error, Reason}.
1888
1889       write(IoDevice, Bytes) -> ok | {error, Reason}
1890
1891              Types:
1892
1893                 IoDevice = io_device() | atom()
1894                 Bytes = iodata()
1895                 Reason = posix() | badarg | terminated
1896
1897              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
1902              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
1908              Typical error reasons:
1909
1910                ebadf:
1911                  The file is not opened for writing.
1912
1913                enospc:
1914                  No space is left on the device.
1915
1916       write_file(Filename, Bytes) -> ok | {error, Reason}
1917
1918              Types:
1919
1920                 Filename = name_all()
1921                 Bytes = iodata()
1922                 Reason = posix() | badarg | terminated | system_limit
1923
1924              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
1929              Typical error reasons:
1930
1931                enoent:
1932                  A component of the filename does not exist.
1933
1934                enotdir:
1935                  A  component  of  the  filename  is not a directory. On some
1936                  platforms, enoent is returned instead.
1937
1938                enospc:
1939                  No space is left on the device.
1940
1941                eacces:
1942                  Missing permission for writing the file or searching one  of
1943                  the parent directories.
1944
1945                eisdir:
1946                  The named file is a directory.
1947
1948       write_file(Filename, Bytes, Modes) -> ok | {error, Reason}
1949
1950              Types:
1951
1952                 Filename = name_all()
1953                 Bytes = iodata()
1954                 Modes = [mode()]
1955                 Reason = posix() | badarg | terminated | system_limit
1956
1957              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
1961       write_file_info(Filename, FileInfo) -> ok | {error, Reason}
1962
1963       write_file_info(Filename, FileInfo, Opts) -> ok | {error, Reason}
1964
1965              Types:
1966
1967                 Filename = name_all()
1968                 Opts = [file_info_option()]
1969                 FileInfo = file_info()
1970                 Reason = posix() | badarg
1971
1972              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
1977               -include_lib("kernel/include/file.hrl").
1978
1979              The time type set in atime, mtime, and ctime depends on the time
1980              type set in Opts :: {time, Type} as follows:
1981
1982                local:
1983                  Interprets the time set as local.
1984
1985                universal:
1986                  Interprets it as universal time.
1987
1988                posix:
1989                  Must  be  seconds  since or before Unix time epoch, which is
1990                  1970-01-01 00:00 UTC.
1991
1992              Default is {time, local}.
1993
1994              If the option raw is set, the file server is not called and only
1995              information about local files is returned.
1996
1997              The following fields are used from the record, if they are spec‐
1998              ified:
1999
2000                atime = date_time() | integer() >= 0:
2001                  The last time the file was read.
2002
2003                mtime = date_time() | integer() >= 0:
2004                  The last time the file was written.
2005
2006                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
2012                mode = integer() >= 0:
2013                  The file permissions as the sum of the following bit values:
2014
2015                  8#00400:
2016                    Read permission: owner
2017
2018                  8#00200:
2019                    Write permission: owner
2020
2021                  8#00100:
2022                    Execute permission: owner
2023
2024                  8#00040:
2025                    Read permission: group
2026
2027                  8#00020:
2028                    Write permission: group
2029
2030                  8#00010:
2031                    Execute permission: group
2032
2033                  8#00004:
2034                    Read permission: other
2035
2036                  8#00002:
2037                    Write permission: other
2038
2039                  8#00001:
2040                    Execute permission: other
2041
2042                  16#800:
2043                    Set user id on execution
2044
2045                  16#400:
2046                    Set group id on execution
2047
2048                  On Unix platforms, other bits than those listed above may be
2049                  set.
2050
2051                uid = integer() >= 0:
2052                  Indicates the file owner. Ignored for non-Unix file systems.
2053
2054                gid = integer() >= 0:
2055                  Gives the group that the file owner belongs to. Ignored  for
2056                  non-Unix file systems.
2057
2058              Typical error reasons:
2059
2060                eacces:
2061                  Missing  search permission for one of the parent directories
2062                  of the file.
2063
2064                enoent:
2065                  The file does not exist.
2066
2067                enotdir:
2068                  A component of the filename is  not  a  directory.  On  some
2069                  platforms, enoent is returned instead.
2070

POSIX ERROR CODES

2072         * eacces - Permission denied
2073
2074         * eagain - Resource temporarily unavailable
2075
2076         * ebadf - Bad file number
2077
2078         * ebusy - File busy
2079
2080         * edquot - Disk quota exceeded
2081
2082         * eexist - File already exists
2083
2084         * efault - Bad address in system call argument
2085
2086         * efbig - File too large
2087
2088         * eintr - Interrupted system call
2089
2090         * einval - Invalid argument
2091
2092         * eio - I/O error
2093
2094         * eisdir - Illegal operation on a directory
2095
2096         * eloop - Too many levels of symbolic links
2097
2098         * emfile - Too many open files
2099
2100         * emlink - Too many links
2101
2102         * enametoolong - Filename too long
2103
2104         * enfile - File table overflow
2105
2106         * enodev - No such device
2107
2108         * enoent - No such file or directory
2109
2110         * enomem - Not enough memory
2111
2112         * enospc - No space left on device
2113
2114         * enotblk - Block device required
2115
2116         * enotdir - Not a directory
2117
2118         * enotsup - Operation not supported
2119
2120         * enxio - No such device or address
2121
2122         * eperm - Not owner
2123
2124         * epipe - Broken pipe
2125
2126         * erofs - Read-only file system
2127
2128         * espipe - Invalid seek
2129
2130         * esrch - No such process
2131
2132         * estale - Stale remote file handle
2133
2134         * exdev - Cross-domain link
2135

PERFORMANCE

2137       For increased performance, raw files are recommended.
2138
2139       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
2147   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
2154
2155       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
2162       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
2167       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
2173       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
2177       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
2183       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
2192       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
2200   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
2206

SEE ALSO

2208       filename(3)
2209
2210
2211
2212Ericsson AB                     kernel 8.5.4.2                         file(3)
Impressum