summaryrefslogtreecommitdiff
path: root/os.h
diff options
context:
space:
mode:
authorpommicket <pommicket@gmail.com>2023-02-28 19:39:06 -0500
committerpommicket <pommicket@gmail.com>2023-02-28 19:39:06 -0500
commit52ba910a48a4dd2abb798c3c998ecb0e006c1895 (patch)
tree5fa4b3fb1e28ee1027aaa02a78ddf9b9bd7b59f5 /os.h
parent5e92dac7b8ff9d60bfa3dcc69c3f77663a01aea4 (diff)
doxygen documentation
Diffstat (limited to 'os.h')
-rw-r--r--os.h128
1 files changed, 70 insertions, 58 deletions
diff --git a/os.h b/os.h
index a670a6b..6b9389a 100644
--- a/os.h
+++ b/os.h
@@ -1,4 +1,5 @@
-// a bunch of OS-dependent functions
+/// \file
+/// a bunch of OS-dependent functions
#ifndef OS_H_
#define OS_H_
@@ -22,45 +23,46 @@ typedef struct {
char name[];
} FsDirectoryEntry;
-// returns what kind of thing this is.
+/// returns what kind of thing this is.
FsType fs_path_type(const char *path);
FsPermission fs_path_permission(const char *path);
-// Does this file exist? Returns false for directories.
+/// Does this file exist? Returns false for directories.
bool fs_file_exists(const char *path);
-// Returns a NULL-terminated array of the files/directories in this directory, or NULL if the directory does not exist/out of memory.
-// When you're done with the entries, call fs_dir_entries_free (or call free on each entry, then on the whole array).
-// NOTE: The files/directories aren't returned in any particular order!
+/// Returns a NULL-terminated array of the files/directories in this directory, or NULL if the directory does not exist/out of memory.
+/// When you're done with the entries, call fs_dir_entries_free (or call free on each entry, then on the whole array).
+/// NOTE: The files/directories aren't returned in any particular order!
FsDirectoryEntry **fs_list_directory(const char *dirname);
-// Create the directory specified by `path`
-// Returns:
-// 1 if the directory was created successfully
-// 0 if the directory already exists
-// -1 if the path already exists, but it's not a directory, or if there's another error (e.g. don't have permission to create directory).
+/// Create the directory specified by `path`\n
+/// Returns:\n
+/// 1 if the directory was created successfully\n
+/// 0 if the directory already exists\n
+/// -1 if the path already exists, but it's not a directory, or if there's another error (e.g. don't have permission to create directory).\n
int fs_mkdir(const char *path);
-// Puts the current working directory into buf, including a null-terminator, writing at most buflen bytes.
-// Returns:
-// 1 if the working directory was inserted into buf successfully
-// 0 if buf is too short to hold the cwd
-// -1 if we can't get the cwd for whatever reason.
+// Puts the current working directory into buf, including a null-terminator, writing at most buflen bytes.\n
+// Returns:\n
+// 1 if the working directory was inserted into buf successfully\n
+// 0 if buf is too short to hold the cwd\n
+// -1 if we can't get the cwd for whatever reason.\n
int os_get_cwd(char *buf, size_t buflen);
-// Unlike ISO C rename() function, this will overwrite `newname` if it exists.
-// Returns:
-// >= 0 if successful
-// < 0 on error
+// Unlike ISO C rename() function, this will overwrite `newname` if it exists.\n
+// Returns:\n
+// >= 0 if successful\n
+// < 0 on error\n
int os_rename_overwrite(const char *oldname, const char *newname);
struct timespec time_last_modified(const char *filename);
struct timespec time_get(void);
-// sleep for a certain number of nanoseconds
+/// sleep for a certain number of nanoseconds
void time_sleep_ns(u64 ns);
-// free the entries generated by fs_list_directory.
+/// free the entries generated by fs_list_directory.
static void fs_dir_entries_free(FsDirectoryEntry **entries) {
for (int i = 0; entries[i]; ++i)
free(entries[i]);
free(entries);
}
+/// get current time in seconds since some arbitrary point
static double time_get_seconds(void) {
struct timespec t = time_get();
return (double)t.tv_sec
@@ -69,17 +71,17 @@ static double time_get_seconds(void) {
-// sleep for microseconds
+/// sleep for microseconds
static void time_sleep_us(u64 us) {
time_sleep_ns(us * 1000);
}
-// sleep for milliseconds
+/// sleep for milliseconds
static void time_sleep_ms(u64 ms) {
time_sleep_ns(ms * 1000000);
}
-// sleep for seconds
+/// sleep for seconds
static void time_sleep_s(u64 s) {
time_sleep_ns(s * 1000000000);
}
@@ -87,60 +89,70 @@ static void time_sleep_s(u64 s) {
typedef struct Process Process;
-// zero everything except what you're using
+/// zero everything except what you're using
typedef struct {
bool separate_stderr;
const char *working_directory;
+ /// for forwards compatibility
+ char _reserved[256];
} ProcessSettings;
typedef struct {
- // string like "exited with code 9"
+ /// string like "exited with code 9"
char message[62];
- // it might be possible that both signalled and exited are false,
- // if something weird happens.
+ /// it might be possible that both `signalled` and `exited` are false,
+ /// if something weird happens.
bool signalled;
bool exited;
+ /// only relevant if `exited = true`
int exit_code;
+ /// only relevant if `signalled = true`
int signal;
} ProcessExitInfo;
-// get process ID of this process
+/// get process ID of this process
int process_get_id(void);
-// execute the given command (like if it was passed to system()), creating a new Process object.
-// returns a valid process object on failure, but it will have an error, according to process_geterr
+/// execute the given command (like if it was passed to `system()`), creating a new \ref Process object.
+///
+/// returns a valid process object on failure, but it will have an error, according to \ref process_geterr
Process *process_run_ex(const char *command, const ProcessSettings *settings);
-// like process_run_ex, but with the default settings
+/// like \ref process_run_ex, but with the default settings
Process *process_run(const char *command);
-// returns the error last error produced, or NULL if there was no error.
+/// returns the error last error produced, or NULL if there was no error.
const char *process_geterr(Process *process);
-// write to stdin
-// returns:
-// -2 on error
-// or a non-negative number indicating the number of bytes written.
-// Currently, this does a blocking write.
+/// write to stdin
+///
+/// returns -2 on error,
+/// or a non-negative number indicating the number of bytes written.
+/// Currently, this does a blocking write.
long long process_write(Process *process, const char *data, size_t size);
-// read from stdout+stderr
-// returns:
-// -2 on error
-// -1 if no data is available right now
-// 0 on end of file
-// or a positive number indicating the number of bytes read to data (at most size)
-// This does a nonblocking read.
+/// read from stdout+stderr.
+///
+/// returns:\n
+/// -2 on error\n
+/// -1 if no data is available right now\n
+/// 0 on end of file\n
+/// or a positive number indicating the number of bytes read to data (at most size)\n
+/// This does a nonblocking read.
long long process_read(Process *process, char *data, size_t size);
-// like process_read, but reads stderr.
-// this function ALWAYS RETURNS -2 if separate_stderr is not specified in the ProcessSettings.
-// if separate_stderr is false, then both stdout and stderr will be sent via process_read.
+/// like \ref process_read, but reads stderr.
+///
+/// this function ALWAYS RETURNS -2 if `separate_stderr` is not specified in the \ref ProcessSettings.
+/// if `separate_stderr` is false, then both stdout and stderr will be sent via \ref process_read.
long long process_read_stderr(Process *process, char *data, size_t size);
-// Checks if the process has exited. Returns:
-// -1 if the process returned a non-zero exit code, or got a signal.
-// 1 if the process exited successfully
-// 0 if the process hasn't exited.
-// If the process has exited, *info will be filled out with details.
-// if the process is no longer running, *process will be freed and set to NULL.
+/// Checks if the process has exited.
+///
+/// Returns:\n
+/// -1 if the process returned a non-zero exit code, or got a signal.\n
+/// 1 if the process exited successfully\n
+/// 0 if the process hasn't exited.\n
+/// If the process has exited, `*info` will be filled out with details.
+/// if the process is no longer running, `*process` will be freed and set to NULL.
int process_check_status(Process **process, ProcessExitInfo *info);
-// kills process if still running
-// this also frees any resources used by `*process`.
-// *process will be set to NULL.
+/// kills process if still running
+///
+/// this also frees any resources used by `*process`.
+/// `*process` will be set to NULL.
void process_kill(Process **process);
#endif // OS_H_