style and fixed bug allocating too much memory in append file

lib/api/api.h

@@ -9,37 +9,137 @@ struct timespec;
 #define O_CREATE 1
 #define O_LOCK 2
 
-// struttura dati per la lista dei file aperti
-typedef struct openFile_s {
-	char *filename;          // nome del file
-	struct openFile_s *next;  // puntatore al prossimo elemento nella lista
-} openFile_t;
 
+/**
+ * @brief Opens a connection over the unix socket
+ *
+ * @param socketname path to the socket
+ * @param msec milliseconds between tries
+ * @param abstime maximum time spent tring to connect
+ * @return 0 if connection has been established, -1 if an error has occurred
+ */
+int openConnection(const char *sockname, int msec, const struct timespec abstime);
 
-int openConnection(const char* sockname, int msec, const struct timespec abstime);
+/**
+ * @brief Closes the connection to the server
+ *
+ * @param socketname path to the socket
+ * @return 0 if successful, -1 if an error has occurred
+ */
+int closeConnection(const char *sockname);
 
-int closeConnection(const char* sockname);
+/**
+ * @brief Open or create a file on the server
+ *
+ * @param pathname name of the file to open
+ * @param flags can be 0, O_CREATE, O_LOCK or O_CREATE | O_LOCK
+ * @return 0 if successful, -1 if an error has occurred
+ */
+int openFile(const char *pathname, int flags);
 
-int openFile(const char* pathname, int flags);
+/**
+ * @brief Reads a file on the server and saves the content to the buffer
+ *
+ * @param pathname name of the file to read
+ * @param buf buffer that will hold the content of the file read
+ * @param size size of the buffer
+ * @return 0 if successful, -1 if an error has occurred
+ *
+ * @note buf is not deallocated before being reassigned
+ */
+int readFile(const char *pathname, void** buf, size_t *size);
 
-int readFile(const char* pathname, void** buf, size_t* size);
+/**
+ * @brief Reads N files on the server
+ *
+ * @pre program must have rights over the directory
+ *
+ * @param N number of files to read, if N<1 all files available will be read
+ * @param dirname path to directory to write the files into
+ * @return 0 if successful, -1 if an error has occurred
+ */
+int readNFiles(int N, const char *dirname);
 
-int readNFiles(int N, const char* dirname);
+/**
+ * @brief Sends a file to the server
+ *
+ * @pre program must have rights over the directory
+ *
+ * @param pathname name of the file to write
+ * @param dirname directory in witch files sent from the server may be written
+ * @return 0 if successful, -1 if an error has occurred
+ */
+int writeFile(const char *pathname, const char *dirname);
 
-int writeFile(const char* pathname, const char* dirname);
+/**
+ * @brief Appends the buffer to the file specified
+ *
+ * @pre program must have rights over the directory
+ *
+ * @param pathname name of the file to append to
+ * @param buf data to append
+ * @param size size of data to append
+ * @param dirname directory in witch files sent from the server may be written
+ * @return 0 if successful, -1 if an error has occurred
+ */
+int appendToFile(const char *pathname, void *buf, size_t size, const char *dirname);
 
-int appendToFile(const char* pathname, void* buf, size_t size, const char* dirname);
+/**
+ * @brief Acquire the lock over the file
+ *
+ * @param pathname name of the file to lock
+ * @return 0 if successful, -1 if an error has occurred
+ */
+int lockFile(const char *pathname);
 
-int lockFile(const char* pathname);
-
-int unlockFile(const char* pathname);
+/**
+ * @brief Relese the lock over the file
+ *
+ * @pre file must be opened and locked
+ *
+ * @param pathname name of the file to unlock
+ * @return 0 if successful, -1 if an error has occurred
+ */
+int unlockFile(const char *pathname);
 
+/**
+ * @brief Closes the file
+ *
+ * @pre file must be opened
+ *
+ * @param pathname name of the file to close
+ * @return 0 if successful, -1 if an error has occurred
+ */
 int closeFile(const char *pathname);
 
-int removeFile(const char* pathname);
+/**
+ * @brief Deletes the file from the server
+ *
+ * @pre file must be opened and locked
+ *
+ * @param pathname name of the file to close
+ * @return 0 if successful, -1 if an error has occurred
+ */
+int removeFile(const char *pathname);
 
-int setDirectory(char* Dir, int rw);
+// -----------------------------------------------------------------------------
+/**
+ * @brief Sets the default directory to saves files into if a capacity miss
+ *        occurs
+ *
+ * @param Dir name of the directory
+ * @param rw 0 for read directory, 1 for writing directory
+ * @return 0 if successful, -1 if an error has occurred
+ */
+int setDirectory(char *Dir, int rw);
 
+/**
+ * @brief Sets verbose mode and where to print
+ *
+ * @param p true if printing, 0 if not printing
+ * @param stream where to print
+ * @return 0 if successful, -1 if an error has occurred
+ */
 void printInfo(int p, FILE *stream);
 
 #endif /* _API_CLIENT */