cosms/cosms-core
1
0
Fork 0
Code Issues 5 Pull requests Projects 1 Releases Packages Wiki Activity Actions

docs(file): added commend to all file functions

Browse source
This commit is contained in:
Mineplay5780 2025-12-20 20:53:39 +01:00
parent e7c977165d
commit 562eab114b
3 changed files with 105 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

69
include/cosms-core/file.h
View file

@ -45,19 +45,86 @@ struct cosms_core_file {
#endif
};
/**
* @brief Opens file in specified mode.
*
* @param file Pointer to file struct (must not be NULL)
* @param path to the file to open
* @param mode to open the file in (read, write, apped, create or a combination of these)
* @return COSMS_CORE_FILE_OK on success, or a negative error code
*/
CosmsCoreFileError cosms_core_file_open(struct cosms_core_file *file, const char *path, int mode);
/**
* @brief Closes an open file.
*
* @param file Pointer to file struct that has been opened (must not be NULL)
* @return COSMS_CORE_FILE_OK on success, or a negative error code
*/
CosmsCoreFileError cosms_core_file_close(struct cosms_core_file *file);
/**
* @brief Gets the size of an opened file.
*
* @param file Pointer to file struct that has been opned (must not be NULL)
* @param size Pointer to the variable to store the size in (must not be NULL)
* @return COSMS_CORE_FILE_OK on success, or a negative error code
*/
CosmsCoreFileError cosms_core_file_get_size(struct cosms_core_file *file, unsigned long long *size);
/**
* @brief Try's to reads specified number of bytes.
*
* @param file Pointer to file struct that has been opened in read mode (must not be NULL)
* @param buffer to store the file content in (has to be preallocated stack or heap memory)
* @param bytes_to_read from the file.
* @param bytes_read Pointer to the variable to store the amount of bytes that where actually read (can be NULL)
* @return COSMS_CORE_FILE_OK on success, or a negative error code
*/
CosmsCoreFileError cosms_core_file_read(struct cosms_core_file *file, char *buffer, unsigned int bytes_to_read, unsigned int *bytes_read);
/**
* @brief Reads the whole file with support for reading large files.
*
* @param file Pointer to file struct that has been opened in read mode (must not be NULL)
* @param buffer Pointer to buffer to store the file content in (needs to be empty)
* @param bytes_read Pointer to the variable to store the amount of bytes that where actually read (can be NULL)
* @return COSMS_CORE_FILE_OK on success, or a negative error code
*/
CosmsCoreFileError cosms_core_file_read_all(struct cosms_core_file *file, char **buffer, unsigned long long *bytes_read);
/**
* @brief Try's to write specified number of bytes.
*
* @param file Pointer to file struct that has been opened in write mode (must not be NULL)
* @param buffer that contains the bytes to write (must not be NULL)
* @param bytes_to_write to the file
* @param bytes_written Pointer to the variable to store the amount of bytes that where actually written (can be NULL)
* @return COSMS_CORE_FILE_OK on success, or a negative error code
*/
CosmsCoreFileError cosms_core_file_write(struct cosms_core_file *file, char *buffer, unsigned int bytes_to_write, unsigned int *bytes_written);
/**
* @brief Writes the full buffer to the file with support for writting large files.
*
* @param file Pointer to file struct that has been opened in write mode (must not be NULL)
* @param buffer that contains the bytes to write (must not be NULL)
* @param bytes_to_write to the file
* @return COSMS_CORE_FILE_OK on success, or a negative error code
*/
CosmsCoreFileError cosms_core_file_write_all(struct cosms_core_file *file, char *buffer, unsigned long long bytes_to_write);
/**
* @brief Deletes specified file from system.
*
* @param path to the file to delete
* @return COSMS_CORE_FILE_OK on success, or a negative error code
*/
CosmsCoreFileError cosms_core_file_delete(const char *path);
/**
* @brief Converts error code to a string that can be used for printing/logging errors.
*
* @param error The error code to convert to a string message.
* @return The error as a string on success, or NULL
*/
const char *cosms_core_file_error_string(CosmsCoreFileError error);
#endif
#endif /* COSMS_CORE_FILE */

27
src/file.c
View file

