-/** \mainpage OSL Quick start
-
This document describes the steps which have to be performed in order
to create and use an osl table. The code sniplets in this section
-are taken from the file \ref osltar.c in the source distribution.
+are taken from the file `osltar.c` in the source distribution.
-The complete API reference is contained in the file \ref osl.h.
+The complete API reference is contained in the file `osl.h.`
-- Define an enum that assigns descriptive names to the columns
+Define an enum that assigns descriptive names to the columns
of your table. Example:
-\verbatim
-
-enum osltar_columns {
- OTC_NAME,
- OTC_DATA,
- NUM_OT_COLUMNS
-};
-
-\endverbatim
-
-The last element is is useful because the number of columns
-of your table must be specified later, see below.
-
-- Define an array of struct osl_column_description, one
-array member per column:
-
-\verbatim
-
-struct osl_column_description tar_table_cols[] = {
- [OTC_NAME] = {
- .storage_type = OSL_MAPPED_STORAGE,
- .storage_flags = OSL_RBTREE | OSL_UNIQUE,
- .name = "filename",
- .compare_function = string_compare,
- },
- [OTC_DATA] = {
- .storage_type = OSL_MAPPED_STORAGE,
- .name = "data",
- },
-};
-
-\endverbatim
-
-Three different storage types are available which may be
-selected on a per-column basis: \ref OSL_DISK_STORAGE, \ref
-OSL_MAPPED_STORAGE, and \ref OSL_NO_STORAGE.
-
-For columns of type OSL_MAPPED_STORAGE and OSL_NO_STORAGE an optional
-rbtree is maintained by the osl library which allows to quickly lookup
-rows by cell content. Whether or not an rbtree should be used must be
-specified in the storage_flags field which should contain the bitwise
-or of suitable \ref osl_storage_flags.
-
-If a column has an associated rbtree, i.e. if the OSL_RBTREE flag
-is set in the storage flags for the column, the compare_function
-field must be initialized to point to a function of type \ref
-osl_compare_func. In this example, \ref string_compare() is used,
-which is just a wrapper for strcmp() that interprets osl objects as
-C-strings and calls strcmp() on the object data.
-
-- Define a struct \ref osl_table_description and initialize
-it with the number of columns of your table and the column
-descriptions:
-
-\verbatim
-
-struct osl_table_description tar_table_desc = {
- .name = "tar_table",
- .num_columns = NUM_OT_COLUMNS,
- .column_descriptions = tar_table_cols,
- .dir = "/tmp/osltest"
-};
-
-\endverbatim
-
-- Create the table by calling \ref osl_create_table():
-
-\verbatim
-
-ret = osl_create_table(&tar_table_desc);
-
-\endverbatim
-
-- Open the newly created table by calling osl_open_table:
-
-\verbatim
-
-struct osl_table *table;
-ret = osl_open_table(&tar_table_desc, &table);
-
-\endverbatim
-
-- To add a new row to the table, you must define an array of struct
-osl_object of length NUM_OT_COLUMNS which holds the contents of the
-new row. Note that an osl object is just a blob: It consists of a
-data pointer and a size value. Once the array has been initialized,
-pass it to \ref osl_add_row() together with the table handle obtained
-from osl_open_table():
-
-\verbatim
-
-struct osl_object objs[NUM_OT_COLUMNS];
-/* ...init the array... */
-ret = osl_add_row(table, objs);
-
-\endverbatim
-
-- Close the table with \ref osl_close_table().
-
-\verbatim
-
-osl_close_table(table, OSL_MARK_CLEAN);
-
-\endverbatim
-
-The storage type of both columns of the table in this example
-is OSL_MAPPED_STORAGE, so you can later open the table again
-and retrieve its contents:
-
-\verbatim
-
-ret = osl_get_row(table, OTC_NAME, &obj, &row);
-if (ret < 0) {
- fprintf(stderr, "osl_get_row(%s): %s\n", name,
- osl_strerror(-ret));
- return ret;
-}
-ret = osl_get_object(table, row, OTC_DATA, &obj);
-
-\endverbatim
-
-The call to \ref osl_get_row() uses the rbtree of the OTC_NAME
-column to find the row whose object in the OTC_NAME column
-matches the given object obj. If a row was found, it is
-passed to \ref osl_get_object() which returns the object of
-the OTC_DATA column of this row.
-
+<pre>
+ enum osltar_columns {
+ OTC_NAME,
+ OTC_DATA,
+ NUM_OT_COLUMNS
+ };
+</pre>
+
+The last element is is useful because the number of columns of your
+table must be specified later, see below.
+
+Define an array of struct osl_column_description, one array member
+per column:
+
+<pre>
+ struct osl_column_description tar_table_cols[] = {
+ [OTC_NAME] = {
+ .storage_type = OSL_MAPPED_STORAGE,
+ .storage_flags = OSL_RBTREE | OSL_UNIQUE,
+ .name = "filename",
+ .compare_function = string_compare,
+ },
+ [OTC_DATA] = {
+ .storage_type = OSL_MAPPED_STORAGE,
+ .name = "data",
+ },
+ };
+</pre>
+
+Three different storage types are available which may be selected
+on a per-column basis: `OSL_DISK_STORAGE`, `OSL_MAPPED_STORAGE`, and
+`OSL_NO_STORAGE`.
+
+For columns of type `OSL_MAPPED_STORAGE` and `OSL_NO_STORAGE` an
+optional rbtree is maintained by the osl library which allows to
+quickly lookup rows by cell content. Whether or not an rbtree should
+be used must be specified in the `storage_flags` field which should
+contain the bitwise or of suitable `osl_storage_flags`.
+
+If a column has an associated rbtree, i.e. if the `OSL_RBTREE` flag
+is set in the storage flags for the column, the `compare_function`
+field must be initialized to point to a function of type
+`osl_compare_func`. In this example, `string_compare()` is used,
+which is just a wrapper for `strcmp()` that interprets osl objects
+as C-strings and calls `strcmp()` on the object data.
+
+Define a struct `osl_table_description` and initialize it with
+the number of columns of your table and the column descriptions:
+
+<pre>
+ struct osl_table_description tar_table_desc = {
+ .name = "tar_table",
+ .num_columns = NUM_OT_COLUMNS,
+ .column_descriptions = tar_table_cols,
+ .dir = "/tmp/osltest"
+ };
+</pre>
+
+Create the table by calling `osl_create_table()`:
+
+<pre>
+ ret = osl_create_table(&tar_table_desc);
+</pre>
+
+Open the newly created table by calling `osl_open_table()`:
+
+<pre>
+ struct osl_table *table;
+ ret = osl_open_table(&tar_table_desc, &table);
+</pre>
+
+To add a new row to the table, you must define an array of struct
+osl_object of length `NUM_OT_COLUMNS` which holds the contents of
+the new row. Note that an osl object is just a blob: It consists of
+a data pointer and a size value. Once the array has been initialized,
+pass it to `osl_add_row()` together with the table handle obtained from
+`osl_open_table()`:
+
+<pre>
+ struct osl_object objs[NUM_OT_COLUMNS];
+ /* ...init the array... */
+ ret = osl_add_row(table, objs);
+</pre>
+
+Close the table with `osl_close_table()`.
+
+<pre>
+ osl_close_table(table, OSL_MARK_CLEAN);
+</pre>
+
+The storage type of both columns of the table in this example is
+`OSL_MAPPED_STORAGE`, so you can later open the table again and
+retrieve its contents:
+
+<pre>
+ ret = osl_get_row(table, OTC_NAME, &obj, &row);
+ if (ret < 0) {
+ fprintf(stderr, "osl_get_row(%s): %s\n", name,
+ osl_strerror(-ret));
+ return ret;
+ }
+ ret = osl_get_object(table, row, OTC_DATA, &obj);
+</pre>
+
+The call to `osl_get_row()` uses the rbtree of the `OTC_NAME`
+column to find the row whose object in the `OTC_NAME` column
+matches the given object `obj`. If a row was found, it is
+passed to `osl_get_object()` which returns the object of
+the `OTC_DATA` column of this row.
This concludes the quick start document. Of course, libosl contains
many more public functions than those used above. For details on the
-C-API, look at the file \ref osl.h which contains the declarations of
-all public functions and the complete documentation of the public part
-of the library.
+C-API, look at the file `osl.h` which contains the declarations of
+all public functions and the complete documentation of the public
+part of the library.
The "examples" subdirectory of the source distribution
contains the full code of the above example and another
-small program which illustrates the use of columns of
-type OSL_NO_STORAGE. Larger applications using libosl are <a
-href="http://people.tuebingen.mpg.de/maan/paraslash/">paraslash</a>, a network audio
-streaming system, and <a href="http://people.tuebingen.mpg.de/maan/adu/">adu
-</a>, the advanced disk usage tool.
-
-*/
+small program which illustrates the use of columns of type
+`OSL_NO_STORAGE`. Larger applications using libosl are <a
+href="http://people.tuebingen.mpg.de/maan/paraslash/">paraslash</a>,
+a network audio streaming system, and <a
+href="http://people.tuebingen.mpg.de/maan/adu/">adu</a>, the advanced
+disk usage tool.
projects / osl.git / commitdiff