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 and  MacOS  X
29       enforce  consistent  filename  encoding  and therefore the VM uses utf8
30       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
84              allowed  to  be  >  255.  See  also  the  documentation  of  the
85              name_all() 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 |
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
178              operating 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. When it succeeds, space is preallocated for the  file  but
193              the  file  size  might not be updated. This behaviour depends on
194              the preallocation implementation. To  guarantee  that  the  file
195              size is updated, truncate the file to the new size.
196
197       change_group(Filename, Gid) -> ok | {error, Reason}
198
199              Types:
200
201                 Filename = name_all()
202                 Gid = integer()
203                 Reason = posix() | badarg
204
205              Changes group of a file. See write_file_info/2.
206
207       change_mode(Filename, Mode) -> ok | {error, Reason}
208
209              Types:
210
211                 Filename = name_all()
212                 Mode = integer()
213                 Reason = posix() | badarg
214
215              Changes permissions of a file. See write_file_info/2.
216
217       change_owner(Filename, Uid) -> ok | {error, Reason}
218
219              Types:
220
221                 Filename = name_all()
222                 Uid = integer()
223                 Reason = posix() | badarg
224
225              Changes owner of a file. See write_file_info/2.
226
227       change_owner(Filename, Uid, Gid) -> ok | {error, Reason}
228
229              Types:
230
231                 Filename = name_all()
232                 Uid = Gid = integer()
233                 Reason = posix() | badarg
234
235              Changes owner and group of a file. See write_file_info/2.
236
237       change_time(Filename, Mtime) -> ok | {error, Reason}
238
239              Types:
240
241                 Filename = name_all()
242                 Mtime = date_time()
243                 Reason = posix() | badarg
244
245              Changes  the  modification  and  access  times  of  a  file. See
246              write_file_info/2.
247
248       change_time(Filename, Atime, Mtime) -> ok | {error, Reason}
249
250              Types:
251
252                 Filename = name_all()
253                 Atime = Mtime = date_time()
254                 Reason = posix() | badarg
255
256              Changes the modification and last access times of  a  file.  See
257              write_file_info/2.
258
259       close(IoDevice) -> ok | {error, Reason}
260
261              Types:
262
263                 IoDevice = io_device()
264                 Reason = posix() | badarg | terminated
265
266              Closes  the  file  referenced by IoDevice. It mostly returns ok,
267              except for some severe errors such as out of memory.
268
269              Notice that if option delayed_write was used  when  opening  the
270              file,  close/1 can return an old write error and not even try to
271              close the file. See open/2.
272
273       consult(Filename) -> {ok, Terms} | {error, Reason}
274
275              Types:
276
277                 Filename = name_all()
278                 Terms = [term()]
279                 Reason =
280                     posix() |
281                     badarg | terminated | system_limit |
282                     {Line :: integer(), Mod :: module(), Term :: term()}
283
284              Reads Erlang terms, separated by '.', from Filename. Returns one
285              of the following:
286
287                {ok, Terms}:
288                  The file was successfully read.
289
290                {error, atom()}:
291                  An error occurred when opening the file or reading it. For a
292                  list of typical error codes, see open/2.
293
294                {error, {Line, Mod, Term}}:
295                  An error occurred when interpreting the Erlang terms in  the
296                  file.  To  convert  the  three-element  tuple  to an English
297                  description of the error, use format_error/1.
298
299              Example:
300
301              f.txt:  {person, "kalle", 25}.
302                      {person, "pelle", 30}.
303
304              1> file:consult("f.txt").
305              {ok,[{person,"kalle",25},{person,"pelle",30}]}
306
307              The encoding of Filename can be set by a comment,  as  described
308              in epp(3).
309
310       copy(Source, Destination) -> {ok, BytesCopied} | {error, Reason}
311
312       copy(Source, Destination, ByteCount) ->
313               {ok, BytesCopied} | {error, Reason}
314
315              Types:
316
317                 Source  =  Destination  = io_device() | Filename | {Filename,
318                 Modes}
319                 Filename = name_all()
320                 Modes = [mode()]
321                 ByteCount = integer() >= 0 | infinity
322                 BytesCopied = integer() >= 0
323                 Reason = posix() | badarg | terminated
324
325              Copies ByteCount bytes from Source to  Destination.  Source  and
326              Destination  refer  to  either filenames or IO devices from, for
327              example, open/2. ByteCount defaults  to  infinity,  denoting  an
328              infinite number of bytes.
329
330              Argument  Modes  is  a  list  of possible modes, see open/2, and
331              defaults to [].
332
333              If both Source and Destination refer to filenames, the files are
334              opened  with  [read,  binary]  and  [write, binary] prepended to
335              their mode lists, respectively, to optimize the copy.
336
337              If Source refers to a filename, it  is  opened  with  read  mode
338              prepended  to  the  mode  list  before the copy, and closed when
339              done.
340
341              If Destination refers to a filename, it  is  opened  with  write
342              mode prepended to the mode list before the copy, and closed when
343              done.
344
345              Returns {ok, BytesCopied}, where BytesCopied is  the  number  of
346              bytes  that  was copied, which can be less than ByteCount if end
347              of file was encountered on the source. If the  operation  fails,
348              {error, Reason} is returned.
349
350              Typical error reasons: as for open/2 if a file had to be opened,
351              and as for read/2 and write/2.
352
353       datasync(IoDevice) -> ok | {error, Reason}
354
355              Types:
356
357                 IoDevice = io_device()
358                 Reason = posix() | badarg | terminated
359
360              Ensures that any buffers kept by the operating  system  (not  by
361              the  Erlang runtime system) are written to disk. In many ways it
362              resembles fsync but it does not update some of the  metadata  of
363              the  file, such as the access time. On some platforms this func‐
364              tion has no effect.
365
366              Applications that access databases or log files  often  write  a
367              tiny  data  fragment  (for  example, one line in a log file) and
368              then call fsync() immediately to ensure that the written data is
369              physically  stored  on  the  hard  disk.  Unfortunately, fsync()
370              always initiates two write operations: one for the newly written
371              data  and  another one to update the modification time stored in
372              the inode. If the modification time is not a part of the  trans‐
373              action  concept,  fdatasync()  can  be used to avoid unnecessary
374              inode disk write operations.
375
376              Available only in some POSIX systems, this  call  results  in  a
377              call  to  fsync(), or has no effect in systems not providing the
378              fdatasync() syscall.
379
380       del_dir(Dir) -> ok | {error, Reason}
381
382              Types:
383
384                 Dir = name_all()
385                 Reason = posix() | badarg
386
387              Tries to delete directory  Dir.  The  directory  must  be  empty
388              before it can be deleted. Returns ok if successful.
389
390              Typical error reasons:
391
392                eacces:
393                  Missing  search or write permissions for the parent directo‐
394                  ries of Dir.
395
396                eexist:
397                  The directory is not empty.
398
399                enoent:
400                  The directory does not exist.
401
402                enotdir:
403                  A component of Dir is not a directory.  On  some  platforms,
404                  enoent is returned instead.
405
406                einval:
407                  Attempt  to delete the current directory. On some platforms,
408                  eacces is returned instead.
409
410       delete(Filename) -> ok | {error, Reason}
411
412              Types:
413
414                 Filename = name_all()
415                 Reason = posix() | badarg
416
417              Tries to delete file Filename. Returns ok if successful.
418
419              Typical error reasons:
420
421                enoent:
422                  The file does not exist.
423
424                eacces:
425                  Missing permission for the file or one of its parents.
426
427                eperm:
428                  The file is a directory and the user is not superuser.
429
430                enotdir:
431                  A component of the filename is  not  a  directory.  On  some
432                  platforms, enoent is returned instead.
433
434                einval:
435                  Filename has an improper type, such as tuple.
436
437          Warning:
438              In a future release, a bad type for argument Filename will prob‐
439              ably generate an exception.
440
441
442       eval(Filename) -> ok | {error, Reason}
443
444              Types:
445
446                 Filename = name_all()
447                 Reason =
448                     posix() |
449                     badarg | terminated | system_limit |
450                     {Line :: integer(), Mod :: module(), Term :: term()}
451
452              Reads and evaluates Erlang expressions,  separated  by  '.'  (or
453              ',', a sequence of expressions is also an expression) from File‐
454              name. The result of the evaluation is not returned; any  expres‐
455              sion  sequence  in  the  file must be there for its side effect.
456              Returns one of the following:
457
458                ok:
459                  The file was read and evaluated.
460
461                {error, atom()}:
462                  An error occurred when opening the file or reading it. For a
463                  list of typical error codes, see open/2.
464
465                {error, {Line, Mod, Term}}:
466                  An  error  occurred when interpreting the Erlang expressions
467                  in the file. To convert the three-element tuple to  an  Eng‐
468                  lish description of the error, use format_error/1.
469
470              The  encoding  of Filename can be set by a comment, as described
471              in epp(3).
472
473       eval(Filename, Bindings) -> ok | {error, Reason}
474
475              Types:
476
477                 Filename = name_all()
478                 Bindings = erl_eval:binding_struct()
479                 Reason =
480                     posix() |
481                     badarg | terminated | system_limit |
482                     {Line :: integer(), Mod :: module(), Term :: term()}
483
484              The same as eval/1, but the variable bindings Bindings are  used
485              in  the evaluation. For information about the variable bindings,
486              see erl_eval(3).
487
488       format_error(Reason) -> Chars
489
490              Types:
491
492                 Reason =
493                     posix() |
494                     badarg | terminated | system_limit |
495                     {Line :: integer(), Mod :: module(), Term :: term()}
496                 Chars = string()
497
498              Given the error reason returned by any function in this  module,
499              returns a descriptive string of the error in English.
500
501       get_cwd() -> {ok, Dir} | {error, Reason}
502
503              Types:
504
505                 Dir = filename()
506                 Reason = posix()
507
508              Returns {ok, Dir}, where Dir is the current working directory of
509              the file server.
510
511          Note:
512              In rare circumstances, this function can fail on  Unix.  It  can
513              occur  if read permission does not exist for the parent directo‐
514              ries of the current directory.
515
516
517              A typical error reason:
518
519                eacces:
520                  Missing read permission for one of the parents of  the  cur‐
521                  rent directory.
522
523       get_cwd(Drive) -> {ok, Dir} | {error, Reason}
524
525              Types:
526
527                 Drive = string()
528                 Dir = filename()
529                 Reason = posix() | badarg
530
531              Returns  {ok,  Dir} or {error, Reason}, where Dir is the current
532              working directory of the specified drive.
533
534              Drive is to be of the form "Letter:", for example, "c:".
535
536              Returns {error, enotsup} on platforms that have  no  concept  of
537              current drive (Unix, for example).
538
539              Typical error reasons:
540
541                enotsup:
542                  The operating system has no concept of drives.
543
544                eacces:
545                  The drive does not exist.
546
547                einval:
548                  The format of Drive is invalid.
549
550       list_dir(Dir) -> {ok, Filenames} | {error, Reason}
551
552              Types:
553
554                 Dir = name_all()
555                 Filenames = [filename()]
556                 Reason =
557                     posix() |
558                     badarg |
559                     {no_translation, Filename :: unicode:latin1_binary()}
560
561              Lists all files in a directory, except files with raw filenames.
562              Returns {ok, Filenames} if successful,  otherwise  {error,  Rea‐
563              son}.  Filenames  is a list of the names of all the files in the
564              directory. The names are not sorted.
565
566              Typical error reasons:
567
568                eacces:
569                  Missing search or write permissions for Dir or  one  of  its
570                  parent directories.
571
572                enoent:
573                  The directory does not exist.
574
575                {no_translation, Filename}:
576                  Filename  is a binary() with characters coded in ISO Latin-1
577                  and the VM was started with parameter +fnue.
578
579       list_dir_all(Dir) -> {ok, Filenames} | {error, Reason}
580
581              Types:
582
583                 Dir = name_all()
584                 Filenames = [filename_all()]
585                 Reason = posix() | badarg
586
587              Lists all the files in a directory,  including  files  with  raw
588              filenames.  Returns  {ok,  Filenames}  if  successful, otherwise
589              {error, Reason}. Filenames is a list of the  names  of  all  the
590              files in the directory. The names are not sorted.
591
592              Typical error reasons:
593
594                eacces:
595                  Missing  search  or  write permissions for Dir or one of its
596                  parent directories.
597
598                enoent:
599                  The directory does not exist.
600
601       make_dir(Dir) -> ok | {error, Reason}
602
603              Types:
604
605                 Dir = name_all()
606                 Reason = posix() | badarg
607
608              Tries to create directory Dir. Missing  parent  directories  are
609              not created. Returns ok if successful.
610
611              Typical error reasons:
612
613                eacces:
614                  Missing  search or write permissions for the parent directo‐
615                  ries of Dir.
616
617                eexist:
618                  A file or directory named Dir exists already.
619
620                enoent:
621                  A component of Dir does not exist.
622
623                enospc:
624                  No space is left on the device.
625
626                enotdir:
627                  A component of Dir is not a directory.  On  some  platforms,
628                  enoent is returned instead.
629
630       make_link(Existing, New) -> ok | {error, Reason}
631
632              Types:
633
634                 Existing = New = name_all()
635                 Reason = posix() | badarg
636
637              Makes  a  hard link from Existing to New on platforms supporting
638              links (Unix and Windows). This function returns ok if  the  link
639              was  successfully  created,  otherwise {error, Reason}. On plat‐
640              forms not supporting links, {error,enotsup} is returned.
641
642              Typical error reasons:
643
644                eacces:
645                  Missing read or write permissions for the parent directories
646                  of Existing or New.
647
648                eexist:
649                  New already exists.
650
651                enotsup:
652                  Hard links are not supported on this platform.
653
654       make_symlink(Existing, New) -> ok | {error, Reason}
655
656              Types:
657
658                 Existing = New = name_all()
659                 Reason = posix() | badarg
660
661              Creates a symbolic link New to the file or directory Existing on
662              platforms supporting symbolic links (most Unix systems and  Win‐
663              dows,  beginning  with  Vista). Existing does not need to exist.
664              Returns ok  if  the  link  is  successfully  created,  otherwise
665              {error,  Reason}.  On  platforms  not supporting symbolic links,
666              {error, enotsup} is returned.
667
668              Typical error reasons:
669
670                eacces:
671                  Missing read or write permissions for the parent directories
672                  of Existing or New.
673
674                eexist:
675                  New already exists.
676
677                enotsup:
678                  Symbolic links are not supported on this platform.
679
680                eperm:
681                  User  does  not  have  privileges  to  create symbolic links
682                  (SeCreateSymbolicLinkPrivilege on Windows).
683
684       native_name_encoding() -> latin1 | utf8
685
686              Returns the filename encoding mode. If it is latin1, the  system
687              translates  no filenames. If it is utf8, filenames are converted
688              back and forth to the native filename encoding  (usually  UTF-8,
689              but UTF-16 on Windows).
690
691       open(File, Modes) -> {ok, IoDevice} | {error, Reason}
692
693              Types:
694
695                 File = Filename | iodata()
696                 Filename = name_all()
697                 Modes = [mode() | ram]
698                 IoDevice = io_device()
699                 Reason = posix() | badarg | system_limit
700
701              Opens  file File in the mode determined by Modes, which can con‐
702              tain one or more of the following options:
703
704                read:
705                  The file, which must exist, is opened for reading.
706
707                write:
708                  The file is opened for writing. It is created if it does not
709                  exist.  If  the  file  exists and write is not combined with
710                  read, the file is truncated.
711
712                append:
713                  The file is opened for writing. It is created if it does not
714                  exist.  Every  write  operation to a file opened with append
715                  takes place at the end of the file.
716
717                exclusive:
718                  The file is opened for writing. It is created if it does not
719                  exist. If the file exists, {error, eexist} is returned.
720
721            Warning:
722                This  option  does not guarantee exclusiveness on file systems
723                not supporting O_EXCL properly, such as NFS. Do not depend  on
724                this  option  unless you know that the file system supports it
725                (in general, local file systems are safe).
726
727
728                raw:
729                  Allows faster access to a file,  as  no  Erlang  process  is
730                  needed  to  handle  the file. However, a file opened in this
731                  way has the following limitations:
732
733                  * The functions in the io module cannot be used, as they can
734                    only  talk  to  an  Erlang process. Instead, use functions
735                    read/2, read_line/1, and write/2.
736
737                  * Especially if read_line/1 is to be used on a raw file,  it
738                    is   recommended   to  combine  this  option  with  option
739                    {read_ahead, Size} as  line-oriented  I/O  is  inefficient
740                    without buffering.
741
742                  * Only the Erlang process that opened the file can use it.
743
744                  * A  remote  Erlang file server cannot be used. The computer
745                    on which the Erlang node is running must  have  access  to
746                    the file system (directly or through NFS).
747
748                binary:
749                  Read  operations  on  the  file  return binaries rather than
750                  lists.
751
752                {delayed_write, Size, Delay}:
753                  Data in subsequent write/2 calls is buffered until at  least
754                  Size  bytes  are buffered, or until the oldest buffered data
755                  is Delay milliseconds old. Then all buffered data is written
756                  in  one  operating  system  call.  The buffered data is also
757                  flushed before some other file  operation  than  write/2  is
758                  executed.
759
760                  The  purpose  of  this  option is to increase performance by
761                  reducing the number of operating  system  calls.  Thus,  the
762                  write/2  calls  must  be  for  sizes significantly less than
763                  Size, and not interspersed by too  many  other  file  opera‐
764                  tions.
765
766                  When  this  option  is used, the result of write/2 calls can
767                  prematurely be reported as successful, and if a write  error
768                  occurs, the error is reported as the result of the next file
769                  operation, which is not executed.
770
771                  For example, when delayed_write is used, after a  number  of
772                  write/2  calls, close/1 can return {error, enospc}, as there
773                  is not enough space on the disc for previously written data.
774                  close/1  must probably be called again, as the file is still
775                  open.
776
777                delayed_write:
778                  The same as {delayed_write,  Size,  Delay}  with  reasonable
779                  default  values  for  Size  and Delay (roughly some 64 KB, 2
780                  seconds).
781
782                {read_ahead, Size}:
783                  Activates read data buffering. If read/2 calls are for  sig‐
784                  nificantly  less  than  Size  bytes,  read operations to the
785                  operating system are still  performed  for  blocks  of  Size
786                  bytes. The extra data is buffered and returned in subsequent
787                  read/2 calls, giving a performance gain  as  the  number  of
788                  operating system calls is reduced.
789
790                  The  read_ahead  buffer  is  also  highly  used  by function
791                  read_line/1 in raw mode, therefore  this  option  is  recom‐
792                  mended  (for  performance  reasons) when accessing raw files
793                  using that function.
794
795                  If read/2 calls are for sizes not significantly  less  than,
796                  or  even greater than Size bytes, no performance gain can be
797                  expected.
798
799                read_ahead:
800                  The same as {read_ahead, Size}  with  a  reasonable  default
801                  value for Size (roughly some 64 KB).
802
803                compressed:
804                  Makes  it  possible  to read or write gzip compressed files.
805                  Option compressed must be combined with read or  write,  but
806                  not   both.   Notice   that  the  file  size  obtained  with
807                  read_file_info/1 does probably not match the number of bytes
808                  that can be read from a compressed file.
809
810                {encoding, Encoding}:
811                  Makes  the  file perform automatic translation of characters
812                  to and from a specific (Unicode) encoding. Notice  that  the
813                  data  supplied  to  write/2  or  returned by read/2 still is
814                  byte-oriented; this option denotes only how data  is  stored
815                  in the disk file.
816
817                  Depending  on the encoding, different methods of reading and
818                  writing data is preferred. The default  encoding  of  latin1
819                  implies  using  this  module  (file) for reading and writing
820                  data as the interfaces provided here work with byte-oriented
821                  data.  Using other (Unicode) encodings makes the io(3) func‐
822                  tions get_chars, get_line, and put_chars more  suitable,  as
823                  they can work with the full Unicode range.
824
825                  If data is sent to an io_device() in a format that cannot be
826                  converted to the specified encoding, or if data is read by a
827                  function that returns data in a format that cannot cope with
828                  the character range of the data, an  error  occurs  and  the
829                  file is closed.
830
831                  Allowed values for Encoding:
832
833                  latin1:
834                    The default encoding. Bytes supplied to the file, that is,
835                    write/2 are written "as is" on the file.  Likewise,  bytes
836                    read  from the file, that is, read/2 are returned "as is".
837                    If module io(3) is used for writing,  the  file  can  only
838                    cope with Unicode characters up to code point 255 (the ISO
839                    Latin-1 range).
840
841                  unicode or utf8:
842                    Characters are  translated  to  and  from  UTF-8  encoding
843                    before  they  are written to or read from the file. A file
844                    opened in this way can be readable using function  read/2,
845                    as  long as no data stored on the file lies beyond the ISO
846                    Latin-1 range (0..255), but failure  occurs  if  the  data
847                    contains  Unicode  code points beyond that range. The file
848                    is best read with the functions in the Unicode aware  mod‐
849                    ule io(3).
850
851                    Bytes  written  to the file by any means are translated to
852                    UTF-8 encoding before being stored on the disk file.
853
854                  utf16 or {utf16,big}:
855                    Works like unicode, but translation is done  to  and  from
856                    big endian UTF-16 instead of UTF-8.
857
858                  {utf16,little}:
859                    Works  like  unicode,  but translation is done to and from
860                    little endian UTF-16 instead of UTF-8.
861
862                  utf32 or {utf32,big}:
863                    Works like unicode, but translation is done  to  and  from
864                    big endian UTF-32 instead of UTF-8.
865
866                  {utf32,little}:
867                    Works  like  unicode,  but translation is done to and from
868                    little endian UTF-32 instead of UTF-8.
869
870                  The Encoding can be changed for a file "on the fly" by using
871                  function  io:setopts/2.  So a file can be analyzed in latin1
872                  encoding for, for example, a BOM, positioned beyond the  BOM
873                  and  then be set for the right encoding before further read‐
874                  ing. For functions identifying BOMs, see module unicode(3).
875
876                  This option is not allowed on raw files.
877
878                ram:
879                  File must be iodata(). Returns an fd(),  which  lets  module
880                  file operate on the data in-memory as if it is a file.
881
882                sync:
883                  On  platforms  supporting  it, enables the POSIX O_SYNC syn‐
884                  chronous I/O flag or its platform-dependent equivalent  (for
885                  example,  FILE_FLAG_WRITE_THROUGH on Windows) so that writes
886                  to the file block until the data is  physically  written  to
887                  disk.  However,  be  aware  that the exact semantics of this
888                  flag differ from platform to platform. For example, none  of
889                  Linux  or Windows guarantees that all file metadata are also
890                  written before the  call  returns.  For  precise  semantics,
891                  check  the  details of your platform documentation. On plat‐
892                  forms with no support for POSIX O_SYNC or equivalent, use of
893                  the sync flag causes open to return {error, enotsup}.
894
895              Returns:
896
897                {ok, IoDevice}:
898                  The file is opened in the requested mode. IoDevice is a ref‐
899                  erence to the file.
900
901                {error, Reason}:
902                  The file cannot be opened.
903
904              IoDevice is really the pid of the process that handles the file.
905              This process is linked to the process that originally opened the
906              file. If any process to which the IoDevice is linked terminates,
907              the  file  is  closed  and  the process itself is terminated. An
908              IoDevice returned from this call can be used as an  argument  to
909              the I/O functions (see io(3)).
910
911          Note:
912              In previous versions of file, modes were specified as one of the
913              atoms read, write, or read_write instead  of  a  list.  This  is
914              still allowed for reasons of backwards compatibility, but is not
915              to be used for new  code.  Also  note  that  read_write  is  not
916              allowed in a mode list.
917
918
919              Typical error reasons:
920
921                enoent:
922                  The file does not exist.
923
924                eacces:
925                  Missing  permission for reading the file or searching one of
926                  the parent directories.
927
928                eisdir:
929                  The named file is a directory.
930
931                enotdir:
932                  A component of the filename is  not  a  directory.  On  some
933                  platforms, enoent is returned instead.
934
935                enospc:
936                  There  is  no  space left on the device (if write access was
937                  specified).
938
939       path_consult(Path, Filename) ->
940                       {ok, Terms, FullName} | {error, Reason}
941
942              Types:
943
944                 Path = [Dir]
945                 Dir = Filename = name_all()
946                 Terms = [term()]
947                 FullName = filename_all()
948                 Reason =
949                     posix() |
950                     badarg | terminated | system_limit |
951                     {Line :: integer(), Mod :: module(), Term :: term()}
952
953              Searches the path Path (a list of  directory  names)  until  the
954              file  Filename  is  found.  If Filename is an absolute filename,
955              Path is ignored. Then reads Erlang terms, separated by '.', from
956              the file.
957
958              Returns one of the following:
959
960                {ok, Terms, FullName}:
961                  The  file is successfully read. FullName is the full name of
962                  the file.
963
964                {error, enoent}:
965                  The file cannot be found in any of the directories in Path.
966
967                {error, atom()}:
968                  An error occurred when opening the file or reading it. For a
969                  list of typical error codes, see open/2.
970
971                {error, {Line, Mod, Term}}:
972                  An  error occurred when interpreting the Erlang terms in the
973                  file. Use format_error/1 to convert the three-element  tuple
974                  to an English description of the error.
975
976              The encoding of Filename can be set by a comment as described in
977              epp(3).
978
979       path_eval(Path, Filename) -> {ok, FullName} | {error, Reason}
980
981              Types:
982
983                 Path = [Dir :: name_all()]
984                 Filename = name_all()
985                 FullName = filename_all()
986                 Reason =
987                     posix() |
988                     badarg | terminated | system_limit |
989                     {Line :: integer(), Mod :: module(), Term :: term()}
990
991              Searches the path Path (a list of  directory  names)  until  the
992              file  Filename  is  found.  If Filename is an absolute filename,
993              Path is ignored. Then reads and  evaluates  Erlang  expressions,
994              separated  by  '.' (or ',', a sequence of expressions is also an
995              expression), from the file. The  result  of  evaluation  is  not
996              returned;  any expression sequence in the file must be there for
997              its side effect.
998
999              Returns one of the following:
1000
1001                {ok, FullName}:
1002                  The file is read and evaluated. FullName is the full name of
1003                  the file.
1004
1005                {error, enoent}:
1006                  The file cannot be found in any of the directories in Path.
1007
1008                {error, atom()}:
1009                  An error occurred when opening the file or reading it. For a
1010                  list of typical error codes, see open/2.
1011
1012                {error, {Line, Mod, Term}}:
1013                  An error occurred when interpreting the  Erlang  expressions
1014                  in the file. Use format_error/1 to convert the three-element
1015                  tuple to an English description of the error.
1016
1017              The encoding of Filename can be set by a comment as described in
1018              epp(3).
1019
1020       path_open(Path, Filename, Modes) ->
1021                    {ok, IoDevice, FullName} | {error, Reason}
1022
1023              Types:
1024
1025                 Path = [Dir :: name_all()]
1026                 Filename = name_all()
1027                 Modes = [mode()]
1028                 IoDevice = io_device()
1029                 FullName = filename_all()
1030                 Reason = posix() | badarg | system_limit
1031
1032              Searches  the  path  Path  (a list of directory names) until the
1033              file Filename is found. If Filename  is  an  absolute  filename,
1034              Path  is  ignored. Then opens the file in the mode determined by
1035              Modes.
1036
1037              Returns one of the following:
1038
1039                {ok, IoDevice, FullName}:
1040                  The file is opened in the requested mode. IoDevice is a ref‐
1041                  erence  to  the  file  and  FullName is the full name of the
1042                  file.
1043
1044                {error, enoent}:
1045                  The file cannot be found in any of the directories in Path.
1046
1047                {error, atom()}:
1048                  The file cannot be opened.
1049
1050       path_script(Path, Filename) ->
1051                      {ok, Value, FullName} | {error, Reason}
1052
1053              Types:
1054
1055                 Path = [Dir :: name_all()]
1056                 Filename = name_all()
1057                 Value = term()
1058                 FullName = filename_all()
1059                 Reason =
1060                     posix() |
1061                     badarg | terminated | system_limit |
1062                     {Line :: integer(), Mod :: module(), Term :: term()}
1063
1064              Searches the path Path (a list of  directory  names)  until  the
1065              file  Filename  is  found.  If Filename is an absolute filename,
1066              Path is ignored. Then reads and  evaluates  Erlang  expressions,
1067              separated  by  '.' (or ',', a sequence of expressions is also an
1068              expression), from the file.
1069
1070              Returns one of the following:
1071
1072                {ok, Value, FullName}:
1073                  The file is read and evaluated. FullName is the full name of
1074                  the file and Value the value of the last expression.
1075
1076                {error, enoent}:
1077                  The file cannot be found in any of the directories in Path.
1078
1079                {error, atom()}:
1080                  An error occurred when opening the file or reading it. For a
1081                  list of typical error codes, see open/2.
1082
1083                {error, {Line, Mod, Term}}:
1084                  An error occurred when interpreting the  Erlang  expressions
1085                  in the file. Use format_error/1 to convert the three-element
1086                  tuple to an English description of the error.
1087
1088              The encoding of Filename can be set by a comment as described in
1089              epp(3).
1090
1091       path_script(Path, Filename, Bindings) ->
1092                      {ok, Value, FullName} | {error, Reason}
1093
1094              Types:
1095
1096                 Path = [Dir :: name_all()]
1097                 Filename = name_all()
1098                 Bindings = erl_eval:binding_struct()
1099                 Value = term()
1100                 FullName = filename_all()
1101                 Reason =
1102                     posix() |
1103                     badarg | terminated | system_limit |
1104                     {Line :: integer(), Mod :: module(), Term :: term()}
1105
1106              The same as path_script/2 but the variable bindings Bindings are
1107              used in the evaluation. See erl_eval(3) about variable bindings.
1108
1109       pid2name(Pid) -> {ok, Filename} | undefined
1110
1111              Types:
1112
1113                 Filename = filename_all()
1114                 Pid = pid()
1115
1116              If Pid is an I/O device, that is, a pid  returned  from  open/2,
1117              this function returns the filename, or rather:
1118
1119                {ok, Filename}:
1120                  If the file server of this node is not a slave, the file was
1121                  opened by the file server of this node  (this  implies  that
1122                  Pid  must  be a local pid) and the file is not closed. File‐
1123                  name is the filename in flat string format.
1124
1125                undefined:
1126                  In all other cases.
1127
1128          Warning:
1129              This function is intended for debugging only.
1130
1131
1132       position(IoDevice, Location) ->
1133                   {ok, NewPosition} | {error, Reason}
1134
1135              Types:
1136
1137                 IoDevice = io_device()
1138                 Location = location()
1139                 NewPosition = integer()
1140                 Reason = posix() | badarg | terminated
1141
1142              Sets the position of the file referenced by  IoDevice  to  Loca‐
1143              tion. Returns {ok, NewPosition} (as absolute offset) if success‐
1144              ful, otherwise {error, Reason}. Location is one of  the  follow‐
1145              ing:
1146
1147                Offset:
1148                  The same as {bof, Offset}.
1149
1150                {bof, Offset}:
1151                  Absolute offset.
1152
1153                {cur, Offset}:
1154                  Offset from the current position.
1155
1156                {eof, Offset}:
1157                  Offset from the end of file.
1158
1159                bof | cur | eof:
1160                  The same as above with Offset 0.
1161
1162              Notice  that offsets are counted in bytes, not in characters. If
1163              the file is opened using some other encoding  than  latin1,  one
1164              byte does not correspond to one character. Positioning in such a
1165              file can only be done to known character boundaries. That is, to
1166              a  position  earlier retrieved by getting a current position, to
1167              the beginning/end of the file or to some other position known to
1168              be  on  a  correct character boundary by some other means (typi‐
1169              cally beyond a byte order mark in the file, which  has  a  known
1170              byte-size).
1171
1172              A typical error reason is:
1173
1174                einval:
1175                  Either Location is illegal, or it is evaluated to a negative
1176                  offset in the file. Notice that if the resulting position is
1177                  a negative value, the result is an error, and after the call
1178                  the file position is undefined.
1179
1180       pread(IoDevice, LocNums) -> {ok, DataL} | eof | {error, Reason}
1181
1182              Types:
1183
1184                 IoDevice = io_device()
1185                 LocNums =
1186                     [{Location :: location(), Number :: integer() >= 0}]
1187                 DataL = [Data]
1188                 Data = string() | binary() | eof
1189                 Reason = posix() | badarg | terminated
1190
1191              Performs a sequence of pread/3 in one operation, which  is  more
1192              efficient  than  calling them one at a time. Returns {ok, [Data,
1193              ...]} or {error, Reason}, where each Data,  the  result  of  the
1194              corresponding  pread,  is either a list or a binary depending on
1195              the mode of the file, or eof if the requested position is beyond
1196              end of file.
1197
1198              As the position is specified as a byte-offset, take special cau‐
1199              tion when working with files where encoding is set to  something
1200              else  than latin1, as not every byte position is a valid charac‐
1201              ter boundary on such a file.
1202
1203       pread(IoDevice, Location, Number) ->
1204                {ok, Data} | eof | {error, Reason}
1205
1206              Types:
1207
1208                 IoDevice = io_device()
1209                 Location = location()
1210                 Number = integer() >= 0
1211                 Data = string() | binary()
1212                 Reason = posix() | badarg | terminated
1213
1214              Combines position/2 and read/2 in one operation, which  is  more
1215              efficient than calling them one at a time. If IoDevice is opened
1216              in raw mode, some restrictions apply:
1217
1218                * Location is only allowed to be an integer.
1219
1220                * The current position of the  file  is  undefined  after  the
1221                  operation.
1222
1223              As the position is specified as a byte-offset, take special cau‐
1224              tion when working with files where encoding is set to  something
1225              else  than latin1, as not every byte position is a valid charac‐
1226              ter boundary on such a file.
1227
1228       pwrite(IoDevice, LocBytes) -> ok | {error, {N, Reason}}
1229
1230              Types:
1231
1232                 IoDevice = io_device()
1233                 LocBytes = [{Location :: location(), Bytes :: iodata()}]
1234                 N = integer() >= 0
1235                 Reason = posix() | badarg | terminated
1236
1237              Performs a sequence of pwrite/3 in one operation, which is  more
1238              efficient than calling them one at a time. Returns ok or {error,
1239              {N, Reason}}, where N is the number of  successful  writes  done
1240              before the failure.
1241
1242              When positioning in a file with other encoding than latin1, cau‐
1243              tion must be taken to set the position on  a  correct  character
1244              boundary. For details, see position/2.
1245
1246       pwrite(IoDevice, Location, Bytes) -> ok | {error, Reason}
1247
1248              Types:
1249
1250                 IoDevice = io_device()
1251                 Location = location()
1252                 Bytes = iodata()
1253                 Reason = posix() | badarg | terminated
1254
1255              Combines  position/2 and write/2 in one operation, which is more
1256              efficient than calling them one at a time. If IoDevice has  been
1257              opened in raw mode, some restrictions apply:
1258
1259                * Location is only allowed to be an integer.
1260
1261                * The  current  position  of  the  file is undefined after the
1262                  operation.
1263
1264              When positioning in a file with other encoding than latin1, cau‐
1265              tion  must  be  taken to set the position on a correct character
1266              boundary. For details, see position/2.
1267
1268       read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}
1269
1270              Types:
1271
1272                 IoDevice = io_device() | atom()
1273                 Number = integer() >= 0
1274                 Data = string() | binary()
1275                 Reason =
1276                     posix() |
1277                     badarg | terminated |
1278                     {no_translation, unicode, latin1}
1279
1280              Reads Number bytes/characters from the file referenced by  IoDe‐
1281              vice.  The  functions  read/2,  pread/3, and read_line/1 are the
1282              only ways to read from a file opened in raw mode (although  they
1283              work for normally opened files, too).
1284
1285              For  files  where encoding is set to something else than latin1,
1286              one character can be represented by more than one  byte  on  the
1287              file.  The parameter Number always denotes the number of charac‐
1288              ters read from the file, while the position in the file  can  be
1289              moved much more than this number when reading a Unicode file.
1290
1291              Also,  if  encoding  is  set  to something else than latin1, the
1292              read/3 call fails if the data contains  characters  larger  than
1293              255,  which  is why module io(3) is to be preferred when reading
1294              such a file.
1295
1296              The function returns:
1297
1298                {ok, Data}:
1299                  If the file was opened in binary mode, the  read  bytes  are
1300                  returned  in  a  binary,  otherwise  in  a list. The list or
1301                  binary is shorter than the number of bytes requested if  end
1302                  of file was reached.
1303
1304                eof:
1305                  Returned if Number>0 and end of file was reached before any‐
1306                  thing at all could be read.
1307
1308                {error, Reason}:
1309                  An error occurred.
1310
1311              Typical error reasons:
1312
1313                ebadf:
1314                  The file is not opened for reading.
1315
1316                {no_translation, unicode, latin1}:
1317                  The file is opened with another encoding than latin1 and the
1318                  data  in  the file cannot be translated to the byte-oriented
1319                  data that this function returns.
1320
1321       read_file(Filename) -> {ok, Binary} | {error, Reason}
1322
1323              Types:
1324
1325                 Filename = name_all()
1326                 Binary = binary()
1327                 Reason = posix() | badarg | terminated | system_limit
1328
1329              Returns {ok, Binary}, where Binary is a binary data object  that
1330              contains  the  contents  of  Filename,  or {error, Reason} if an
1331              error occurs.
1332
1333              Typical error reasons:
1334
1335                enoent:
1336                  The file does not exist.
1337
1338                eacces:
1339                  Missing permission for reading the file,  or  for  searching
1340                  one of the parent directories.
1341
1342                eisdir:
1343                  The named file is a directory.
1344
1345                enotdir:
1346                  A  component  of  the  filename  is not a directory. On some
1347                  platforms, enoent is returned instead.
1348
1349                enomem:
1350                  There is not enough memory for the contents of the file.
1351
1352       read_file_info(Filename) -> {ok, FileInfo} | {error, Reason}
1353
1354       read_file_info(Filename, Opts) -> {ok, FileInfo} | {error, Reason}
1355
1356              Types:
1357
1358                 Filename = name_all()
1359                 Opts = [file_info_option()]
1360                 FileInfo = file_info()
1361                 Reason = posix() | badarg
1362
1363              Retrieves information about a file. Returns  {ok,  FileInfo}  if
1364              successful,  otherwise  {error,  Reason}.  FileInfo  is a record
1365              file_info, defined in the Kernel include file file.hrl.  Include
1366              the following directive in the module from which the function is
1367              called:
1368
1369               -include_lib("kernel/include/file.hrl").
1370
1371              The time type returned in atime, mtime, and ctime  is  dependent
1372              on the time type set in Opts :: {time, Type} as follows:
1373
1374                local:
1375                  Returns local time.
1376
1377                universal:
1378                  Returns universal time.
1379
1380                posix:
1381                  Returns  seconds  since  or before Unix time epoch, which is
1382                  1970-01-01 00:00 UTC.
1383
1384              Default is {time, local}.
1385
1386              If the option raw is set, the file server is not called and only
1387              information  about  local files is returned. Note that this will
1388              break this module's atomicity guarantees as it can race  with  a
1389              concurrent call to write_file_info/1,2
1390
1391          Note:
1392              As  file times are stored in POSIX time on most OS, it is faster
1393              to query file information with option posix.
1394
1395
1396              The record file_info contains the following fields:
1397
1398                size = integer() >= 0:
1399                  Size of file in bytes.
1400
1401                type = device | directory | other | regular | symlink:
1402                  The type of the file.
1403
1404                access = read | write | read_write | none:
1405                  The current system access to the file.
1406
1407                atime = date_time() | integer() >= 0:
1408                  The last time the file was read.
1409
1410                mtime = date_time() | integer() >= 0:
1411                  The last time the file was written.
1412
1413                ctime = date_time() | integer() >=0:
1414                  The interpretation of this time field depends on the operat‐
1415                  ing  system.  On  Unix,  it is the last time the file or the
1416                  inode was changed. In Windows, it is the create time.
1417
1418                mode = integer() >= 0:
1419                  The file permissions as the sum of the following bit values:
1420
1421                  8#00400:
1422                    read permission: owner
1423
1424                  8#00200:
1425                    write permission: owner
1426
1427                  8#00100:
1428                    execute permission: owner
1429
1430                  8#00040:
1431                    read permission: group
1432
1433                  8#00020:
1434                    write permission: group
1435
1436                  8#00010:
1437                    execute permission: group
1438
1439                  8#00004:
1440                    read permission: other
1441
1442                  8#00002:
1443                    write permission: other
1444
1445                  8#00001:
1446                    execute permission: other
1447
1448                  16#800:
1449                    set user id on execution
1450
1451                  16#400:
1452                    set group id on execution
1453
1454                  On Unix platforms, other bits than those listed above may be
1455                  set.
1456
1457                links = integer() >= 0:
1458                  Number  of links to the file (this is always 1 for file sys‐
1459                  tems that have no concept of links).
1460
1461                major_device = integer() >= 0:
1462                  Identifies the file system where the  file  is  located.  In
1463                  Windows,  the  number  indicates a drive as follows: 0 means
1464                  A:, 1 means B:, and so on.
1465
1466                minor_device = integer() >= 0:
1467                  Only valid for character  devices  on  Unix.  In  all  other
1468                  cases, this field is zero.
1469
1470                inode = integer() >= 0:
1471                  Gives the inode number. On non-Unix file systems, this field
1472                  is zero.
1473
1474                uid = integer() >= 0:
1475                  Indicates the owner of the file. On non-Unix  file  systems,
1476                  this field is zero.
1477
1478                gid = integer() >= 0:
1479                  Gives  the  group  that the owner of the file belongs to. On
1480                  non-Unix file systems, this field is zero.
1481
1482              Typical error reasons:
1483
1484                eacces:
1485                  Missing search permission for one of the parent  directories
1486                  of the file.
1487
1488                enoent:
1489                  The file does not exist.
1490
1491                enotdir:
1492                  A  component  of  the  filename  is not a directory. On some
1493                  platforms, enoent is returned instead.
1494
1495       read_line(IoDevice) -> {ok, Data} | eof | {error, Reason}
1496
1497              Types:
1498
1499                 IoDevice = io_device() | atom()
1500                 Data = string() | binary()
1501                 Reason =
1502                     posix() |
1503                     badarg | terminated |
1504                     {no_translation, unicode, latin1}
1505
1506              Reads a line of bytes/characters from  the  file  referenced  by
1507              IoDevice. Lines are defined to be delimited by the linefeed (LF,
1508              \n) character, but any carriage return (CR, \r)  followed  by  a
1509              newline  is  also treated as a single LF character (the carriage
1510              return is silently ignored). The line is returned including  the
1511              LF, but excluding any CR immediately followed by an LF. This be‐
1512              haviour is consistent with the behaviour  of  io:get_line/2.  If
1513              end  of  file  is reached without any LF ending the last line, a
1514              line with no trailing LF is returned.
1515
1516              The function can be used on files opened in raw  mode.  However,
1517              it  is  inefficient  to  use  it on raw files if the file is not
1518              opened with option {read_ahead, Size} specified. Thus, combining
1519              raw  and {read_ahead, Size} is highly recommended when opening a
1520              text file for raw line-oriented reading.
1521
1522              If  encoding  is  set  to  something  else  than   latin1,   the
1523              read_line/1  call  fails  if the data contains characters larger
1524              than 255, why module io(3) is to be preferred when reading  such
1525              a file.
1526
1527              The function returns:
1528
1529                {ok, Data}:
1530                  One  line  from the file is returned, including the trailing
1531                  LF, but with CRLF sequences replaced by  a  single  LF  (see
1532                  above).
1533
1534                  If  the  file  is  opened in binary mode, the read bytes are
1535                  returned in a binary, otherwise in a list.
1536
1537                eof:
1538                  Returned if end of file was reached before anything  at  all
1539                  could be read.
1540
1541                {error, Reason}:
1542                  An error occurred.
1543
1544              Typical error reasons:
1545
1546                ebadf:
1547                  The file is not opened for reading.
1548
1549                {no_translation, unicode, latin1}:
1550                  The file is opened with another encoding than latin1 and the
1551                  data on the file cannot be translated to  the  byte-oriented
1552                  data that this function returns.
1553
1554       read_link(Name) -> {ok, Filename} | {error, Reason}
1555
1556              Types:
1557
1558                 Name = name_all()
1559                 Filename = filename()
1560                 Reason = posix() | badarg
1561
1562              Returns {ok, Filename} if Name refers to a symbolic link that is
1563              not a raw filename, or {error, Reason} otherwise.  On  platforms
1564              that  do  not  support  symbolic  links,  the  return  value  is
1565              {error,enotsup}.
1566
1567              Typical error reasons:
1568
1569                einval:
1570                  Name does not refer to a symbolic link or the  name  of  the
1571                  file  that  it  refers  to  does not conform to the expected
1572                  encoding.
1573
1574                enoent:
1575                  The file does not exist.
1576
1577                enotsup:
1578                  Symbolic links are not supported on this platform.
1579
1580       read_link_all(Name) -> {ok, Filename} | {error, Reason}
1581
1582              Types:
1583
1584                 Name = name_all()
1585                 Filename = filename_all()
1586                 Reason = posix() | badarg
1587
1588              Returns {ok, Filename} if Name refers  to  a  symbolic  link  or
1589              {error, Reason} otherwise. On platforms that do not support sym‐
1590              bolic links, the return value is {error,enotsup}.
1591
1592              Notice that Filename can be either a list or a binary.
1593
1594              Typical error reasons:
1595
1596                einval:
1597                  Name does not refer to a symbolic link.
1598
1599                enoent:
1600                  The file does not exist.
1601
1602                enotsup:
1603                  Symbolic links are not supported on this platform.
1604
1605       read_link_info(Name) -> {ok, FileInfo} | {error, Reason}
1606
1607       read_link_info(Name, Opts) -> {ok, FileInfo} | {error, Reason}
1608
1609              Types:
1610
1611                 Name = name_all()
1612                 Opts = [file_info_option()]
1613                 FileInfo = file_info()
1614                 Reason = posix() | badarg
1615
1616              Works like read_file_info/1,2 except that if Name is a  symbolic
1617              link,  information  about  the link is returned in the file_info
1618              record and the type field of the record is set to symlink.
1619
1620              If the option raw is set, the file server is not called and only
1621              information  about  local files is returned. Note that this will
1622              break this module's atomicity guarantees as it can race  with  a
1623              concurrent call to write_file_info/1,2
1624
1625              If  Name  is not a symbolic link, this function returns the same
1626              result as read_file_info/1. On platforms  that  do  not  support
1627              symbolic   links,   this   function   is  always  equivalent  to
1628              read_file_info/1.
1629
1630       rename(Source, Destination) -> ok | {error, Reason}
1631
1632              Types:
1633
1634                 Source = Destination = name_all()
1635                 Reason = posix() | badarg
1636
1637              Tries to rename the file Source to Destination. It can  be  used
1638              to  move  files (and directories) between directories, but it is
1639              not sufficient to specify the destination only. The  destination
1640              filename must also be specified. For example, if bar is a normal
1641              file and foo and baz are directories,  rename("foo/bar",  "baz")
1642              returns  an  error,  but  rename("foo/bar", "baz/bar") succeeds.
1643              Returns ok if it is successful.
1644
1645          Note:
1646              Renaming of open files is not allowed  on  most  platforms  (see
1647              eacces below).
1648
1649
1650              Typical error reasons:
1651
1652                eacces:
1653                  Missing read or write permissions for the parent directories
1654                  of Source or Destination. On some platforms, this  error  is
1655                  given if either Source or Destination is open.
1656
1657                eexist:
1658                  Destination  is  not  an empty directory. On some platforms,
1659                  also given when Source and Destination are not of  the  same
1660                  type.
1661
1662                einval:
1663                  Source is a root directory, or Destination is a subdirectory
1664                  of Source.
1665
1666                eisdir:
1667                  Destination is a directory, but Source is not.
1668
1669                enoent:
1670                  Source does not exist.
1671
1672                enotdir:
1673                  Source is a directory, but Destination is not.
1674
1675                exdev:
1676                  Source and Destination are on different file systems.
1677
1678       script(Filename) -> {ok, Value} | {error, Reason}
1679
1680              Types:
1681
1682                 Filename = name_all()
1683                 Value = term()
1684                 Reason =
1685                     posix() |
1686                     badarg | terminated | system_limit |
1687                     {Line :: integer(), Mod :: module(), Term :: term()}
1688
1689              Reads and evaluates Erlang expressions,  separated  by  '.'  (or
1690              ',',  a sequence of expressions is also an expression), from the
1691              file.
1692
1693              Returns one of the following:
1694
1695                {ok, Value}:
1696                  The file is read and evaluated. Value is the  value  of  the
1697                  last expression.
1698
1699                {error, atom()}:
1700                  An error occurred when opening the file or reading it. For a
1701                  list of typical error codes, see open/2.
1702
1703                {error, {Line, Mod, Term}}:
1704                  An error occurred when interpreting the  Erlang  expressions
1705                  in the file. Use format_error/1 to convert the three-element
1706                  tuple to an English description of the error.
1707
1708              The encoding of Filename can be set by a comment as described in
1709              epp(3).
1710
1711       script(Filename, Bindings) -> {ok, Value} | {error, Reason}
1712
1713              Types:
1714
1715                 Filename = name_all()
1716                 Bindings = erl_eval:binding_struct()
1717                 Value = term()
1718                 Reason =
1719                     posix() |
1720                     badarg | terminated | system_limit |
1721                     {Line :: integer(), Mod :: module(), Term :: term()}
1722
1723              The same as script/1 but the variable bindings Bindings are used
1724              in the evaluation. See erl_eval(3) about variable bindings.
1725
1726       sendfile(Filename, Socket) ->
1727                   {ok, integer() >= 0} |
1728                   {error, inet:posix() | closed | badarg | not_owner}
1729
1730              Types:
1731
1732                 Filename = name_all()
1733                 Socket = inet:socket()
1734
1735              Sends the file Filename to Socket. Returns  {ok,  BytesSent}  if
1736              successful, otherwise {error, Reason}.
1737
1738       sendfile(RawFile, Socket, Offset, Bytes, Opts) ->
1739                   {ok, integer() >= 0} |
1740                   {error, inet:posix() | closed | badarg | not_owner}
1741
1742              Types:
1743
1744                 RawFile = fd()
1745                 Socket = inet:socket()
1746                 Offset = Bytes = integer() >= 0
1747                 Opts = [sendfile_option()]
1748                 sendfile_option() =
1749                     {chunk_size, integer() >= 0} | {use_threads, boolean()}
1750
1751              Sends  Bytes  from  the  file referenced by RawFile beginning at
1752              Offset to Socket. Returns {ok, BytesSent} if successful,  other‐
1753              wise  {error,  Reason}.  If Bytes is set to 0 all data after the
1754              specified Offset is sent.
1755
1756              The file used must be opened using the raw flag, and the process
1757              calling  sendfile must be the controlling process of the socket.
1758              See gen_tcp:controlling_process/2.
1759
1760              If the OS used does not support non-blocking sendfile, an Erlang
1761              fallback using read/2 and gen_tcp:send/2 is used.
1762
1763              The option list can contain the following options:
1764
1765                chunk_size:
1766                  The  chunk size used by the Erlang fallback to send data. If
1767                  using the fallback, set this to  a  value  that  comfortably
1768                  fits in the systems memory. Default is 20 MB.
1769
1770       set_cwd(Dir) -> ok | {error, Reason}
1771
1772              Types:
1773
1774                 Dir = name() | EncodedBinary
1775                 EncodedBinary = binary()
1776                 Reason = posix() | badarg | no_translation
1777
1778              Sets  the  current  working directory of the file server to Dir.
1779              Returns ok if successful.
1780
1781              The functions in the module file usually treat binaries  as  raw
1782              filenames, that is, they are passed "as is" even when the encod‐
1783              ing of the binary does not  agree  with  native_name_encoding().
1784              However,  this function expects binaries to be encoded according
1785              to the value returned by native_name_encoding().
1786
1787              Typical error reasons are:
1788
1789                enoent:
1790                  The directory does not exist.
1791
1792                enotdir:
1793                  A component of Dir is not a directory.  On  some  platforms,
1794                  enoent is returned.
1795
1796                eacces:
1797                  Missing permission for the directory or one of its parents.
1798
1799                badarg:
1800                  Dir has an improper type, such as tuple.
1801
1802                no_translation:
1803                  Dir  is  a binary() with characters coded in ISO-latin-1 and
1804                  the VM is operating with unicode filename encoding.
1805
1806          Warning:
1807              In a future release, a bad type for argument Dir  will  probably
1808              generate an exception.
1809
1810
1811       sync(IoDevice) -> ok | {error, Reason}
1812
1813              Types:
1814
1815                 IoDevice = io_device()
1816                 Reason = posix() | badarg | terminated
1817
1818              Ensures  that  any  buffers kept by the operating system (not by
1819              the Erlang runtime system) are written to disk.  On  some  plat‐
1820              forms, this function might have no effect.
1821
1822              A typical error reason is:
1823
1824                enospc:
1825                  Not enough space left to write the file.
1826
1827       truncate(IoDevice) -> ok | {error, Reason}
1828
1829              Types:
1830
1831                 IoDevice = io_device()
1832                 Reason = posix() | badarg | terminated
1833
1834              Truncates  the  file referenced by IoDevice at the current posi‐
1835              tion. Returns ok if successful, otherwise {error, Reason}.
1836
1837       write(IoDevice, Bytes) -> ok | {error, Reason}
1838
1839              Types:
1840
1841                 IoDevice = io_device() | atom()
1842                 Bytes = iodata()
1843                 Reason = posix() | badarg | terminated
1844
1845              Writes Bytes to the file referenced by IoDevice.  This  function
1846              is  the only way to write to a file opened in raw mode (although
1847              it works for normally opened files too). Returns ok if  success‐
1848              ful, and {error, Reason} otherwise.
1849
1850              If  the  file is opened with encoding set to something else than
1851              latin1, each byte written can result in many bytes being written
1852              to  the  file,  as  the byte range 0..255 can represent anything
1853              between one and four bytes depending on value and  UTF  encoding
1854              type.
1855
1856              Typical error reasons:
1857
1858                ebadf:
1859                  The file is not opened for writing.
1860
1861                enospc:
1862                  No space is left on the device.
1863
1864       write_file(Filename, Bytes) -> ok | {error, Reason}
1865
1866              Types:
1867
1868                 Filename = name_all()
1869                 Bytes = iodata()
1870                 Reason = posix() | badarg | terminated | system_limit
1871
1872              Writes  the  contents of the iodata term Bytes to file Filename.
1873              The file is created if it does not exist. If it exists, the pre‐
1874              vious contents are overwritten. Returns ok if successful, other‐
1875              wise {error, Reason}.
1876
1877              Typical error reasons:
1878
1879                enoent:
1880                  A component of the filename does not exist.
1881
1882                enotdir:
1883                  A component of the filename is  not  a  directory.  On  some
1884                  platforms, enoent is returned instead.
1885
1886                enospc:
1887                  No space is left on the device.
1888
1889                eacces:
1890                  Missing  permission for writing the file or searching one of
1891                  the parent directories.
1892
1893                eisdir:
1894                  The named file is a directory.
1895
1896       write_file(Filename, Bytes, Modes) -> ok | {error, Reason}
1897
1898              Types:
1899
1900                 Filename = name_all()
1901                 Bytes = iodata()
1902                 Modes = [mode()]
1903                 Reason = posix() | badarg | terminated | system_limit
1904
1905              Same as write_file/2, but takes a third argument Modes,  a  list
1906              of  possible  modes, see open/2. The mode flags binary and write
1907              are implicit, so they are not to be used.
1908
1909       write_file_info(Filename, FileInfo) -> ok | {error, Reason}
1910
1911       write_file_info(Filename, FileInfo, Opts) -> ok | {error, Reason}
1912
1913              Types:
1914
1915                 Filename = name_all()
1916                 Opts = [file_info_option()]
1917                 FileInfo = file_info()
1918                 Reason = posix() | badarg
1919
1920              Changes file information. Returns ok  if  successful,  otherwise
1921              {error,  Reason}. FileInfo is a record file_info, defined in the
1922              Kernel include file file.hrl. Include the following directive in
1923              the module from which the function is called:
1924
1925               -include_lib("kernel/include/file.hrl").
1926
1927              The time type set in atime, mtime, and ctime depends on the time
1928              type set in Opts :: {time, Type} as follows:
1929
1930                local:
1931                  Interprets the time set as local.
1932
1933                universal:
1934                  Interprets it as universal time.
1935
1936                posix:
1937                  Must be seconds since or before Unix time  epoch,  which  is
1938                  1970-01-01 00:00 UTC.
1939
1940              Default is {time, local}.
1941
1942              If the option raw is set, the file server is not called and only
1943              information about local files is returned.
1944
1945              The following fields are used from the record, if they are spec‐
1946              ified:
1947
1948                atime = date_time() | integer() >= 0:
1949                  The last time the file was read.
1950
1951                mtime = date_time() | integer() >= 0:
1952                  The last time the file was written.
1953
1954                ctime = date_time() | integer() >= 0:
1955                  On  Unix, any value specified for this field is ignored (the
1956                  "ctime" for the file is set to the current  time).  On  Win‐
1957                  dows,  this  field  is  the new creation time to set for the
1958                  file.
1959
1960                mode = integer() >= 0:
1961                  The file permissions as the sum of the following bit values:
1962
1963                  8#00400:
1964                    Read permission: owner
1965
1966                  8#00200:
1967                    Write permission: owner
1968
1969                  8#00100:
1970                    Execute permission: owner
1971
1972                  8#00040:
1973                    Read permission: group
1974
1975                  8#00020:
1976                    Write permission: group
1977
1978                  8#00010:
1979                    Execute permission: group
1980
1981                  8#00004:
1982                    Read permission: other
1983
1984                  8#00002:
1985                    Write permission: other
1986
1987                  8#00001:
1988                    Execute permission: other
1989
1990                  16#800:
1991                    Set user id on execution
1992
1993                  16#400:
1994                    Set group id on execution
1995
1996                  On Unix platforms, other bits than those listed above may be
1997                  set.
1998
1999                uid = integer() >= 0:
2000                  Indicates the file owner. Ignored for non-Unix file systems.
2001
2002                gid = integer() >= 0:
2003                  Gives  the group that the file owner belongs to. Ignored for
2004                  non-Unix file systems.
2005
2006              Typical error reasons:
2007
2008                eacces:
2009                  Missing search permission for one of the parent  directories
2010                  of the file.
2011
2012                enoent:
2013                  The file does not exist.
2014
2015                enotdir:
2016                  A  component  of  the  filename  is not a directory. On some
2017                  platforms, enoent is returned instead.
2018

