From bc07cc94cb5208525df9b2e16ce50de8c93748a8 Mon Sep 17 00:00:00 2001 From: apio Date: Fri, 9 Jun 2023 22:45:06 +0200 Subject: [PATCH] libos: Document it entirely using Doxygen comments =D Also, add copyright information to individual files. This is going to be a hassle to do for EVERY file. --- .vscode/settings.json | 13 ++- libos/include/os/ArgumentParser.h | 149 ++++++++++++++++++++++++-- libos/include/os/Directory.h | 68 ++++++++++-- libos/include/os/File.h | 172 +++++++++++++++++++++++++++--- libos/include/os/FileSystem.h | 82 +++++++++++++- libos/include/os/Main.h | 19 +++- libos/include/os/Mode.h | 22 ++++ libos/include/os/Path.h | 51 +++++++++ libos/include/os/Process.h | 44 ++++++++ libos/src/ArgumentParser.cpp | 10 ++ libos/src/Directory.cpp | 9 ++ libos/src/File.cpp | 15 ++- libos/src/FileSystem.cpp | 15 ++- libos/src/Main.cpp | 11 ++ libos/src/Mode.cpp | 9 ++ libos/src/Path.cpp | 9 ++ libos/src/Process.cpp | 9 ++ 17 files changed, 667 insertions(+), 40 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 6583b570..772ee6e1 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -13,5 +13,16 @@ "files.trimFinalNewlines": true, "files.insertFinalNewline": true, "git.inputValidationLength": 72, - "git.inputValidationSubjectLength": 72 + "git.inputValidationSubjectLength": 72, + "doxdocgen.file.fileOrder": [ + "file", + "author", + "brief", + "empty", + "copyright", + "empty" + ], + "doxdocgen.file.copyrightTag": [ + "@copyright Copyright (c) {year}, the Luna authors." + ] } diff --git a/libos/include/os/ArgumentParser.h b/libos/include/os/ArgumentParser.h index 1816da88..223f29c0 100644 --- a/libos/include/os/ArgumentParser.h +++ b/libos/include/os/ArgumentParser.h @@ -1,46 +1,173 @@ +/** + * @file ArgumentParser.h + * @author apio (cloudapio.eu) + * @brief Command-line argument parser. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #pragma once #include #include namespace os { + /** + * @brief A simple command-line argument parser. + */ class ArgumentParser { public: + /** + * @brief Construct a new ArgumentParser object. + */ ArgumentParser(); + /** + * @brief Add a description for this command-line utility (shown in the help text). + * + * @param description The description to use. + */ void add_description(StringView description); - Result add_positional_argument(StringView& out, StringView name, bool required); + /** + * @brief Register a new positional argument. + * + * @param out The variable where the argument's value will be stored. + * @param name The positional argument's name. + * @param fallback The value to use if the user does not provide one. + * @return Result Whether the operation succeeded. + */ Result add_positional_argument(StringView& out, StringView name, StringView fallback); + /** + * @brief Register a new positional argument. + * + * @param out The variable where the argument's value will be stored. + * @param name The positional argument's name. + * @param required Whether the user must enter a value for this argument. If this is false and the user does not + * enter a value, out will be set to an empty string. + * @return Result Whether the operation succeeded. + */ + Result add_positional_argument(StringView& out, StringView name, bool required); + + /** + * @brief Register a new switch argument. + * + * @param out This variable will be set to true if the user provides the switch argument on the command + * line. + * @param short_flag The short flag to use for this argument, excluding the '-' prefix: an option '-c' would be + * passed as 'c'. Can only be a single ASCII character. If you do not wish this argument to have a short flag, + * use the space character: ' '. + * @param long_flag The long flag to use for this argument, excluding the '--' prefix: an option '--example' + * would be passed as 'example'. Can be a string of any length. If you do not wish this argument to have a long + * flag, use an empty string: "". + * @param help The help text to show for this argument (optional). + * @return Result Whether the operation succeeded. + */ Result add_switch_argument(bool& out, char short_flag, StringView long_flag, StringView help = {}); - Result add_value_argument(StringView& out, char short_flag, StringView long_flag, bool value_required, - StringView help = {}); + /** + * @brief Register a new value argument. + * + * @param out The variable where the argument's value will be stored. + * @param short_flag The short flag to use for this argument, excluding the '-' prefix: an option '-c' would be + * passed as 'c'. Can only be a single ASCII character. If you do not wish this argument to have a short flag, + * use the space character: ' '. + * @param long_flag The long flag to use for this argument, excluding the '--' prefix: an option '--example' + * would be passed as 'example'. Can be a string of any length. If you do not wish this argument to have a long + * flag, use an empty string: "". + * @param fallback The value to use if the user uses the argument but does not provide a value. If, however, the + * user does not specify this argument at all, out WILL NOT BE MODIFIED! + * @param help The help text to show for this argument (optional). + * @return Result Whether the operation succeeded. + */ Result add_value_argument(StringView& out, char short_flag, StringView long_flag, StringView fallback, StringView help = {}); + /** + * @brief Register a new value argument. + * + * @param out The variable where the argument's value will be stored. + * @param short_flag The short flag to use for this argument, excluding the '-' prefix: an option '-c' would be + * passed as 'c'. Can only be a single ASCII character. If you do not wish this argument to have a short flag, + * use the space character: ' '. + * @param long_flag The long flag to use for this argument, excluding the '--' prefix: an option '--example' + * would be passed as 'example'. Can be a string of any length. If you do not wish this argument to have a long + * flag, use an empty string: "". + * @param value_required Whether the user is required to pass a value when using this argument. If this is + * false and the user does not enter a value along with the argument, out will be set to an empty string. If, + * however, the user does not specify this argument at all, out WILL NOT BE MODIFIED! + * @param help The help text to show for this argument (optional). + * @return Result Whether the operation succeeded. + */ + Result add_value_argument(StringView& out, char short_flag, StringView long_flag, bool value_required, + StringView help = {}); + + /** + * @brief Set the vector to append extra unregistered positional arguments to, after all + * registered positional arguments have been parsed. (If no vector is set, these values will instead be + * discarded!) + * + * @param out The vector of StringViews to use. + * @param allow_no_more_flags If set, after starting to append values into the vector, no more flags (switch and + * value arguments) will be parsed, and will instead be treated as regular positional arguments, as if '--' had + * been specified on the command line. + */ void set_vector_argument(Vector& out, bool allow_no_more_flags = false); + /** + * @brief Parse the given command-line using this ArgumentParser's registered arguments. + * + * @param argc The argc value passed to main() or luna_main(). + * @param argv The argv value passed to main() or luna_main(). + * @return Result Whether the operation succeeded. + */ Result parse(int argc, char* const* argv); + /** + * @brief A program's copyright and version information. + */ struct ProgramInfo { - StringView name; - StringView version; - StringView copyright; - StringView license; - StringView authors; - StringView package; + StringView name; // The program's name. + StringView version; // The program's version/release. + StringView copyright; // The program's copyright statement. + StringView license; // The program's licensing information. + StringView authors; // The program's authors (optional). + StringView package; // The package the program is a part of (optional). }; + /** + * @brief Set this program's copyright and version information (shown in the version text). + * + * @param info The program information to use. + */ void add_program_info(ProgramInfo info); - /* Used from programs that are part of the Luna source tree, to add the same version info for all programs. - * Should not be used otherwise. */ + /** + * @brief For programs that are part of the Luna source tree, set the version information using Luna's own + * version and copyright info and the program name. + * + * @param name The program name to show in the version information. + */ void add_system_program_info(StringView name); + /** + * @brief Show a short message describing how to find usage information (usually " --help"). + * + * The actual message shown is: + * "Try running ' --help' for more information." if --help has not been overridden. + * "Try running ' -h' for more information." if -h has not been overridden. + * If both have been overridden, no output is shown. + * + * Then, the program exits with a non-zero exit code. + * This function is designed to be used when the program detects an invalid argument value after parse() has run + * successfully. + * + * @param program_name The program name to show (usually argv[0]). + */ void short_usage(StringView program_name); private: diff --git a/libos/include/os/Directory.h b/libos/include/os/Directory.h index d2eeb195..bc8a4c20 100644 --- a/libos/include/os/Directory.h +++ b/libos/include/os/Directory.h @@ -1,3 +1,12 @@ +/** + * @file Directory.h + * @author apio (cloudapio.eu) + * @brief A C++-friendly API for directory access. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #pragma once #include #include @@ -7,44 +16,85 @@ namespace os { + /** + * @brief An object-oriented directory handle, which is closed when all references to it go out of scope. + */ class Directory { public: + /** + * @brief Create a new Directory object from a path, and open the directory. + * + * @param path The path to open. + * @return Result> A new Directory object. + */ static Result> open(const Path& path); + /** + * @brief A filter to skip certain directory entries. + */ enum class Filter { - None, - Hidden, - ParentAndBase + None, // Do not skip anything. + Hidden, // Skip all hidden files (that start with a '.' character). + ParentAndBase // Skip only the '.' and '..' entries. }; + /** + * @brief Read the next entry name from this Directory. + * + * @param filter The entries to filter out. + * @return Result The next entry's name as an owned String object, or an empty string if + * there are no more entries. + */ Result next(Filter filter); + /** + * @brief Read the list of entry names from this Directory. + * + * @param filter The entries to filter out. + * @return Result> The list of entry names. + */ Result> list_names(Filter filter); + /** + * @brief A directory entry with extra information. + */ struct Entry { - String name; - mode_t mode; - usize size; - time_t mtime; + String name; // The entry's name. + mode_t mode; // The entry's file permissions. + usize size; // The entry's size. + time_t mtime; // The entry's last modification time. }; + /** + * @brief Read the list of entries from this Directory, fetching extra information for each one. + * + * @param filter The entries to filter out. + * @return Result> The list of entries. + */ Result> list(Filter filter); + /** + * @brief Rewinds this Directory back to the beginning of its entry list. + */ void rewind(); + /** + * @brief Returns the file descriptor associated with this Directory. + * + * @return int The file descriptor. + */ int fd() { return dirfd(m_dirp); } ~Directory(); - - private: Directory(Badge); + private: DIR* m_dirp { nullptr }; }; } diff --git a/libos/include/os/File.h b/libos/include/os/File.h index 74144933..b4df45a6 100644 --- a/libos/include/os/File.h +++ b/libos/include/os/File.h @@ -1,5 +1,14 @@ +/** + * @file File.h + * @author apio (cloudapio.eu) + * @brief A C++-friendly API for file access. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #pragma once -#include +#include #include #include #include @@ -9,52 +18,160 @@ namespace os { + /** + * @brief An object-oriented file handle, which is closed when all references to it go out of scope. + */ class File { public: + /** + * @brief The supported file opening modes. + */ enum OpenMode { - ReadOnly = O_RDONLY, - WriteOnly = O_WRONLY | O_TRUNC, - ReadWrite = O_RDWR | O_TRUNC, - Append = O_WRONLY | O_APPEND, - ReadAppend = O_RDWR | O_APPEND, + ReadOnly = O_RDONLY, // Open the file read-only. + WriteOnly = O_WRONLY | O_TRUNC, // Open the file write-only, truncating it. + ReadWrite = O_RDWR | O_TRUNC, // Open the file read-write, truncating it. + Append = O_WRONLY | O_APPEND, // Open the file write-only, and append to it. + ReadAppend = O_RDWR | O_APPEND, // Open the file read-write, and append to it. }; + /** + * @brief Create a new File object from a file path, opening the file. + * + * @param path The path to open. + * @param flags The opening mode to pass to open(2). + * @return Result> A new File object, or ENOENT if the file did not exist. + */ static Result> open(const Path& path, OpenMode flags); + + /** + * @brief Create a new File object from a file path, opening the file or creating it if it does not exist. + * + * @param path The path to open. + * @param flags The opening mode to pass to open(2). + * @param mode If a new file is created, the file permissions to apply to it. (default: u=rw,g=r,o=r) + * @return Result> A new File object. + */ static Result> open_or_create(const Path& path, OpenMode flags, mode_t mode = 0644); + + /** + * @brief Create a new File object from a file path, creating the file but erroring out if the file already + * exists. + * + * @param path The path to open. + * @param flags The opening mode to pass to open(2). + * @param mode The file permissions to apply to the created file. (default: u=rw,g=r,o=r) + * @return Result> A new File object, or EEXIST if the file already existed. + */ static Result> create(const Path& path, OpenMode flags, mode_t mode = 0644); - /* - If path is "-", return standard input (as is common for many CLI apps). Otherwise, open path for reading. - - This function is a convenience function for CLI apps, so that they don't need to check path and open standard - input if necessary. - */ + /** + * @brief If path is "-", return standard input (as is common for many CLI apps). Otherwise, open path for + * reading. + * + * @param path The path to open. + * @return Result> A new File object if path was not "-", or the File + * object for standard input if path was "-". + */ static Result> open_input_file(StringView path); + /** + * @brief Returns the File corresponding to standard input. + * + * @return SharedPtr The File object for standard input. + */ static SharedPtr standard_input(); + + /** + * @brief Returns the File corresponding to standard output. + * + * @return SharedPtr The File object for standard output. + */ static SharedPtr standard_output(); + + /** + * @brief Returns the File corresponding to standard error. + * + * @return SharedPtr The File object for standard error. + */ static SharedPtr standard_error(); + /** + * @brief Make this File object automatically close on the next call to execve(3). + */ void set_close_on_exec(); + /** + * @brief Write a string to this File. + * + * @param str The string to write (can be not null-terminated). + * @return Result Whether the operation succeeded. + */ Result write(StringView str); + + /** + * @brief Write a memory buffer to this File. + * + * @param buf The buffer to write. + * @return Result Whether the operation succeeded. + */ Result write(const Buffer& buf); + /** + * @brief Read a line from this File. + * + * @return Result The line as an owned String object, or an empty string if there is no more + * data to read. + */ Result read_line(); + + /** + * @brief Read the entire File's contents as a string. + * + * @return Result The file's contents as an owned String object. + */ Result read_all_as_string(); + /** + * @brief Read data from this File. + * + * @param buf The output buffer to store the data in. Will be resized to fit the data. + * @param size The maximum number of bytes to read. + * @return Result Whether the operation succeeded. + */ Result read(Buffer& buf, usize size); + + /** + * @brief Read the entire File's contents. + * + * @return Result The file's contents as an owned Buffer object. + */ Result read_all(); + /** + * @brief Read a single character from the File. + * + * @return Result A character value above 0 (to be cast to an unsigned char), or EOF (typically -1) + * if there is no more data to read. + */ Result getchar(); + /** + * @brief Returns the file descriptor associated with this File. + * + * @return int The file descriptor. + */ int fd() const { return m_fd; } + /** + * @brief Move this File's file pointer back to the beginning. + */ + void rewind(); + File(Badge); ~File(); @@ -68,8 +185,39 @@ namespace os int m_fd { -1 }; }; + /** + * @brief Print a formatted string to standard output. + * + * @param fmt The format string (in the same format as printf(3)). + * @param ... The format arguments. + * @return Result Whether the operation succeeded. + */ Result print(StringView fmt, ...); + + /** + * @brief Print a newline-terminated formatted string to standard output. + * + * @param fmt The format string (in the same format as printf(3)). + * @param ... The format arguments. + * @return Result Whether the operation succeeded. + */ Result println(StringView fmt, ...); + + /** + * @brief Print a formatted string to standard error. + * + * @param fmt The format string (in the same format as printf(3)). + * @param ... The format arguments. + * @return Result Whether the operation succeeded. + */ Result eprint(StringView fmt, ...); + + /** + * @brief Print a newline-terminated formatted string to standard error. + * + * @param fmt The format string (in the same format as printf(3)). + * @param ... The format arguments. + * @return Result Whether the operation succeeded. + */ Result eprintln(StringView fmt, ...); } diff --git a/libos/include/os/FileSystem.h b/libos/include/os/FileSystem.h index c5553f52..64c71965 100644 --- a/libos/include/os/FileSystem.h +++ b/libos/include/os/FileSystem.h @@ -1,31 +1,111 @@ +/** + * @file FileSystem.h + * @author apio (cloudapio.eu) + * @brief APIs to read and modify the general file system. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #pragma once -#include #include #include #include +#include #include namespace os { namespace FileSystem { + /** + * @brief Check whether a given path exists. + * + * @param path The path to check. + * @param follow_symlinks If path is a symbolic link, whether to follow it (defaults to true). + * @return true The path exists. + * @return false The path does not exist, or it was a symbolic link and following it leaded to a nonexistent + * path. + */ bool exists(const Path& path, bool follow_symlinks = true); + /** + * @brief Check whether a given path is a directory. + * + * @param path The path to check. + * @param follow_symlinks If path is a symbolic link, whether to follow it (defaults to false). + * @return true The path is a directory, or the path was a symbolic link and following it leaded to a directory. + * @return false The path does not exist, or it is not a directory. + */ bool is_directory(const Path& path, bool follow_symlinks = false); + /** + * @brief Retrieve file status information. + * + * @param path The path to examine. + * @param st The buffer to store file status information in. + * @param follow_symlinks If path is a symbolic link, whether to follow it and retrieve its target's status, or + * otherwise retrieve the symbolic link's status (defaults to true). + * @return Result Whether the operation succeeded. + */ Result stat(const Path& path, struct stat& st, bool follow_symlinks = true); + /** + * @brief Create a new directory in the file system. + * + * @param path The path for the new directory. + * @param mode The file permissions to apply to the new directory. + * @return Result Whether the operation succeeded. + */ Result create_directory(StringView path, mode_t mode); + /** + * @brief Remove a file or empty directory from the file system. (The file will continue to exist if there are + * other hard links to it or a process still has it open.) + * + * @param path The path to remove. + * @return Result Whether the operation succeeded. + */ Result remove(const Path& path); + /** + * @brief Remove a directory tree from the file system recursively, deleting subfiles and subdirectories as + * well. + * + * @param path The path to remove. + * @return Result Whether the operation succeeded. + */ Result remove_tree(const Path& path); + /** + * @brief Read the target of a symbolic link. + * + * @param path The symbolic link's path. + * @return Result If the path was not a symbolic link, an empty string, otherwise the symbolic link's + * target. + */ Result readlink(const Path& path); + /** + * @brief Read the current process's working directory. + * + * @return Result The working directory as an owned String object. + */ Result working_directory(); + + /** + * @brief Fetch the current user' home directory. + * + * @return Result The home directory as an owned String object. + */ Result home_directory(); + /** + * @brief Change the current process's working directory. + * + * @param path The new working directory. + * @return Result Whether the operation succeeded. + */ Result change_directory(StringView path); } } diff --git a/libos/include/os/Main.h b/libos/include/os/Main.h index a53f9941..1a1ed8c3 100644 --- a/libos/include/os/Main.h +++ b/libos/include/os/Main.h @@ -1,4 +1,21 @@ +/** + * @file Main.h + * @author apio (cloudapio.eu) + * @brief Alternative C++ main function. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #pragma once #include -Result luna_main(int argc, char** argv); +/** + * @brief The main() function for Luna C++ apps. This function is extern as it should be implemented by the user if they + * do not implement the C main() function. + * + * @param argc The argc parameter passed to the regular main() function. + * @param argv The argv parameter passed to the regular main() function. + * @return Result A normal status code, or an errno code, which will be displayed along with an abnormal exit code. + */ +extern Result luna_main(int argc, char** argv); diff --git a/libos/include/os/Mode.h b/libos/include/os/Mode.h index 98263e28..e28c474b 100644 --- a/libos/include/os/Mode.h +++ b/libos/include/os/Mode.h @@ -1,8 +1,30 @@ +/** + * @file Mode.h + * @author apio (cloudapio.eu) + * @brief Visual file permissions parsing and formatting. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #pragma once #include namespace os { + /** + * @brief Create a visual representation of file permissions using the integral representation. + * + * The output is formatted in the same style as the output of "ls -l". + * For example: + * An integral mode of S_IFREG | 0644 would result in "-rw-r--r--". + * An integral mode of S_IFDIR | 0755 would result in "drwxr-xr-x". + * An integral mode of S_IFLNK | 0777 would result in "lrwxrwxrwx". + * + * @param mode The integral mode. + * @param out The buffer to store the formatted file permissions in, as a C-string (minimum 11 bytes, including the + * terminating null byte). + */ void format_mode(mode_t mode, char out[11]); } diff --git a/libos/include/os/Path.h b/libos/include/os/Path.h index f6dfd1d1..b7badd55 100644 --- a/libos/include/os/Path.h +++ b/libos/include/os/Path.h @@ -1,27 +1,78 @@ +/** + * @file Path.h + * @author apio (cloudapio.eu) + * @brief Dirfd-friendly Path class. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #pragma once #include #include namespace os { + /** + * @brief A dirfd-friendly Path class. + */ class Path { public: + /** + * @brief Construct a new Path object using a C-string file path. + * + * @param path The file path to use. + */ Path(const char* path); + + /** + * @brief Construct a new Path object using a StringView file path. + * + * @param path The file path to use. + */ Path(StringView path); + + /** + * @brief Construct a new Path object using a file descriptor. + * + * @param fd The file descriptor to use. + */ Path(int fd); + + /** + * @brief Construct a new Path object using a parent file descriptor and a file path. + * + * @param dirfd The parent file descriptor to use. + * @param name The file path to use. + */ Path(int dirfd, StringView name); + /** + * @brief Return the file descriptor associated with this Path. + * + * @return int The file descriptor, or AT_FDCWD if this Path does not have one. + */ int dirfd() const { return m_dirfd.value_or(AT_FDCWD); } + /** + * @brief Return the file path associated with this Path. + * + * @return StringView The path, or an empty StringView if this Path does not have one. + */ StringView name() const { return m_name.value_or(""_sv); } + /** + * @brief Determine whether this Path consists only of a file descriptor. + * + * @return int The fstatat()-compatible flag value to use in case this Path consists only of a file descriptor. + */ int is_empty_path() const { if (m_dirfd.has_value() && !m_name.has_value()) return AT_EMPTY_PATH; diff --git a/libos/include/os/Process.h b/libos/include/os/Process.h index 0ac19de9..b2c7a490 100644 --- a/libos/include/os/Process.h +++ b/libos/include/os/Process.h @@ -1,3 +1,12 @@ +/** + * @file Process.h + * @author apio (cloudapio.eu) + * @brief Functions to manipulate processes. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #pragma once #include #include @@ -5,13 +14,48 @@ namespace os { + /** + * @brief An object representing a process. + */ class Process { public: + /** + * @brief Create a new process, which is an identical copy of the current one. + * + * @return Result The child's process ID in the parent process, and 0 in the child process. + */ static Result fork(); + /** + * @brief Replace the current process's executable with another one. + * + * @param path The new executable's path. + * @param args The argument list to pass to the new executable. + * @param search_in_path Determines whether to search in the system binary directories if path is just a name. + * @return Result Always an error, as this function does not return on success. + */ static Result exec(StringView path, Slice args, bool search_in_path = true); + + /** + * @brief Replace the current process's executable with another one. + * + * @param path The new executable's path. + * @param args The argument list to pass to the new executable. + * @param search_in_path Determines whether to search in the system binary directories if path is just a name. + * @return Result Always an error, as this function does not return on success. + */ static Result exec(StringView path, Slice args, bool search_in_path = true); + + /** + * @brief Replace the current process's executable with another one. + * + * @param path The new executable's path. + * @param args The argument list to pass to the new executable. + * @param env The environment to pass to the new executable, instead of the current environment. + * @param search_in_path Determines whether to search in the system binary directories if path is just a name. + * @return Result Always an error, as this function does not return on success. + */ static Result exec(StringView path, Slice args, Slice env, bool search_in_path = true); }; } diff --git a/libos/src/ArgumentParser.cpp b/libos/src/ArgumentParser.cpp index 7dc9f22b..bca5e40a 100644 --- a/libos/src/ArgumentParser.cpp +++ b/libos/src/ArgumentParser.cpp @@ -1,3 +1,12 @@ +/** + * @file ArgumentParser.cpp + * @author apio (cloudapio.eu) + * @brief Command-line argument parser. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #include #include #include @@ -75,6 +84,7 @@ namespace os return; } + // Change this every year! constexpr auto copyright_text = "Copyright (C) 2023, the Luna authors."; constexpr auto license_text = "Licensed under the BSD-2 license "; diff --git a/libos/src/Directory.cpp b/libos/src/Directory.cpp index 78716eb2..876f2324 100644 --- a/libos/src/Directory.cpp +++ b/libos/src/Directory.cpp @@ -1,3 +1,12 @@ +/** + * @file Directory.cpp + * @author apio (cloudapio.eu) + * @brief A C++-friendly API for directory access. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #include #include #include diff --git a/libos/src/File.cpp b/libos/src/File.cpp index 33155dbc..9087dc28 100644 --- a/libos/src/File.cpp +++ b/libos/src/File.cpp @@ -1,4 +1,12 @@ -#include +/** + * @file File.cpp + * @author apio (cloudapio.eu) + * @brief A C++-friendly API for file access. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #include #include #include @@ -194,6 +202,11 @@ namespace os fcntl(m_fd, F_SETFD, FD_CLOEXEC); } + void File::rewind() + { + lseek(m_fd, 0, SEEK_SET); + } + // FIXME: Do not allocate memory for printing. Result print_impl(SharedPtr f, StringView fmt, va_list ap) { diff --git a/libos/src/FileSystem.cpp b/libos/src/FileSystem.cpp index f86de484..4c753d45 100644 --- a/libos/src/FileSystem.cpp +++ b/libos/src/FileSystem.cpp @@ -1,4 +1,12 @@ -#include +/** + * @file FileSystem.cpp + * @author apio (cloudapio.eu) + * @brief APIs to read and modify the general file system. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #include #include #include @@ -33,9 +41,8 @@ namespace os::FileSystem Result stat(const Path& path, struct stat& st, bool follow_symlinks) { - long rc = - syscall(SYS_fstatat, path.dirfd(), path.name().chars(), &st, - (int)((path.is_empty_path() ? AT_EMPTY_PATH : 0) | (follow_symlinks ? 0 : AT_SYMLINK_NOFOLLOW))); + long rc = syscall(SYS_fstatat, path.dirfd(), path.name().chars(), &st, + (int)(path.is_empty_path() | (follow_symlinks ? 0 : AT_SYMLINK_NOFOLLOW))); return Result::from_syscall(rc); } diff --git a/libos/src/Main.cpp b/libos/src/Main.cpp index 9059c295..d460e7ef 100644 --- a/libos/src/Main.cpp +++ b/libos/src/Main.cpp @@ -1,3 +1,12 @@ +/** + * @file Main.cpp + * @author apio (cloudapio.eu) + * @brief Alternative C++ main function. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #include #include #include @@ -5,6 +14,8 @@ int g_argc; char** g_argv; +// This function will only be linked into the final binary if the user does not already define main(), which implies +// that they should have defined luna_main() instead. If not, good for them: linker errors! __attribute__((weak)) int main(int argc, char** argv) { g_argc = argc; diff --git a/libos/src/Mode.cpp b/libos/src/Mode.cpp index 431a6aea..2c6e6cbb 100644 --- a/libos/src/Mode.cpp +++ b/libos/src/Mode.cpp @@ -1,3 +1,12 @@ +/** + * @file Mode.cpp + * @author apio (cloudapio.eu) + * @brief Visual file permissions parsing and formatting. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #include #include diff --git a/libos/src/Path.cpp b/libos/src/Path.cpp index 2575b721..a43dc415 100644 --- a/libos/src/Path.cpp +++ b/libos/src/Path.cpp @@ -1,3 +1,12 @@ +/** + * @file Path.cpp + * @author apio (cloudapio.eu) + * @brief Dirfd-friendly Path class. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #include namespace os diff --git a/libos/src/Process.cpp b/libos/src/Process.cpp index a20e4fbf..31f3a327 100644 --- a/libos/src/Process.cpp +++ b/libos/src/Process.cpp @@ -1,3 +1,12 @@ +/** + * @file Process.cpp + * @author apio (cloudapio.eu) + * @brief Functions to manipulate processes. + * + * @copyright Copyright (c) 2023, the Luna authors. + * + */ + #include #include #include