@ -21,6 +21,9 @@
#include <errno.h>
#endif
/**
* @brief Opens file in specified mode.
*/
CosmsCoreFileError cosms_core_file_open(struct cosms_core_file *file, const char *path, int mode) {
file->mode = mode;
@ -111,6 +114,9 @@ CosmsCoreFileError cosms_core_file_open(struct cosms_core_file *file, const char
return COSMS_CORE_FILE_OK;
}
/**
* @brief Closes an open file.
*/
CosmsCoreFileError cosms_core_file_close(struct cosms_core_file *file) {
#if defined(__GNUC__)
int error = close(file->native_file);
@ -135,6 +141,9 @@ CosmsCoreFileError cosms_core_file_close(struct cosms_core_file *file) {
return COSMS_CORE_FILE_OK;
}
/**
* @brief Gets the size of an opened file.
*/
CosmsCoreFileError cosms_core_file_get_size(struct cosms_core_file *file, unsigned long long *size) {
#if defined(__GNUC__)
struct stat file_stat;
@ -164,6 +173,9 @@ CosmsCoreFileError cosms_core_file_get_size(struct cosms_core_file *file, unsign
return COSMS_CORE_FILE_OK;
}
/**
* @brief Try's to reads specified number of bytes.
*/
CosmsCoreFileError cosms_core_file_read(struct cosms_core_file *file, char *buffer, unsigned int bytes_to_read, unsigned int *bytes_read) {
if ((file->mode & COSMS_CORE_FILE_MODE_READ) == 0) {
return COSMS_CORE_FILE_INVALID_OPERATION;
@ -188,6 +200,9 @@ CosmsCoreFileError cosms_core_file_read(struct cosms_core_file *file, char *buff
return COSMS_CORE_FILE_OK;
}
/**
* @brief Reads the whole file with support for reading large files.
*/
CosmsCoreFileError cosms_core_file_read_all(struct cosms_core_file *file, char **buffer, unsigned long long *bytes_read) {
if ((file->mode & COSMS_CORE_FILE_MODE_READ) == 0) {
return COSMS_CORE_FILE_INVALID_OPERATION;
@ -267,6 +282,9 @@ CosmsCoreFileError cosms_core_file_read_all(struct cosms_core_file *file, char *
return COSMS_CORE_FILE_OK;
}
/**
* @brief Try's to write specified number of bytes.
*/
CosmsCoreFileError cosms_core_file_write(struct cosms_core_file *file, char *buffer, unsigned int bytes_to_write, unsigned int *bytes_written) {
if ((file->mode & COSMS_CORE_FILE_MODE_WRITE) == 0) {
return COSMS_CORE_FILE_INVALID_OPERATION;
@ -294,6 +312,9 @@ CosmsCoreFileError cosms_core_file_write(struct cosms_core_file *file, char *buf
return COSMS_CORE_FILE_OK;
}
/**
* @brief Writes the full buffer to the file with support for writting large files.
*/
CosmsCoreFileError cosms_core_file_write_all(struct cosms_core_file *file, char *buffer, unsigned long long bytes_to_write) {
if ((file->mode & COSMS_CORE_FILE_MODE_WRITE) == 0) {
return COSMS_CORE_FILE_INVALID_OPERATION;
@ -344,6 +365,9 @@ CosmsCoreFileError cosms_core_file_write_all(struct cosms_core_file *file, char
return COSMS_CORE_FILE_OK;
}
/**
* @brief Deletes specified file from system.
*/
CosmsCoreFileError cosms_core_file_delete(const char *path) {
#if defined(__GNUC__)
if (unlink(path) == -1) {
@ -384,6 +408,9 @@ CosmsCoreFileError cosms_core_file_delete(const char *path) {
return COSMS_CORE_FILE_OK;
}
/**
* @brief Converts error code to a string that can be used for printing/logging errors.
*/
const char *cosms_core_file_error_string(CosmsCoreFileError error) {
switch(error) {
case COSMS_CORE_FILE_OK:

11
tests/test.h
View file

@ -9,15 +9,24 @@
implementation \
}
/**
* @brief Creates a list to export so it can be imported into the main test list.
*/
#define COSMS_CORE_TEST_EXPORT(name, ...) static const struct cosms_core_test cosms_core_test_##name[] = { \
__VA_ARGS__, \
0 \
}
/**
* @brief Creates a list of lists from exported tests so all tests can be easly executed.
*/
#define COSMS_CORE_TEST_START static const struct cosms_core_test *cosms_core_test_tests[] = {
#define COSMS_CORE_TEST_IMPORT(name) cosms_core_test_##name
#define COSMS_CORE_TEST_END };
/**
* @brief Runs all tests specified in the cosms_core_test_tests array;
*/
#define COSMS_CORE_TEST_RUN() \
for (unsigned long long index = 0; index < sizeof(cosms_core_test_tests) / sizeof(cosms_core_test_tests[0]); index += 1) { \
unsigned long long test_index = 0; \
@ -42,4 +51,4 @@ struct cosms_core_test {
const char *(*function)(void);
};
#endif
#endif /* COSMS_CORE_TEST */