POSIX ERROR CODES

2020         * eacces - Permission denied
2021
2022         * eagain - Resource temporarily unavailable
2023
2024         * ebadf - Bad file number
2025
2026         * ebusy - File busy
2027
2028         * edquot - Disk quota exceeded
2029
2030         * eexist - File already exists
2031
2032         * efault - Bad address in system call argument
2033
2034         * efbig - File too large
2035
2036         * eintr - Interrupted system call
2037
2038         * einval - Invalid argument
2039
2040         * eio - I/O error
2041
2042         * eisdir - Illegal operation on a directory
2043
2044         * eloop - Too many levels of symbolic links
2045
2046         * emfile - Too many open files
2047
2048         * emlink - Too many links
2049
2050         * enametoolong - Filename too long
2051
2052         * enfile - File table overflow
2053
2054         * enodev - No such device
2055
2056         * enoent - No such file or directory
2057
2058         * enomem - Not enough memory
2059
2060         * enospc - No space left on device
2061
2062         * enotblk - Block device required
2063
2064         * enotdir - Not a directory
2065
2066         * enotsup - Operation not supported
2067
2068         * enxio - No such device or address
2069
2070         * eperm - Not owner
2071
2072         * epipe - Broken pipe
2073
2074         * erofs - Read-only file system
2075
2076         * espipe - Invalid seek
2077
2078         * esrch - No such process
2079
2080         * estale - Stale remote file handle
2081
2082         * exdev - Cross-domain link
2083

