robodoc'd lib/silcutil/silcfileutil.h

diff --git a/TODO b/TODO
index 8a3cc11054a1566936aebb720d38e77fa6ee4793..998f6f847a9815532c6dfc0fc15afb5035c4e742 100644 (file)
--- a/TODO
+++ b/TODO
@@ -72,8 +72,6 @@ Manual (Do these to 0.9.x).
 
  o ROBOdoc documenting missing from lib/silcutil/silcdlist.h.
 
- o ROBOdoc documenting missing from lib/silcutil/silcfileutil.h.
-
  o ROBOdoc documenting missing from lib/silccrypt/silccipher.h.
 
  o ROBOdoc documenting missing from lib/silccrypt/silcpkcs.h.

diff --git a/lib/silcutil/silcfileutil.c b/lib/silcutil/silcfileutil.c
index 1435da0d97ff53aa7820b4e74e2b256edcdd6d1d..7d2d14757281af64b6f1e7ae737fa72ed1cd7fe6 100644 (file)
--- a/lib/silcutil/silcfileutil.c
+++ b/lib/silcutil/silcfileutil.c
@@ -1,6 +1,6 @@
 /*
 
-  silcfileutil.c 
+  silcfileutil.c
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
@@ -45,7 +45,7 @@ int silc_file_read(int fd, unsigned char *buf, SilcUInt32 buf_len)
   return read(fd, (void *)buf, buf_len);
 }
 
-/* Writes `buffer' of length of `len' to file descriptor `fd. */
+/* Writes `buffer' of length of `len' to file descriptor `fd'. */
 
 int silc_file_write(int fd, const char *buffer, SilcUInt32 len)
 {
@@ -61,42 +61,42 @@ int silc_file_close(int fd)
 
 /* Writes a buffer to the file. */
 
-int silc_file_writefile(const char *filename, const char *buffer, 
+int silc_file_writefile(const char *filename, const char *buffer,
                        SilcUInt32 len)
 {
   int fd;
-        
+
   if ((fd = creat(filename, 0644)) == -1) {
     SILC_LOG_ERROR(("Cannot open file %s for writing: %s", filename,
                    strerror(errno)));
     return -1;
   }
-  
-  if ((silc_file_write(fd, buffer, len)) == -1) {
+
+  if (silc_file_write(fd, buffer, len) == -1) {
     SILC_LOG_ERROR(("Cannot write to file %s: %s", filename, strerror(errno)));
     silc_file_close(fd);
     return -1;
   }
 
   silc_file_close(fd);
-  
+
   return 0;
 }
 
 /* Writes a buffer to the file.  If the file is created specific mode is
    set to the file. */
 
-int silc_file_writefile_mode(const char *filename, const char *buffer, 
+int silc_file_writefile_mode(const char *filename, const char *buffer,
                             SilcUInt32 len, int mode)
 {
   int fd;
-        
+
   if ((fd = creat(filename, mode)) == -1) {
     SILC_LOG_ERROR(("Cannot open file %s for writing: %s", filename,
                    strerror(errno)));
     return -1;
   }
-  
+
   if ((silc_file_write(fd, buffer, len)) == -1) {
     SILC_LOG_ERROR(("Cannot write to file %s: %s", filename, strerror(errno)));
     silc_file_close(fd);
@@ -104,7 +104,7 @@ int silc_file_writefile_mode(const char *filename, const char *buffer,
   }
 
   silc_file_close(fd);
-  
+
   return 0;
 }
 
@@ -140,9 +140,9 @@ char *silc_file_readfile(const char *filename, SilcUInt32 *return_len)
     silc_file_close(fd);
     return NULL;
   }
-  
+
   buffer = silc_calloc(filelen + 1, sizeof(char));
-  
+
   if ((silc_file_read(fd, buffer, filelen)) == -1) {
     memset(buffer, 0, sizeof(buffer));
     silc_file_close(fd);
@@ -160,7 +160,7 @@ char *silc_file_readfile(const char *filename, SilcUInt32 *return_len)
   return buffer;
 }
 
-/* Returns files size. Returns 0 on error. */
+/* Returns the size of `filename'. Returns 0 on error. */
 
 SilcUInt64 silc_file_size(const char *filename)
 {

diff --git a/lib/silcutil/silcfileutil.h b/lib/silcutil/silcfileutil.h
index 80624ed5e89f0d3bb247077f75e0d01be73a20b3..f388e25a876c17cb1bf900b9c5ab05fbfc8da757 100644 (file)
--- a/lib/silcutil/silcfileutil.h
+++ b/lib/silcutil/silcfileutil.h
@@ -1,6 +1,6 @@
 /*
 
-  silcfileutil.h 
+  silcfileutil.h
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
@@ -17,10 +17,12 @@
 
 */
 
-/****h* silcutil/Silc File Util Interface
+/****h* silcutil/SILC File Util Interface
  *
  * DESCRIPTION
  *
+ *    The SILC File Util Interface is a small set of functions that provides a
+ *    portable access method to the filesystem.
  *
  ***/
 
@@ -29,15 +31,133 @@
 
 /* Prototypes */
 
+/****f* silcutil/SilcFileUtilAPI/silc_file_open
+ *
+ * SYNOPSIS
+ *
+ *    int silc_file_open(const char *filename, int flags);
+ *
+ * DESCRIPTION
+ *
+ *    Opens a file indicated by the filename `filename' with flags indicated
+ *    by `flags'.  The opening permission defaults to 0600.
+ *
+ ***/
 int silc_file_open(const char *filename, int flags);
+
+/****f* silcutil/SilcFileUtilAPI/silc_file_open_mode
+ *
+ * SYNOPSIS
+ *
+ *    int silc_file_open_mode(const char *filename, int flags, int mode);
+ *
+ * DESCRIPTION
+ *
+ *    Opens a file indicated by the filename `filename' with flags indicated
+ *    by `flags'.  The argument `mode' specifies the permissions to use in
+ *    case a new file is created.
+ *
+ ***/
 int silc_file_open_mode(const char *filename, int flags, int mode);
+
+/****f* silcutil/SilcFileUtilAPI/silc_file_read
+ *
+ * SYNOPSIS
+ *
+ *    int silc_file_read(int fd, unsigned char *buf, SilcUInt32 buf_len);
+ *
+ * DESCRIPTION
+ *
+ *    Reads data from file descriptor `fd' to `buf'.
+ *
+ ***/
 int silc_file_read(int fd, unsigned char *buf, SilcUInt32 buf_len);
+
+/****f* silcutil/SilcFileUtilAPI/silc_file_write
+ *
+ * SYNOPSIS
+ *
+ *    int silc_file_write(int fd, const char *buffer, SilcUInt32 len);
+ *
+ * DESCRIPTION
+ *
+ *    Writes `buffer' of length of `len' to file descriptor `fd'.
+ *
+ ***/
 int silc_file_write(int fd, const char *buffer, SilcUInt32 len);
+
+/****f* silcutil/SilcFileUtilAPI/silc_file_close
+ *
+ * SYNOPSIS
+ *
+ *    int silc_file_close(int fd);
+ *
+ * DESCRIPTION
+ *
+ *    Closes file descriptor previously opened with silc_file_open().
+ *
+ ***/
 int silc_file_close(int fd);
+
+/****f* silcutil/SilcFileUtilAPI/silc_file_readfile
+ *
+ * SYNOPSIS
+ *
+ *    char *silc_file_readfile(const char *filename, SilcUInt32 *return_len);
+ *
+ * DESCRIPTION
+ *
+ *    Reads the content of `filename' to a buffer.  The allocated buffer is
+ *    returned.
+ *    If the `return_len' pointer is not NULL, it's filled with the length of
+ *    the file.
+ *
+ ***/
 char *silc_file_readfile(const char *filename, SilcUInt32 *return_len);
-int silc_file_writefile(const char *filename, const char *buffer, SilcUInt32 len);
-int silc_file_writefile_mode(const char *filename, const char *buffer, 
+
+/****f* silcutil/SilcFileUtilAPI/silc_file_writefile
+ *
+ * SYNOPSIS
+ *
+ *    int silc_file_writefile(const char *filename, const char *buffer,
+ *                            SilcUInt32 len);
+ *
+ * DESCRIPTION
+ *
+ *    Writes a buffer to the file.  If the file is created specific mode is
+ *    set to the file.
+ *
+ ***/
+int silc_file_writefile(const char *filename, const char *buffer,
+                       SilcUInt32 len);
+
+/****f* silcutil/SilcFileUtilAPI/silc_file_writefile_mode
+ *
+ * SYNOPSIS
+ *
+ *    int silc_file_writefile_mode(const char *filename, const char *buffer,
+ *                                 SilcUInt32 len, int mode);
+ *
+ * DESCRIPTION
+ *
+ *    Writes a buffer to the file.  If the file is created the specified `mode'
+ *    is set to the file.
+ *
+ ***/
+int silc_file_writefile_mode(const char *filename, const char *buffer,
                             SilcUInt32 len, int mode);
+
+/****f* silcutil/SilcFileUtilAPI/silc_file_size
+ *
+ * SYNOPSIS
+ *
+ *    SilcUInt64 silc_file_size(const char *filename);
+ *
+ * DESCRIPTION
+ *
+ *    Returns the size of `filename'. Returns 0 on error.
+ *
+ ***/
 SilcUInt64 silc_file_size(const char *filename);
 
-#endif /* SILCFILEUTIL_H */
+#endif /* !SILCFILEUTIL_H */