[GRASS-SVN] r58834 - grass/trunk/lib/gis

[svn_grass at osgeo.org]

Author: neteler
Date: 2014-02-01 14:10:43 -0800 (Sat, 01 Feb 2014)
New Revision: 58834

Modified:
   grass/trunk/lib/gis/mkstemp.c
Log:
libgis: attempt to document G_mkstemp() etc according to http://lists.osgeo.org/pipermail/grass-dev/2014-January/066964.html

Modified: grass/trunk/lib/gis/mkstemp.c
===================================================================
--- grass/trunk/lib/gis/mkstemp.c	2014-02-01 21:56:33 UTC (rev 58833)
+++ grass/trunk/lib/gis/mkstemp.c	2014-02-01 22:10:43 UTC (rev 58834)
@@ -1,3 +1,16 @@
+/*!
+ * \file lib/gis/mkstemp.c
+ *
+ * \brief GIS Library - Temporary file functions.
+ *
+ * (C) 2014 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Glynn Clements
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <errno.h>
@@ -68,11 +81,49 @@
 }
 
 
+/*!
+ * \brief Opens a temporary file.
+ *
+ * This routine opens the file.
+ *
+ * The last two take the arguments "flags" and "mode". "flags" should be
+ * O_WRONLY or O_RDWR, plus any other desired flags (e.g. O_APPEND).
+ * "mode" is the file mode (0666 would be typical).
+ *
+ * The functions does not use the PID, although the caller can do so.
+ *
+ * In theory, up to 26^5 (= ~12 million) filenames will be attempted
+ * until it finds one which doesn't exist.
+ *
+ * <b>Note:</b> <i>G_mktemp()</i> as such it is prone to race
+ * conditions (some other process may create that file after G_mktemp()
+ * returns).
+ *
+ * \return file name
+ */
 char *G_mktemp(char *template)
 {
     return G__mkstemp(template, 0, 0) < 0 ? NULL : template;
 }
 
+/*!
+ * \brief Returns a file descriptor.
+ *
+ * This routine opens the file and returns a descriptor.
+ *
+ * The last two take the arguments "flags" and "mode". "flags" should be
+ * O_WRONLY or O_RDWR, plus any other desired flags (e.g. O_APPEND).
+ * "mode" is the file mode (0666 would be typical).
+ *
+ * The functions does not use the PID, although the caller can do so.
+ *
+ * In theory, up to 26^5 (= ~12 million) filenames will be attempted
+ * until it finds one which doesn't exist.
+ *
+ *
+ * \return file descriptor
+ */
+
 int G_mkstemp(char *template, int flags, int mode)
 {
 
@@ -91,6 +142,23 @@
     return G__mkstemp(template, flags | O_CREAT | O_EXCL, mode);
 }
 
+/*!
+ * \brief Returns a file descriptor.
+ *
+ * This routine opens the file and returns a FILE*.
+ *
+ * The last two take the arguments "flags" and "mode". "flags" should be
+ * O_WRONLY or O_RDWR, plus any other desired flags (e.g. O_APPEND).
+ * "mode" is the file mode (0666 would be typical).
+ *
+ * The functions does not use the PID, although the caller can do so.
+ *
+ * In theory, up to 26^5 (= ~12 million) filenames will be attempted
+ * until it finds one which doesn't exist.
+ *
+ * \return FILE*
+ */
+
 FILE *G_mkstemp_fp(char *template, int flags, int mode)
 {
     const char *fmode = (flags & O_ACCMODE == O_RDWR)