Doxyfy fileio.h and fileio.c.

[ircu2.10.12-pk.git] / ircd / fileio.c

diff --git a/ircd/fileio.c b/ircd/fileio.c
index f6ba89d05c6510bf6bed48a84c32ce2fcc2de42c..38667868279b4837445f488bea02b211efa311db 100644 (file)
--- a/ircd/fileio.c
+++ b/ircd/fileio.c
@@ -18,6 +18,10 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
+/** @file
+ * @brief ANSI FILE* clone API implementation.
+ * @version $Id$
+ */
 #include "config.h"
 
 #include "fileio.h"
@@ -30,17 +34,23 @@
 #include <unistd.h>             /* read, write, open, close */
 #include <string.h>
 
-#define FB_EOF  0x01
-#define FB_FAIL 0x02
+#define FB_EOF  0x01            /**< File has reached EOF. */
+#define FB_FAIL 0x02            /**< File operation failed. */
 
+/** Tracks status and buffer for a file on disk. */
 struct FileBuf {
-  int fd;                       /* file descriptor */
-  char *endp;                   /* one past the end */
-  char *ptr;                    /* current read pos */
-  int flags;                    /* file state */
-  char buf[BUFSIZ];             /* buffer */
+  int fd;                       /**< file descriptor */
+  char *endp;                   /**< one past the end */
+  char *ptr;                    /**< current read pos */
+  int flags;                    /**< file state */
+  char buf[BUFSIZ];             /**< buffer */
 };
 
+/** Open a new FBFILE.
+ * @param[in] filename Name of file to open.
+ * @param[in] mode fopen()-style mode string.
+ * @return Pointer to newly allocated FBFILE.
+ */
 FBFILE* fbopen(const char *filename, const char *mode)
 {
   int openmode = 0;
@@ -88,6 +98,10 @@ FBFILE* fbopen(const char *filename, const char *mode)
   return fb;
 }
 
+/** Open a FBFILE from a file descriptor.
+ * @param[in] fd File descriptor to use.
+ * @param[in] mode fopen()-style mode string (ignored).
+ */
 FBFILE* fdbopen(int fd, const char *mode)
 {
   /*
@@ -103,6 +117,9 @@ FBFILE* fdbopen(int fd, const char *mode)
   return fb;
 }
 
+/** Close a FBFILE.
+ * @param[in] fb File buffer to close.
+ */
 void fbclose(FBFILE* fb)
 {
   assert(fb);
@@ -110,6 +127,10 @@ void fbclose(FBFILE* fb)
   MyFree(fb);
 }
 
+/** Attempt to fill a file's buffer.
+ * @param[in] fb File to operate on.
+ * @return Number of bytes read into buffer, or a negative number on error.
+ */
 static int fbfill(FBFILE * fb)
 {
   int n;
@@ -129,6 +150,10 @@ static int fbfill(FBFILE * fb)
   return n;
 }
 
+/** Get a single character from a file.
+ * @param[in] fb File to fetch from.
+ * @return Character value read, or EOF on error or end-of-file.
+ */
 int fbgetc(FBFILE * fb)
 {
   assert(fb);
@@ -137,6 +162,12 @@ int fbgetc(FBFILE * fb)
   return EOF;
 }
 
+/** Get a line of input from a file.
+ * @param[out] buf Output buffer to read to.
+ * @param[in] len Maximum number of bytes to write to buffer
+ * (including terminating NUL).
+ * @param[in] fb File to read from.
+ */
 char *fbgets(char *buf, size_t len, FBFILE * fb)
 {
   char *p = buf;
@@ -173,6 +204,11 @@ char *fbgets(char *buf, size_t len, FBFILE * fb)
   return buf;
 }
 
+/** Write a string to a file.
+ * @param[in] str String to write to file.
+ * @param[in] fb File to write to.
+ * @return Number of bytes written, or -1 on error.
+ */
 int fbputs(const char *str, FBFILE * fb)
 {
   int n = -1;
@@ -187,6 +223,11 @@ int fbputs(const char *str, FBFILE * fb)
   return n;
 }
 
+/** Get file status.
+ * @param[out] sb Receives file status.
+ * @param[in] fb File to get status for.
+ * @return Zero on success, -1 on error.
+ */
 int fbstat(struct stat *sb, FBFILE * fb)
 {
   assert(sb);