Started adding some documentation

src/backing.c

@@ -377,3 +377,43 @@ result_t set_default_backing(const char* backing) {
 		return result;
 	}
 }
+
+result_t get_backing_parent(char** _parent, const char* backing) {
+	// Initialize the output parameters
+	*_parent = NULL;
+
+	// Get the backing path
+	char* path;
+	result_t result = get_backing_path(&path, backing);
+	if (result != success())
+		return result;
+
+	// Get the disk info
+	disk_info_t info;
+	result = get_disk_info(&info, path);
+	if (result != success()) {
+		free(path);
+		return result;
+	}
+
+	// If the disk is not backed, return success and a null parent
+	if (info.backing_path == NULL) {
+		free_disk_info(&info);
+		free(path);
+		return success();
+	}
+
+	// Get the backing identifier of the parent
+	char* parent = strdup(basename(info.backing_path));
+	if (parent == NULL) {
+		free_disk_info(&info);
+		free(path);
+		return failure("Failed to get the backing identifier of the parent.");
+	}
+
+	free_disk_info(&info);
+	free(path);
+
+	*_parent = parent;
+	return result;
+}

src/backing.h

@@ -18,4 +18,6 @@ bool backing_filter(const char* file);
 result_t list_backings(char*** _backings);
 
 result_t get_default_backing(char** _backing);
-result_t set_default_backing(const char* backing);
+result_t set_default_backing(const char* backing);
+
+result_t get_backing_parent(char** _parent, const char* backing);

src/utils.c

@@ -12,7 +12,7 @@
 #include <fcntl.h>
 #include <openssl/evp.h>
 
-char ERROR_BUFFER[ERROR_BUFFER_SIZE];
+char _ERROR_BUFFER[ERROR_BUFFER_SIZE];
 
 result_t success(void) {
 	return EXIT_SUCCESS;
@@ -23,7 +23,7 @@ result_t failure(const char* format, ...) {
 	va_start(args, format);
 
 	// Print the error message into the error buffer
-	vsnprintf(ERROR_BUFFER, ERROR_BUFFER_SIZE, format, args);
+	vsnprintf(_ERROR_BUFFER, ERROR_BUFFER_SIZE, format, args);
 
 	va_end(args);
 
@@ -31,7 +31,7 @@ result_t failure(const char* format, ...) {
 }
 
 const char* error(void) {
-	return ERROR_BUFFER;
+	return _ERROR_BUFFER;
 }
 
 result_t format(char** _str, const char* format, ...) {

src/utils.h

@@ -6,28 +6,99 @@
 
 #define ERROR_BUFFER_SIZE 4096
 
-extern char ERROR_BUFFER[];
+extern char _ERROR_BUFFER[];
 
 typedef int result_t;
 
+/// @brief Returns a generic success result.
+/// @return The success result.
 result_t success(void);
+
+/// @brief Returns a generic failure result, with an error message formatted using the given format string and arguments. The error message is stored in a global buffer, and can be retrieved using the error() function.
+/// @param format The format string to use for the error message.
+/// @param ... The arguments to use for the format string.
+/// @return The failure result.
 result_t failure(const char* format, ...);
+
+/// @brief Returns the error message from the last failure result.
+/// @return The error message from the last failure result.
 const char* error(void);
 
+/// @brief Formats a string using the given format string and arguments, and stores the result in the given string pointer.
+/// @param _str The string pointer to store the result in. The caller is responsible for freeing the string.
+/// @param format The format string to use for the string.
+/// @param ... The arguments to use for the format string.
+/// @return The result of the operation.
 result_t format(char** _str, const char* format, ...);
+
+/// @brief Extracts a substring from the given string, starting at the given index and with the given length, and stores the result in the given string pointer.
+/// @param _str The string pointer to store the result in. The caller is responsible for freeing the string.
+/// @param str The string to extract the substring from.
+/// @param start The index to start the substring at.
+/// @param length The length of the substring. If the length goes beyond the end of the string, the substring will be truncated to the end of the string.
+/// @return The result of the operation.
 result_t substring(char** _str, const char* str, size_t start, size_t length);
 
+/// @brief Formats a size in bytes to a human-readable string, and stores the result in the given string pointer.
+/// @param _str The string pointer to store the result in. The caller is responsible for freeing the string.
+/// @param size The size in bytes to format.
+/// @return The result of the operation.
 result_t format_size(char** _str, uint64_t size);
+
+/// @brief Parses a size from the given string, and stores the result in the given size pointer.
+/// @param _size The size pointer to store the result in.
+/// @param str The string to parse the size from.
+/// @return The result of the operation.
 result_t parse_size(uint64_t* _size, const char* str);
 
+/// @brief Executes the given command, and stores the result in the given exit code pointer, and the standard output and standard error in the given string pointers.
+/// @param _exit_code The exit code pointer to store the result in.
+/// @param _stdoutbuf The standard output string pointer to store the result in. The caller is responsible for freeing the string. This parameter can be NULL if the standard output is not needed.
+/// @param _stderrbuf The standard error string pointer to store the result in. The caller is responsible for freeing the string. This parameter can be NULL if the standard error is not needed.
+/// @param executable The command to execute.
+/// @param ... The arguments to pass to the command. The last argument must be NULL. No need to pass the executable as the first argument.
+/// @return The result of the operation.
 result_t execute(int* _exit_code, char** _stdoutbuf, char** _stderrbuf, const char* executable, ...);
 
+// @brief Reads the given file descriptor, and stores the result in the given string pointer. The string can contain null characters.
+// @param _str The string pointer to store the result in. The caller is responsible for freeing the string.
+// @param fd The file descriptor to read from.
+// @return The result of the operation.
 result_t read_fd(char** _str, int fd);
+
+// @brief Writes the given string to the given file descriptor.
+// @param fd The file descriptor to write to.
+// @param str The string to write.
+// @return The result of the operation.
 result_t write_fd(int fd, const char* str);
+
+/// @brief Reads the given file, and stores the result in the given string pointer. The string can contain null characters.
+/// @param _str The string pointer to store the result in. The caller is responsible for freeing the string.
+/// @param path The path to the file to read.
+/// @return The result of the operation.
 result_t read_file(char** _str, const char* path);
+
+/// @brief Writes the given string to the given file.
+/// @param path The path to the file to write to.
+/// @param str The string to write.
+/// @return The result of the operation.
 result_t write_file(const char* path, const char* str);
+
+/// @brief Copies the given file to the given destination.
+/// @param src The path to the file to copy.
+/// @param dst The path to the destination to copy the file to.
+/// @return The result of the operation.
 result_t copy_file(const char* src, const char* dst);
 
+/// @brief Lists the files in the given directory, and stores the result in the given string pointer array. A filter can be provided to only include files that match the filter.
+/// @param _files The string pointer array to store the result in. The caller is responsible for freeing the strings and the array.
+/// @param path The path to the directory to list the files in.
+/// @param filter The filter to use to only include files that match the filter. This parameter can be NULL if no filter is needed.
+/// @return The result of the operation.
 result_t list_files(char*** _files, const char* path, bool (*filter)(const char*));
 
+/// @brief Calculates the MD5 checksum of the given file, and stores the result in the given string pointer.
+/// @param _md5 The string pointer to store the result in. The caller is responsible for freeing the string.
+/// @param path The path to the file to calculate the MD5 checksum of.
+/// @return The result of the operation.
 result_t md5sum(char** _md5, const char* path);