PERFORMANCE

2085       For increased performance, raw files are recommended.
2086
2087       A normal file is really a process so it can be used as  an  I/O  device
2088       (see io). Therefore, when data is written to a normal file, the sending
2089       of the data to the file process, copies all data that are not binaries.
2090       Opening  the file in binary mode and writing binaries is therefore rec‐
2091       ommended. If the file is opened on another node, or if the file  server
2092       runs  as  slave  to  the file server of another node, also binaries are
2093       copied.
2094
2095   Note:
2096       Raw files use the file system of the host machine of the node. For nor‐
2097       mal  files (non-raw), the file server is used to find the files, and if
2098       the node is running its file server as slave  to  the  file  server  of
2099       another  node, and the other node runs on some other host machine, they
2100       can have different file systems. However, this is seldom a problem.
2101
2102
2103       open/2 can be given the options delayed_write and read_ahead to turn on
2104       caching,  which  will  reduce  the number of operating system calls and
2105       greatly improve performance for small reads and  writes.  However,  the
2106       overhead won't disappear completely and it's best to keep the number of
2107       file operations to a minimum. As a  contrived  example,  the  following
2108       function writes 4MB in 2.5 seconds when tested:
2109
2110       create_file_slow(Name) ->
2111           {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2112           create_file_slow_1(Fd, 4 bsl 20),
2113           file:close(Fd).
2114
2115       create_file_slow_1(_Fd, 0) ->
2116           ok;
2117       create_file_slow_1(Fd, M) ->
2118           ok = file:write(Fd, <<0>>),
2119           create_file_slow_1(Fd, M - 1).
2120
2121       The following functionally equivalent code writes 128 bytes per call to
2122       write/2 and so does the same work in 0.08 seconds, which is roughly  30
2123       times faster:
2124
2125       create_file(Name) ->
2126           {ok, Fd} = file:open(Name, [raw, write, delayed_write, binary]),
2127           create_file_1(Fd, 4 bsl 20),
2128           file:close(Fd),
2129           ok.
2130
2131       create_file_1(_Fd, 0) ->
2132           ok;
2133       create_file_1(Fd, M) when M >= 128 ->
2134           ok = file:write(Fd, <<0:(128)/unit:8>>),
2135           create_file_1(Fd, M - 128);
2136       create_file_1(Fd, M) ->
2137           ok = file:write(Fd, <<0:(M)/unit:8>>),
2138           create_file_1(Fd, M - 1).
2139
2140       When  writing  data  it's  generally  more efficient to write a list of
2141       binaries rather than a list of integers. It is not needed to flatten  a
2142       deep list before writing. On Unix hosts, scatter output, which writes a
2143       set of buffers in one operation, is used when  possible.  In  this  way
2144       write(FD,  [Bin1,  Bin2  |  Bin3])  writes the contents of the binaries
2145       without copying the data at all, except for perhaps deep  down  in  the
2146       operating system kernel.
2147
2148   Warning:
2149       If  an  error  occurs  when  accessing an open file with module io, the
2150       process handling the file exits. The dead file process can  hang  if  a
2151       process  tries  to  access  it  later.  This  will be fixed in a future
2152       release.
2153
2154

SEE ALSO

2156       filename(3)
2157
2158
2159
2160Ericsson AB                       kernel 6.5                           file(3)
Impressum