1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
|
[;1m-spec open(File, Modes) -> {ok, IoDevice} | {error, Reason}[0m
[;1m when[0m
[;1m File :: Filename | iodata(),[0m
[;1m Filename :: name_all(),[0m
[;1m Modes :: [mode() | ram | directory],[0m
[;1m IoDevice :: io_device(),[0m
[;1m Reason :: posix() | badarg | system_limit.[0m
Opens file [;;4mFile[0m in the mode determined by [;;4mModes[0m, which can
contain one or more of the following options:
[;;4m[;;4mread[0m[0m:
The file, which must exist, is opened for reading.
[;;4m[;;4mwrite[0m[0m:
The file is opened for writing. It is created if it does not
exist. If the file exists and [;;4mwrite[0m is not combined with [;;4m[0m
[;;4mread[0m, the file is truncated.
[;;4m[;;4mappend[0m[0m:
The file is opened for writing. It is created if it does not
exist. Every write operation to a file opened with [;;4mappend[0m
takes place at the end of the file.
[;;4m[;;4mexclusive[0m[0m:
The file is opened for writing. It is created if it does not
exist. If the file exists, [;;4m{error, eexist}[0m is returned.
Warning:
This option does not guarantee exclusiveness on file
systems not supporting [;;4mO_EXCL[0m properly, such as NFS. Do
not depend on this option unless you know that the file
system supports it (in general, local file systems are
safe).
[;;4m[;;4mraw[0m[0m:
Allows faster access to a file, as no Erlang process is needed
to handle the file. However, a file opened in this way has the
following limitations:
• The functions in the [;;4mio[0m module cannot be used, as they
can only talk to an Erlang process. Instead, use
functions [;;4mread/2[0m, [;;4mread_line/1[0m, and [;;4mwrite/2[0m.
• Especially if [;;4mread_line/1[0m is to be used on a [;;4mraw[0m
file, it is recommended to combine this option with
option [;;4m{read_ahead, Size}[0m as line-oriented I/O is
inefficient without buffering.
• Only the Erlang process that opened the file can use it.
• A remote Erlang file server cannot be used. The computer
on which the Erlang node is running must have access to
the file system (directly or through NFS).
[;;4m[;;4mbinary[0m[0m:
Read operations on the file return binaries rather than lists.
[;;4m[;;4m{delayed_write, Size, Delay}[0m[0m:
Data in subsequent [;;4mwrite/2[0m calls is buffered until at least [;;4m[0m
[;;4mSize[0m bytes are buffered, or until the oldest buffered data is [;;4m[0m
[;;4mDelay[0m milliseconds old. Then all buffered data is written in
one operating system call. The buffered data is also flushed
before some other file operation than [;;4mwrite/2[0m is executed.
The purpose of this option is to increase performance by
reducing the number of operating system calls. Thus, the [;;4m[0m
[;;4mwrite/2[0m calls must be for sizes significantly less than [;;4mSize[0m,
and not interspersed by too many other file operations.
When this option is used, the result of [;;4mwrite/2[0m calls can
prematurely be reported as successful, and if a write error
occurs, the error is reported as the result of the next file
operation, which is not executed.
For example, when [;;4mdelayed_write[0m is used, after a number of [;;4m[0m
[;;4mwrite/2[0m calls, [;;4mclose/1[0m can return [;;4m{error, enospc}[0m, as
there is not enough space on the disc for previously written
data. [;;4mclose/1[0m must probably be called again, as the file is
still open.
[;;4m[;;4mdelayed_write[0m[0m:
The same as [;;4m{delayed_write, Size, Delay}[0m with reasonable
default values for [;;4mSize[0m and [;;4mDelay[0m (roughly some 64 KB, 2
seconds).
[;;4m[;;4m{read_ahead, Size}[0m[0m:
Activates read data buffering. If [;;4mread/2[0m calls are for
significantly less than [;;4mSize[0m bytes, read operations to the
operating system are still performed for blocks of [;;4mSize[0m
bytes. The extra data is buffered and returned in subsequent [;;4m[0m
[;;4mread/2[0m calls, giving a performance gain as the number of
operating system calls is reduced.
The [;;4mread_ahead[0m buffer is also highly used by function [;;4m[0m
[;;4mread_line/1[0m in [;;4mraw[0m mode, therefore this option is
recommended (for performance reasons) when accessing raw files
using that function.
If [;;4mread/2[0m calls are for sizes not significantly less than,
or even greater than [;;4mSize[0m bytes, no performance gain can be
expected.
[;;4m[;;4mread_ahead[0m[0m:
The same as [;;4m{read_ahead, Size}[0m with a reasonable default
value for [;;4mSize[0m (roughly some 64 KB).
[;;4m[;;4mcompressed[0m[0m:
Makes it possible to read or write gzip compressed files.
Option [;;4mcompressed[0m must be combined with [;;4mread[0m or [;;4mwrite[0m,
but not both. Notice that the file size obtained with [;;4m[0m
[;;4mread_file_info/1[0m does probably not match the number of bytes
that can be read from a compressed file.
[;;4m[;;4m{encoding, Encoding}[0m[0m:
Makes the file perform automatic translation of characters to
and from a specific (Unicode) encoding. Notice that the data
supplied to [;;4mwrite/2[0m or returned by [;;4mread/2[0m still is
byte-oriented; this option denotes only how data is stored in
the disk file.
Depending on the encoding, different methods of reading and
writing data is preferred. The default encoding of [;;4mlatin1[0m
implies using this module ([;;4mfile[0m) for reading and writing
data as the interfaces provided here work with byte-oriented
data. Using other (Unicode) encodings makes the [;;4mio(3)[0m
functions [;;4mget_chars[0m, [;;4mget_line[0m, and [;;4mput_chars[0m more
suitable, as they can work with the full Unicode range.
If data is sent to an [;;4mio_device()[0m in a format that cannot be
converted to the specified encoding, or if data is read by a
function that returns data in a format that cannot cope with
the character range of the data, an error occurs and the file
is closed.
Allowed values for [;;4mEncoding[0m:
[;;4m[;;4mlatin1[0m[0m:
The default encoding. Bytes supplied to the file, that is, [;;4m[0m
[;;4mwrite/2[0m are written "as is" on the file. Likewise, bytes
read from the file, that is, [;;4mread/2[0m are returned "as
is". If module [;;4mio(3)[0m is used for writing, the file can
only cope with Unicode characters up to code point 255
(the ISO Latin-1 range).
[;;4m[;;4municode or utf8[0m[0m:
Characters are translated to and from UTF-8 encoding
before they are written to or read from the file. A file
opened in this way can be readable using function [;;4mread/2[0m,
as long as no data stored on the file lies beyond the ISO
Latin-1 range (0..255), but failure occurs if the data
contains Unicode code points beyond that range. The file
is best read with the functions in the Unicode aware
module [;;4mio(3)[0m.
Bytes written to the file by any means are translated to
UTF-8 encoding before being stored on the disk file.
[;;4m[;;4mutf16 or {utf16,big}[0m[0m:
Works like [;;4municode[0m, but translation is done to and from
big endian UTF-16 instead of UTF-8.
[;;4m[;;4m{utf16,little}[0m[0m:
Works like [;;4municode[0m, but translation is done to and from
little endian UTF-16 instead of UTF-8.
[;;4m[;;4mutf32 or {utf32,big}[0m[0m:
Works like [;;4municode[0m, but translation is done to and from
big endian UTF-32 instead of UTF-8.
[;;4m[;;4m{utf32,little}[0m[0m:
Works like [;;4municode[0m, but translation is done to and from
little endian UTF-32 instead of UTF-8.
The Encoding can be changed for a file "on the fly" by using
function [;;4mio:setopts/2[0m. So a file can be analyzed in latin1
encoding for, for example, a BOM, positioned beyond the BOM
and then be set for the right encoding before further reading.
For functions identifying BOMs, see module [;;4municode(3)[0m.
This option is not allowed on [;;4mraw[0m files.
[;;4m[;;4mram[0m[0m:
[;;4mFile[0m must be [;;4miodata()[0m. Returns an [;;4mfd()[0m, which lets module [;;4m[0m
[;;4mfile[0m operate on the data in-memory as if it is a file.
[;;4m[;;4msync[0m[0m:
On platforms supporting it, enables the POSIX [;;4mO_SYNC[0m
synchronous I/O flag or its platform-dependent equivalent (for
example, [;;4mFILE_FLAG_WRITE_THROUGH[0m on Windows) so that writes
to the file block until the data is physically written to
disk. However, be aware that the exact semantics of this flag
differ from platform to platform. For example, none of Linux
or Windows guarantees that all file metadata are also written
before the call returns. For precise semantics, check the
details of your platform documentation. On platforms with no
support for POSIX [;;4mO_SYNC[0m or equivalent, use of the [;;4msync[0m
flag causes [;;4mopen[0m to return [;;4m{error, enotsup}[0m.
[;;4m[;;4mdirectory[0m[0m:
Allows [;;4mopen[0m to work on directories.
Returns:
[;;4m[;;4m{ok, IoDevice}[0m[0m:
The file is opened in the requested mode. [;;4mIoDevice[0m is a
reference to the file.
[;;4m[;;4m{error, Reason}[0m[0m:
The file cannot be opened.
[;;4mIoDevice[0m is really the pid of the process that handles the file.
This process monitors the process that originally opened the file
(the owner process). If the owner process terminates, the file is
closed and the process itself terminates too. An [;;4mIoDevice[0m
returned from this call can be used as an argument to the I/O
functions (see [;;4mio(3)[0m).
Warning:
While this function can be used to open any file, we recommend
against using it for NFS-mounted files, FIFOs, devices, or
similar since they can cause IO threads to hang forever.
If your application needs to interact with these kinds of
files we recommend breaking out those parts to a port program
instead.
Note:
In previous versions of [;;4mfile[0m, modes were specified as one of
the atoms [;;4mread[0m, [;;4mwrite[0m, or [;;4mread_write[0m instead of a list.
This is still allowed for reasons of backwards compatibility,
but is not to be used for new code. Also note that [;;4mread_write[0m
is not allowed in a mode list.
Typical error reasons:
[;;4m[;;4menoent[0m[0m:
The file does not exist.
[;;4m[;;4meacces[0m[0m:
Missing permission for reading the file or searching one of
the parent directories.
[;;4m[;;4meisdir[0m[0m:
The named file is a directory.
[;;4m[;;4menotdir[0m[0m:
A component of the filename is not a directory, or the
filename itself is not a directory if [;;4mdirectory[0m mode was
specified. On some platforms, [;;4menoent[0m is returned instead.
[;;4m[;;4menospc[0m[0m:
There is no space left on the device (if [;;4mwrite[0m access was
specified).
|
