Added documentation for container and backing

src/backing.c

@@ -149,7 +149,7 @@ result_t add_backing(char** _backing, const char* container) {
 	return result;
 }
 
-result_t import_backing(char** _backing, const char* path) {
+result_t import_backing(char** _backing, const char* disk) {
 	// Initialize the output parameters
 	*_backing = NULL;
 
@@ -160,7 +160,7 @@ result_t import_backing(char** _backing, const char* path) {
 		return result;
 
 	// Copy the disk to the temporary backing path
-	result = copy_file(path, temp_path);
+	result = copy_file(disk, temp_path);
 	if (result != success()) {
 		free(temp_path);
 		return result;

src/backing.h

@@ -2,22 +2,76 @@
 
 #include "utils.h"
 
+/// @brief Checks whether the given string is a valid backing identifier. If the string is not a valid backing identifier, the call will return a failure result with an error message.
+/// @param backing The string to check.
+/// @return The result of the operation.
 result_t check_backing_identifier(const char* backing);
+
+/// @brief Checks whether the given backing exists. If the backing does not exist, the call will return a failure result with an error message.
+/// @param backing The backing to check.
+/// @return The result of the operation.
 result_t check_backing_exists(const char* backing);
 
+/// @brief Gets the backing pool path.
+/// @param _path The string pointer to store the resulting path in. The caller is responsible for freeing the string.
+/// @return The result of the operation.
 result_t get_backing_pool_path(char** _path);
+
+/// @brief Gets the path of the given backing.
+/// @param _path The string pointer to store the resulting path in. The caller is responsible for freeing the string.
+/// @param backing The backing to get the path of.
+/// @return The result of the operation.
 result_t get_backing_path(char** _path, const char* backing);
+
+/// @brief Gets the path of the file containing the default backing identifier.
+/// @param _path The string pointer to store the resulting path in. The caller is responsible for freeing the string.
+/// @return The result of the operation.
 result_t get_backing_default_path(char** _path);
+
+/// @brief Gets the path of the temporary path to use for backing files.
+/// @param _path The string pointer to store the resulting path in. The caller is responsible for freeing the string.
+/// @return The result of the operation.
 result_t get_backing_temp_path(char** _path);
 
+/// @brief Adds a backing to the pool, from the given container.
+/// @param _backing The string pointer to store the resulting backing identifier in. The caller is responsible for freeing the string.
+/// @param container The container to use as the source for the backing.
+/// @return The result of the operation.
 result_t add_backing(char** _backing, const char* container);
-result_t import_backing(char** _backing, const char* path);
+
+/// @brief Imports a backing from the given disk.
+/// @param _backing The string pointer to store the resulting backing identifier in. The caller is responsible for freeing the string.
+/// @param disk The disk to use as the source for the backing.
+/// @return The result of the operation.
+result_t import_backing(char** _backing, const char* disk);
+
+/// @brief Removes the given backing from the pool. If the backing does not exist, the call will return a failure result with an error message.
+/// @param backing The backing to remove.
+/// @return The result of the operation.
 result_t remove_backing(const char* backing);
 
+/// @brief Checks that the given file is a backing. This function is used as a filter for listing backings.
+/// @param file The file to check.
+/// @return Whether the file is a backing.
 bool backing_filter(const char* file);
+
+/// @brief Lists the backings in the pool.
+/// @param _backings The string pointer array to store the resulting array in. The caller is responsible for freeing the strings and the array.
+/// @return The result of the operation.
 result_t list_backings(char*** _backings);
 
+/// @brief Gets the default backing identifier.
+/// @param _backing The string pointer to store the resulting backing identifier in. The caller is responsible for freeing the string.
+/// @return The result of the operation.
 result_t get_default_backing(char** _backing);
+
+/// @brief Sets the default backing identifier.
+/// @param backing The backing identifier to set as the default.
+/// @return The result of the operation.
 result_t set_default_backing(const char* backing);
 
+/// @brief Gets the backing parent of the given backing.
+/// @param _parent The string pointer to store the resulting backing parent identifier in. The caller is responsible for freeing the string.
+/// @param backing The backing to get the parent of.
+/// @return The result of the operation.
 result_t get_backing_parent(char** _parent, const char* backing);

src/container.c

@@ -130,6 +130,13 @@ result_t add_backed_container(const char* container, const char* backing) {
 	if (result != success())
 		return result;
 
+	// Check that the backing exists
+	result = check_backing_exists(backing);
+	if (result != success()) {
+		free(path);
+		return result;
+	}
+
 	// Get the backing path
 	char* backing_path;
 	result = get_backing_path(&backing_path, backing);

src/container.h

@@ -4,18 +4,60 @@
 
 #define CONTAINER_IDENTIFIER_MAX_LENGTH 64
 
+/// @brief Checks whether the given string is a valid container identifier. If the string is not a valid container identifier, the call will return a failure result with an error message.
+/// @param container The string to check.
+/// @return The result of the operation.
 result_t check_container_identifier(const char* container);
+
+/// @brief Checks whether the given container exists. If the container does not exist, the call will return a failure result with an error message.
+/// @param container The container to check.
+/// @return The result of the operation.
 result_t check_container_exists(const char* container);
 
+/// @brief Gets the container pool path.
+/// @param _path The string pointer to store the resulting path in. The caller is responsible for freeing the string.
+/// @return The result of the operation.
 result_t get_container_pool_path(char** _path);
+
+/// @brief Gets the container path.
+/// @param _path The string pointer to store the resulting path in. The caller is responsible for freeing the string.
+/// @param container The container to get the path of.
+/// @return The result of the operation.
 result_t get_container_path(char** _path, const char* container);
 
+/// @brief Adds a root (empty) container to the pool, with the given size. If the container already exists, the call will return a failure result with an error message.
+/// @param container The container to add.
+/// @param size The size of the container to add, in bytes.
+/// @return The result of the operation.
 result_t add_root_container(const char* container, uint64_t size);
+
+/// @brief Adds a backed container to the pool, with the given backing. If the container already exists, or the backing does not, the call will return a failure result with an error message.
+/// @param container The container to add.
+/// @param backing The backing to use for the container.
+/// @return The result of the operation.
 result_t add_backed_container(const char* container, const char* backing);
+
+/// @brief Removes the given container from the pool. If the container does not exist, the call will return a failure result with an error message.
+/// @param container The container to remove.
+/// @return The result of the operation.
 result_t remove_container(const char* container);
 
+/// @brief Trims (removes unused space) the given container.
+/// @param container The container to trim.
+/// @return The result of the operation.
 result_t trim_container(const char* container);
+
+/// @brief Resets the given container to its initial state.
+/// @param container The container to reset.
+/// @return The result of the operation.
 result_t reset_container(const char* container);
 
+/// @brief Checks that the given file is a container. This function is used as a filter for listing containers.
+/// @param file The file to check.
+/// @return Whether the file is a container.
 bool container_filter(const char* file);
+
+/// @brief Lists the containers in the pool.
+/// @param _containers The string pointer array to store the resulting array in. The caller is responsible for freeing the strings and the array.
+/// @return The result of the operation.
 result_t list_containers(char*** _containers);

src/disk.h

@@ -14,7 +14,7 @@ typedef struct {
 
 /// @brief Creates a root disk (empty disk) at the given path with the given size.
 /// @param path The path to create the disk at. Any existing file at this path will be overwritten.
-/// @param size The size of the disk to create.
+/// @param size The size of the disk to create, in bytes.
 /// @return The result of the operation.
 result_t create_root_disk(const char* path, uint64_t size);
 
@@ -29,7 +29,7 @@ result_t create_backed_disk(const char* path, const char* backing_path);
 /// @return The result of the operation.
 result_t trim_disk(const char* path);
 
-/// @brief Resets the given disk to its original state.
+/// @brief Resets the given disk to its initial state.
 /// @param path The path to the disk to reset.
 /// @return The result of the operation.
 result_t reset_disk(const char* path);
@@ -41,7 +41,7 @@ result_t reset_disk(const char* path);
 result_t reback_disk(const char* path, const char* backing_path);
 
 /// @brief Gets the disk information of the disk at the given path.
-/// @param _info The disk information pointer to store the result in. The caller is responsible for freeing the disk information.
+/// @param _info The disk information pointer to store the resulting disk information in. The caller is responsible for freeing the disk information.
 /// @param path The path to the disk to get the information of.
 /// @return The result of the operation.
 result_t get_disk_info(disk_info_t* _info, const char* path);

src/utils.h

@@ -25,43 +25,43 @@ result_t failure(const char* format, ...);
 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 _str The string pointer to store the resulting string 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.
+/// @brief Extracts a substring from the given string, starting at the given index and with the given length, and stores the resulting string 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 pointer to store the resulting string 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.
+/// @brief Formats a size in bytes to a human-readable string, and stores the resulting string 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 pointer to store the resulting string 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.
+/// @brief Parses a size from the given string, and stores the resulting integer in the given size pointer.
-/// @param _size The size pointer to store the result in.
+/// @param _size The size pointer to store the resulting integer 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.
+/// @brief Executes the given command, and stores the resulting exit code 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 _exit_code The exit code pointer to store the resulting exit code 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 _stdoutbuf The standard output string pointer to store the resulting string 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 _stderrbuf The standard error string pointer to store the resulting string 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.
+// @brief Reads the given file descriptor, and stores the resulting string 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 _str The string pointer to store the resulting string 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);
@@ -72,8 +72,8 @@ result_t read_fd(char** _str, int fd);
 // @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.
+/// @brief Reads the given file, and stores the resulting string 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 _str The string pointer to store the resulting string 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);
@@ -90,15 +90,15 @@ result_t write_file(const char* path, const char* str);
 /// @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.
+/// @brief Lists the files in the given directory, and stores the resulting array 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 _files The string pointer array to store the resulting array 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.
+/// @brief Calculates the MD5 checksum of the given file, and stores the resulting hash in the given string pointer.
-/// @param _md5 The string pointer to store the result in. The caller is responsible for freeing the string.
+/// @param _md5 The string pointer to store the resulting hash 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);