commit 9762dd010d6728dc55a335b80ce4324246098103
parent 77ee87ac2829f4487b0db9b7e79f302763e87d16
Author: Sebastian <sebastian@sebsite.pw>
Date: Thu, 14 Sep 2023 00:04:05 -0400
fs, os: improve some docs
The main motivation for this is discouraging the use of flag::CREATE
with open, instead directing the user to create. It also clarifies in
create's docs that the file is only created if it doesn't already exist.
This also corrects create's docs, by documenting that flag::TRUNC is
used by default. fs::flag didn't list TRUNC as one of the mandatory
flags for an fs::fs to support though, so I had to add that.
Signed-off-by: Sebastian <sebastian@sebsite.pw>
Diffstat:
3 files changed, 29 insertions(+), 14 deletions(-)
diff --git a/fs/fs.ha b/fs/fs.ha
@@ -19,8 +19,12 @@ export fn close(fs: *fs) void = {
};
};
-// Opens a file. If no flags are provided, the default read/write mode is
-// RDONLY.
+// Opens a file.
+//
+// If no flags are provided, [[flag::RDONLY]] is used when opening the file.
+//
+// [[flag::CREATE]] isn't very useful with this function, since the new file's
+// mode is set to zero. For this use-case, use [[create]] instead.
export fn open(fs: *fs, path: str, flags: flag...) (io::handle | error) = {
match (fs.open) {
case null =>
@@ -34,7 +38,10 @@ export fn open(fs: *fs, path: str, flags: flag...) (io::handle | error) = {
// handle on the host operating system, which may not be possible with all
// filesystem implementations (such cases will return [[io::unsupported]]).
//
-// If no flags are provided, the default read/write mode is RDONLY.
+// If no flags are provided, [[flag::RDONLY]] is used when opening the file.
+//
+// [[flag::CREATE]] isn't very useful with this function, since the new file's
+// mode is set to zero. For this use-case, use [[create_file]] instead.
export fn open_file(fs: *fs, path: str, flags: flag...) (io::file | error) = {
match (fs.openfile) {
case null =>
@@ -44,8 +51,11 @@ export fn open_file(fs: *fs, path: str, flags: flag...) (io::file | error) = {
};
};
-// Creates a new file and opens it for writing. If no flags are provided, the
-// default read/write mode is WRONLY.
+// Creates a new file with the given mode if it doesn't already exist, and opens
+// it for writing.
+//
+// If no flags are provided, [[flag::WRONLY]] and [[flag::TRUNC]] are used when
+// opening the file.
export fn create(
fs: *fs,
path: str,
@@ -60,12 +70,13 @@ export fn create(
};
};
-// Creates a new file, as an [[io::file]], and opens it for writing. This file
-// will be backed by an open file handle on the host operating system, which may
-// not be possible with all filesystem implementations (such cases will return
-// [[io::unsupported]]).
+// Creates a new file with the given mode if it doesn't already exist, and opens
+// it as an [[io::file]] for writing. This file will be backed by an open file
+// handle on the host operating system, which may not be possible with all
+// filesystem implementations (such cases will return [[io::unsupported]]).
//
-// If no flags are provided, the default read/write mode is WRONLY.
+// If no flags are provided, [[flag::WRONLY]] and [[flag::TRUNC]] are used when
+// opening the file.
export fn create_file(
fs: *fs,
path: str,
diff --git a/fs/types.ha b/fs/types.ha
@@ -172,7 +172,7 @@ export fn dirent_dup(e: *dirent) dirent = {
export fn dirent_finish(e: *dirent) void = free(e.name);
// Flags to use for opening a file. Not all operating systems support all flags;
-// at a minimum, RDONLY, WRONLY, RDWR, and CREATE will be supported.
+// at a minimum, RDONLY, WRONLY, RDWR, CREATE, and TRUNC will be supported.
// Note that NOCTTY and CLOEXEC are on by default, and the CTTY/NOCLOEXEC flags
// respectively disable them.
export type flag = enum int {
diff --git a/os/os.ha b/os/os.ha
@@ -88,13 +88,17 @@ export fn symlink(target: str, path: str) (void | fs::error) =
//
// If no flags are provided, [[fs::flag::RDONLY]] is used when opening the
// file.
+//
+// [[fs::flag::CREATE]] isn't very useful with this function, since the new
+// file's mode is set to zero. For this use-case, use [[create]] instead.
export fn open(path: str, flags: fs::flag...) (io::file | fs::error) =
fs::open_file(cwd, path, flags...);
-// Creates a new file and opens it for writing.
+// Creates a new file with the given mode if it doesn't already exist and opens
+// it for writing.
//
-// If no flags are provided, [[fs::flag::WRONLY]] is used when opening the
-// file.
+// If no flags are provided, [[fs::flag::WRONLY]] and [[fs::flag::TRUNC]] are
+// used when opening the file.
//
// Only the permission bits of the mode are used. If other bits are set, they
// are discarded.
