/** \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.

The complete API reference is contained in the file \ref osl.h.

- 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.


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.

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://paraslash.systemlinux.org">paraslash</a>, a network audio
streaming system, and <a href="http://systemlinux.org/~maan/adu">adu
</a>, the advanced disk usage tool.

*/