summaryrefslogtreecommitdiff
path: root/doc/api/libstd/files.txt
blob: f75e765db7c3c4dfbd00cebafcd240e0588a6123 (plain)
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
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
{
        title:  File Handling
        description:    libstd: File Handling
}

File Handling
-------------


    pkg std =
            type dir = struct
            ;;

            /* seek options */
            const Seekset	: whence 
            const Seekcur	: whence 
            const Seekend	: whence 

            /* open options */
            const Ordonly  	: fdopt 
            const Owronly  	: fdopt 
            const Ordwr    	: fdopt 
            const Otrunc   	: fdopt 
            const Ocreat   	: fdopt 
            const Oappend  	: fdopt 
            const Odir	: fdopt 

            /* directory handling */
            const diropen	: (p : byte[:] -> std.result(dir#, byte[:]))
            const dirread	: (d : dir# -> std.option(byte[:]))
            const dirclose	: (d : dir# -> void)
            const dirname	: (p : byte[:] -> byte[:])
            const mkdir	: (path : byte[:], mode : int64 -> int64)
            const mkpath	: (p : byte[:] -> bool)
            const chdir	: (path : byte[:] -> bool)

            /* file handling */
            const open	: (path : byte[:], opts : fdopt -> std.result(fd, errno))
            const openmode	: (path : byte[:], opts : fdopt, mode : int64 -> std.result(fd, errno))
            const mktemp	: (base : byte[:], opts : fdopt, mode : int64 -> std.result((fd, byte[:]), errno)
            const close	: (fd : fd -> int64)
            const creat	: (path : byte[:], mode : int64 -> fd)
            const read	: (fd : fd, buf : byte[:] -> size)
            const write	: (fd : fd, buf : byte[:] -> size)
            const seek	: (fd : fd, delta : off, whence : whence -> off)
            const pipe	: (fds : fd[2]# -> int64)
            const dup2	: (ofd : fd, nfd : fd -> fd)
            const remove	: (path : byte[:] -> bool)
            const unlink	: (path : byte[:] -> int)

            /* path manipulation */
            const basename	: (p : byte[:] -> byte[:])
            const pathcat	: (a : byte[:], b : byte[:] -> byte[:])
            const pathjoin	: (p : byte[:][:] -> byte[:])
            const pathnorm	: (p : byte[:] -> byte[:])
            const getcwd : (-> byte[:])

            /* file properties */
            const fmtime	: (f : byte[:]	-> result(time, errno))
            const fsize	: (f : byte[:]	-> result(off, errno))
            const fexists	: (f : byte[:]	-> bool)
            const fisdir	: (f : byte[:]	-> bool)

            /* convenience functions */
            const slurp : (path : byte[:] -> result(byte[:], byte[:]))
            const fslurp : (path : fd -> result(byte[:], byte[:]))
            const blat : (path : byte[:], buf : byte[:], perm : int64 -> bool)
            const fblat : (f : fd, buf : byte[:] -> bool)
    ;;


Data Types and Constants
------------------------

Libstd's file APIs are generally relatively thin wrappers around the host OS
functions. They are a portable subset of this functionality, designed for both
ease of use and portability.

    type dir = struct
    ;;

The directory struct represents the current state of a directory walk.

    /* seek options */
    const Seekset	: whence 
    const Seekcur	: whence 
    const Seekend	: whence 

These are a set of values which describe from where to seek within the file.

    /* open options */
    const Oread  	: fdopt 
    const Owrite  	: fdopt 
    const Ordwr    	: fdopt 
    const Otrunc   	: fdopt 
    const Ocreat   	: fdopt 

These are a set of options that are passed to the open variants describing
what mode to open the file in. These are bit masks which be OR'ed together to
combine them.

`Oread` and `Owrite` request permission to read and write the file, respectively.
`Ordwr` is a convenience flag which ors read and write together. `Otrunc`
indicates that the file should be truncated to zero bytes in length before it
is opened. `Ocreat` indicates that the file should be created if it does not
exist instead of returning an error. `Odir` indicates that this file should
be opened as a directory.

`Ocreat` does not create the path leading to it, and will return an error if
that path does not exist.


Directories
-----------

    const diropen	: (p : byte[:] -> std.result(dir#, byte[:]))

The `diropen` function opens a path as a directory, and returns a pointer
to an object which tracks the state of the directory, allowing for reading
file names one by one from this directory.

Returns: Either a directory wrapped up in the `\`Ok` branch of the result,
or a string describing the failure reason in the `\`Fail` branch.

    const dirread	: (d : dir# -> result(option(byte[:]), errno)

The `dirread` reads a single entry from the directory, opened with `diropen`,
returning it as a string. 

Returns `\`Some entry`, or `\`None` at the end of the directory.

    const dirclose	: (d : dir# -> void)

`dirclose` closes a directory for reading. This frees all associated
resources, returning them to the system. The directory passed in must have
been opened with `diropen`.

Returns: Nothing.

    const mkdir	: (path : byte[:], mode : int64 -> errno)

`mkdir` creates the directory specified in `path`. with the mode `mode`. It
requires the parent directory to exist and be writable. Absolute paths will
be created relative to the root of the file system, and relative paths will
be created relative to the current working directory, as usual.

If the directory already exists, this is counted as a failure to create the
directory.

Returns: Enone on success, or the error that caused the failure if it fails.

    const mkpath	: (path : byte[:] -> errno)

`mkpath` creates a full path specified by `path`. It creates all of the
path components required to create the full path specified. It requires
the parent of the first directory entry that is not currently in existence
to be writable.

Absolute paths will be created relative to the root of the file system, and
relative paths will be created relative to the current working directory, as
usual.

Returns: Enone on success, or the error that caused the directory creation
to fail on failure.

    const chdir	: (path : byte[:] -> bool)

Chdir changes the current working directory to the path specified in `path`.

Returns: True on success, false on failure.

Files
-----

    const open	: (path : byte[:], opts : fdopt -> result(fd, errno))
    const openmode	: (path : byte[:], opts : fdopt, mode : int64 -> result(fd, errno))

Open opens the file `path` for I/O according to the flags reqeusted in `opts`,
and returns a result containing the file descriptor or error. The mode is a
combination of the modes specified above: `Oread`,   `Owrite`, `Ordwr`,
`Otrunc`, or `Ocreat`.

Openmode is similar to open, however, if Ocreate is passed, it the file
requested will be created with the permissions passed in.

Returns: either a valid file descriptor on success, or an error describing why
the open failed on failure.

    const mktemp : (base : byte[:], opts : fdopt, mode : int64 -> std.result((fd, byte[:]), errno)

Mktemp is similar to openmode, however instead of taking a full path as
its first argument, it generates a unique name for a file in temporary
storage by appending a random string to the base name `base`. The mode
provided is in addition to the implicit Ocreat | Oexcl.

Returns: Either a successful result containing the tuple of file descriptor
opened and path generated, or an error describing the failure. The path
is allocated with `std.slalloc`, and must be freed by the caller using
`std.slfree`. The file descriptor must be closed as ususal.


    const close	: (fd : fd -> void)

Closes closes the file descriptor. If the file descriptor is valid, close
is guaranteed to close it. If it is not valid, this is a no-op.

    const read	: (fd : fd, buf : byte[:] -> result(size, errno))

Reads up to the length of `buf` from the file descriptor `fd`, at the current
offset within the file, advancing the offset by the count of bytes read. The
buffer may not be filled entirely when the read completes. For example, when
reading from a console, often only one line will be returned at a time.

Conventionally, `0` bytes are returned at the end of the file.

Returns: Either the number of bytes read on success, or the error that caused
a failure reading on failure.

    const write	: (fd : fd, buf : byte[:] -> result(size, errno))

Write writes up to the length of `buf` to the file descriptor, writing the
bytes at the current offset. The offset is advanced by the number of bytes
that were written, extending the file size if necessary. Write is not
guaranteed to write the full buffer.

Returns: The number of bytes written on success, or the error that caused
the failure on error.

    const seek	: (fd : fd, delta : off, whence : whence -> result(off, errno))

Seek changes the current offset within the file descriptor `fd` by `delta`.
This delta can be treated in three different ways, depending on the value of
`whence.

If `whence` is Seekset, then `delta` is treated as an absolute value to seek
to, and the offset is set to `delta`. If `whence` is `Seekcur`, then `delta`
is added to the current offset.  If `whence` is `Seekend`, then `delta` is
added to the size of the file.

Returns: Either the new offset within the file on success, or the error that
occurred on failure.

    const pipe	: (fds : fd[2]# -> errno)

Pipe creates a unidirectional channel for communication between processes.
Two file descriptors are returned in the array fd. Data written to fd[1] is
available in fd[0]. The pipe may or may not be buffered.

Returns: Enone on success, otherwise, returns the error that caused this
call to fail.

    const dup2	: (ofd : fd, nfd : fd -> result(fd, errno))

Dup2 copies the old fd `ofd` to the new fd `nfd`. If the file descriptor
`nfd` is already open, then it is implicitly closed by this call before
the fd is copied. This is done atomically.

Returns: Either the new fd used, on success, or an error describing the
failure.

    const remove	: (path : byte[:] -> errno)

Remove removes the file specified from the directory in which it is contained.
The user must have write permissions for the directory in order to remove
files from it. If `path` is a directory, it must be empty.

Returns: Enone on success, otherwise the error that caused the failure.

Path Manipulation
-----------------
    const basename	: (p : byte[:] -> byte[:])
    const dirname	: (p : byte[:] -> byte[:])

Given a string of the form "foo/bar/baz", `dirname()` returns the directory
component of it -- in other words, everything up to the final `/`. It ignores
trailing slashes. It 

The caller is responsible for freeing the path with `slfree`.

For example, `dirname("foo/bar//")` will return `"foo/bar"`.

    const pathcat	: (a : byte[:], b : byte[:] -> byte[:])

Pathcat joins two paths together, using '/' as a directory
separator. The paths are normalized before being returned. This
call is shorthand for `std.pathjoin([a, b][:])`.

The caller is responsible for freeing the path with `slfree`.

Returns: A concatenated path.

    const pathjoin	: (p : byte[:][:] -> byte[:])

Pathcat joins a list of paths together, using '/' as a directory
separator. The paths are normalized before being returned. This
call is shorthand for `std.pathjoin([a, b][:])`.

The caller is responsible for freeing the path with `slfree`.

Returns: A concatenated path.

    const pathnorm	: (p : byte[:] -> byte[:])

Pathnorm does a purely lexical normalization of the path. It removes
redundant components, doubled `/` characters, and similar. The returned
path is equivalent to the original input path.

The caller is responsible for freeing the path with `slfree`.

Returns: A new normalized path.

    const getcwd : (-> byte[:])

Returns the current working directory of the program. The caller is
responsible for freeing the path with `slfree`.

Returns: A string representing the working directory.

File Properties
---------------

    const fmtime	: (f : byte[:]	-> result(time, errno))

Returns either the last modification time of the file `f`, or
the error that was encountered extracting this information.

    const fsize	: (f : byte[:]	-> result(off, errno))

Returns either the size in bytes of the file `f`, or
the error that was encountered extracting this information.

    const fexists	: (f : byte[:]	-> bool)

Returns `true` if the file is able to be `stat`ed, or `false`
if this fails.

    const fisdir	: (f : byte[:]	-> bool)

Returns `true` if the file is a directory that is able to be `stat`ed, or
`false` if this fails.

Convenience Functions
---------------------

    const slurp : (path : byte[:] -> result(byte[:], errno))

Reads all bytes from `path` until the end of file.

Returns either the file data, or the failure encountered.

    const fslurp : (fd : fd -> result(byte[:], errno))

Reads all bytes from the file descriptor `fd` until the end of file.

Returns either the file data, or the failure encountered.

    const blat : (path : byte[:], buf : byte[:], perm : int64 -> bool)

Creates the file `path` with permissions `perm`, and writes as much of
`buf` as it can into it.

Returns Enone if no errors were encountered. Otherwise, the error is returned.

    const fblat : (f : fd, buf : byte[:] -> bool)

Writes as much of `buf` as it can into the file descriptor `fd`.

Returns Enone if no errors were encountered. Otherwise, the error is returned.