osl_get_nth_row(): Always initialize result pointer.

[osl.git] / osl.h.in

diff --git a/osl.h.in b/osl.h.in
index 5d81459a380772fd63764dcae930119a1c938258..17bfbc16656abf7b6ac0a928378cc7529dbb00cf 100644 (file)
--- a/osl.h.in
+++ b/osl.h.in
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2007-2008 Andre Noll <maan@systemlinux.org>
+ * Copyright (C) 2007-2009 Andre Noll <maan@tuebingen.mpg.de>
  *
  * Licensed under the GPL v2. For licencing details see COPYING.
  */
@@ -7,6 +7,7 @@
 /** \file osl.h User interface for the object storage layer. */
 
 #include <sys/mman.h>
+#include <inttypes.h>
 
 /** Export all declarations in this file. */
 #pragma GCC visibility push(default)
@@ -41,7 +42,7 @@ enum osl_storage_type {
         OSL_DISK_STORAGE,
        /**
         * Objects for columns of this type are volatile: They are only stored
-        * in memory and are discarded once the table gets closed.
+        * in memory and are discarded when the table is closed.
         */
        OSL_NO_STORAGE
 };
@@ -61,7 +62,7 @@ enum osl_storage_flags {
        OSL_RBTREE = 1,
        /** The data for this column will have constant size. */
        OSL_FIXED_SIZE = 2,
-       /** All values of this column will be different. */
+       /** All values are different. Must be set if \p OSL_RBTREE is set. */
        OSL_UNIQUE = 4,
        /** Do not free the data for this column (\p OSL_NO_STORAGE). */
        OSL_DONT_FREE = 8
@@ -74,10 +75,10 @@ struct osl_row;
 
 /**
  * In order to build up an rbtree a compare function for the objects must be
- * specified. Such a function always takes pointers to the two objects to be
- * compared. It must return -1, zero, or 1, if the first argument is considered
- * to  be  respectively less than, equal to, or greater than the second. If two
- * members compare as equal, their order in the sorted array is undefined.
+ * provided. This function takes pointers to the two objects to be compared. It
+ * must return -1, zero, or 1, if the first argument is considered to be
+ * respectively less than, equal to, or greater than the second. If two members
+ * compare as equal, their order in the rbtree is undefined.
  */
 typedef int osl_compare_func(const struct osl_object *obj1,
        const struct osl_object *obj2);
@@ -94,14 +95,14 @@ typedef int osl_rbtree_loop_func(struct osl_row *row, void *data);
  * Describes one column of a osl table.
  */
 struct osl_column_description {
-       /** One of the tree possible types of storage, \sa osl_storage_type. */
+       /** One of the three possible types of storage, \sa osl_storage_type. */
        uint16_t storage_type;
        /** Specifies further properties of the column, \sa osl_storage_flags. */
        uint16_t storage_flags;
        /**
         * The column name determines the name of the directory where all data
         * for this column will be stored. Its hash is stored in the table
-        * header. This field is ignored if the storage type is \a NO_STORAGE
+        * header. This field is ignored if the storage type is \a NO_STORAGE.
         */
        char *name;
        /**
@@ -115,7 +116,7 @@ struct osl_column_description {
        osl_compare_func *compare_function;
        /**
         * If the \a OSL_FIXED_SIZE flag is set for this column, this value
-        * determines the fixed size of all objects of this column. It is
+        * describes the number of bytes of each object of this column. It is
         * ignored, if \a OSL_FIXED_SIZE is not set.
         */
        uint32_t data_size;
@@ -125,7 +126,10 @@ struct osl_column_description {
  * Describes one osl table.
  */
 struct osl_table_description {
-       /** The directory which contains all files of this table. */
+       /**
+        * The directory which contains all files of this table. This may be
+        * either relative to the cwd or an absolute path.
+        */
        const char *dir;
        /**
         * The table name. A subdirectory of \a dir called \a name is created
@@ -144,9 +148,10 @@ struct osl_table_description {
 /** Flags to be passed to \a osl_close_table(). */
 enum osl_close_flags {
        /**
-        * The table header contains a "dirty" flag which specifies whether
-        * the table is currently open by another process. This flag specifies
-        * that the dirty flag should be cleared before closing the table.
+        * The table header contains a "dirty" flag which indicates whether the
+        * table is currently held open by another process. The \a
+        * OSL_MARK_CLEAN flag instructs libosl to clear the dirty flag when
+        * the table is closed.
         */
        OSL_MARK_CLEAN = 1,
        /**
@@ -209,7 +214,8 @@ int osl_close_table(struct osl_table *t, enum osl_close_flags flags);
  * Lookup \a obj in \a t and return the row containing \a obj. The column
  * specified by \a col_num must have an associated rbtree.
  *
- * \return Standard.
+ * \return Standard. \a result is set to \p NULL if and only if the function
+ * returns negative.
  *
  * \sa osl_storage_flags
  */
@@ -217,7 +223,7 @@ int osl_get_row(const struct osl_table *t, unsigned col_num,
        const struct osl_object *obj, struct osl_row **result);
 
 /**
- * Retrieve an object identified by row and column
+ * Retrieve an object identified by row and column.
  *
  * \param t Pointer to an open osl table.
  * \param row Pointer to the row.
@@ -378,7 +384,7 @@ int osl_rbtree_loop_reverse(const struct osl_table *t, unsigned col_num,
  * If the \p OSL_RBTREE flag is set for \a col_num, you \b MUST call this
  * function in order to change the contents of an object, even for volatile or
  * mapped columns of constant size (which may be updated directly if \p
- * OSL_RBTREE is not set).  Otherwise the rbtree might become corrupted.
+ * OSL_RBTREE is not set). Otherwise the rbtree might become corrupt.
  *
  * \return Standard
  */
@@ -444,8 +450,8 @@ int osl_rbtree_last_row(const struct osl_table *t, unsigned col_num,
  * \param result Row is returned here.
  *
  * Retrieve the n-th order statistic with respect to the compare function
- * of the rbtree column \a col_num. In other words, get that row with
- * \a n th greatest value in column \a col_num. It's an error if
+ * of the rbtree column \a col_num. In other words, get the row with
+ * \a n th greatest value in column \a col_num. It is an error if
  * \a col_num is not a rbtree column, or if \a n is larger than the
  * number of rows in the table.
  *