README

   1 Libsqlfs
   2
   3 Copyright 2006, Palmsource, Inc., an ACCESS company.
   4 Sunnyvale, California, USA
   5
   6 Libsqlfs is free/open source software distributed under the GNU Lesser
   7 General Public License, version 2 or later versions as published by the Free
   8 Software Foundation.  See the file COPYING for the complete licensing terms.
   9
  10 Introduction
  11 ============
  12
  13
  14 The libsqlfs library implements a POSIX style file system on top of an
  15 SQLite database.  It allows applications to have access to a full read/write
  16 file system in a single file, complete with its own file hierarchy and name
  17 space.  This is useful for applications which needs structured storage, such
  18 as embedding documents within documents, or management of configuration
  19 data or preferences.  Libsqlfs can be used as an shared library, or it can be
  20 built as a FUSE (Linux File System in User Space) module to allow a libsqlfs
  21 database to be accessed via OS level file system interfaces by normal
  22 applications.
  23
  24
  25 Rational
  26 ========
  27
  28 PalmSource software developers recently created libsqlfs.  This library is an
  29 adjunct to the very popular open source SQLite database software.  Libsqlfs
  30 was created as part of PalmSource's ALP mobile phone platform, but it is
  31 useful in many other applications too.
  32
  33 The libsqlfs library provides an easy way for applications to put an
  34 entire read/write file system into a relational database as a single file
  35 in the host file system.  Such a file system can easily be moved around,
  36 backed up or restored as a single file.  But the file system can also be
  37 accessed as individual files.  This provides great flexibility and
  38 convenience.
  39
  40 We concluded that a simpler way to meet our needs was to write a library
  41 that supported  the POSIX file system semantics on an SQL database.  This
  42 brings the benefits of a real database, such as transactions and
  43 concurrency control, and allows us to have complete control over the
  44 schema of the preferences, so we can allow additional metadata such as
  45 value types, permissions and access control lists. Our libsqlfs registry
  46 can accommodate small preference values such as a number, and large
  47 binary objects such as an video clip.   The library provides a generic
  48 file system layer that maps a file system onto a SQLite database, and
  49 supports a POSIX file system semantics.
  50
  51 To speed development, we built our file system mapping layer as a File
  52 System In User Space (FUSE) module.  FUSE is another open source
  53 project.  It is a kernel module that supports user-level implementations
  54 of file systems. Our design allows libsqlfs to implement a real file
  55 system at the OS level, and apply real file system operations on it.  We
  56 tested the complete build process of gcc and the Linux kernel on top of
  57 libsqlfs, and we successfully executed fsx.c, the Apple file system test
  58 tool, against libsqlfs.
  59
  60 Today the ALP Global Settings component uses libsqlfs as the storage
  61 back-end.  Libsqlfs provides an easy way for applications to support a
  62 read/write file system totally contained in a relational database as a single
  63 file in the host file system, without using SQL statements.  Libsqlfs
  64 provides a superset of the storage features of GConf, and can be used as the
  65 storage back end of other desktop preference services.  Libsqlfs is also
  66 useful wherever developers need to organize data, and sometimes treat it as
  67 one file, and at other times treat it as a collection of individually
  68 writable files.
  69
  70
  71 Installation
  72 ============
  73
  74 * As a Library
  75
  76 Libsqlfs provides a GNU autoconf/automake based build system for building as
  77 an application library.  To build, please follow the normal GNU configure
  78 conventions.  Normally, the following command is all what's needed:
  79
  80 ./configure --prefix=<install dir>
  81 make && make install
  82
  83 <install dir> defaults to /usr/local if not specified.
  84
  85 You have to be root for installing into system directories such as
  86 /usr/local.
  87
  88 Both a static library and a shared library are built, unless you specify
  89 otherwise via options to configure.
  90
  91 * As an FUSE module
  92
  93 Currently FUSE module build is not integrated with the configure script;
  94 instead a script compile_fuse is supplied for building the module.  You may
  95 need to edit the include paths to adjust for your particular environment.
  96
  97 After running the script you shall have an executable called fuse_libsqlfs.
  98 Run it as root to start a FUSE session on top of libsqlfs:
  99
 100 fuse_libsqlfs <mnt point>
 101
 102 then you shall see the libsqlfs file space exposed, and
 103 can be accessed by normal applications,  via the <mnt point>.
 104
 105 example:
 106
 107 fuse_libsqlfs /mnt/sqlfs &
 108
 109 ls /mnt/sqlfs
 110
 111 The location of the SQLite database is hard-coded in fuse_main.c.  Change the
 112 argument to sqlfs_init() to suit your needs.
 113
 114 APIs
 115 ====
 116
 117 A libsqlfs session is represented by an object of type sqlfs_t.  All APIs
 118 require an explicit reference to a valid sqlfs_t.
 119
 120 Each file is a "key" in the internal libsqlfs vocabulary.  File metadata are
 121 represented as objects of the sturct key_attr.  File contents are represented
 122 by the struct key_value.
 123
 124 File metadata are the normal POSIX file attributes as expected except an
 125 additional "type" which can not be visible via the normal file attribute
 126 functions.  The "type" is used to support the specific needs of the setting
 127 registry application and can be one of the following:
 128
 129 Null
 130 Dir
 131 Integer (32-bit)
 132 Double (a C double)
 133 String (a C zero-terminated string)
 134 Sym_link (symbolic link)
 135 Bool  (a boolean)
 136 List (a Glib list of values)
 137 Blob (a binary object)
 138
 139 Note all other file system primitives do not make use of the "type"; to them
 140 all files are blobs. At this point the "type" is meant for use by higher up
 141 application logic in applications using libsqlfs.
 142
 143 Libsqlfs started as an FUSE module so it implements the primitives as
 144 defined by FUSE version 2.5.3.  Specifically, the following file system
 145 primitives are implemented:
 146
 147
 148 int sqlfs_proc_getattr(sqlfs_t *, const char *path, struct stat *stbuf);
 149 int sqlfs_proc_access(sqlfs_t *, const char *path, int mask);
 150 int sqlfs_proc_readlink(sqlfs_t *, const char *path, char *buf, size_t size);
 151 int sqlfs_proc_readdir(sqlfs_t *, const char *path, void *buf, fuse_fill_dir_t filler,
 152                   off_t offset, struct fuse_file_info *fi);
 153 int sqlfs_proc_mknod(sqlfs_t *, const char *path, mode_t mode, dev_t rdev);
 154 int sqlfs_proc_mkdir(sqlfs_t *, const char *path, mode_t mode);
 155 int sqlfs_proc_unlink(sqlfs_t *, const char *path);
 156 int sqlfs_proc_rmdir(sqlfs_t *, const char *path);
 157 int sqlfs_proc_symlink(sqlfs_t *, const char *path, const char *to);
 158 int sqlfs_proc_rename(sqlfs_t *, const char *from, const char *to);
 159 int sqlfs_proc_link(sqlfs_t *, const char *from, const char *to);
 160 int sqlfs_proc_chmod(sqlfs_t *, const char *path, mode_t mode);
 161 int sqlfs_proc_chown(sqlfs_t *, const char *path, uid_t uid, gid_t gid);
 162 int sqlfs_proc_truncate(sqlfs_t *, const char *path, off_t size);
 163 int sqlfs_proc_utime(sqlfs_t *, const char *path, struct utimbuf *buf);
 164 int sqlfs_proc_open(sqlfs_t *, const char *path, struct fuse_file_info *fi);
 165 int sqlfs_proc_read(sqlfs_t *, const char *path, char *buf, size_t size, off_t offset, struct
 166     fuse_file_info *fi);
 167 int sqlfs_proc_write(sqlfs_t *, const char *path, const char *buf, size_t size, off_t offset,
 168     struct fuse_file_info *fi);
 169 int sqlfs_proc_statfs(sqlfs_t *, const char *path, struct statvfs *stbuf);
 170 int sqlfs_proc_release(sqlfs_t *, const char *path, struct fuse_file_info *fi);
 171 int sqlfs_proc_fsync(sqlfs_t *, const char *path, int isfdatasync, struct fuse_file_info *fi);
 172
 173
 174 Their semantics are as defined by the FUSE documentation and the
 175 corresponding Unix file system calls.  Following the FUSE conventions, all
 176 file or key paths must be absolute and start with a '/'.  Applications can
 177 provide their own logic for relative paths before passing the "normalized"
 178 absolute paths to these FUSE primitive routines.
 179
 180 Extended attributes are not yet supported in this version.
 181
 182 In addition, other APIs provide environment setup, support for
 183 transaction and convenience functions:
 184
 185 int sqlfs_init(const char *)
 186     initialize the libsqlfs library and sets the default database file name.
 187
 188 int sqlfs_open(const char *db, sqlfs_t **);
 189     creates a new connection to the libsqlfs database.  The first argument,
 190     if not NULL,specifies a different database file from the default.
 191
 192 int sqlfs_close(sqlfs_t *);
 193     closes and frees a libsqlfs connection.
 194
 195
 196 int sqlfs_del_tree(sqlfs_t *sqlfs, const char *key);
 197     deletes a whole subtree.
 198
 199 int sqlfs_get_value(sqlfs_t *sqlfs, const char *key, key_value *value,
 200     size_t begin, size_t end);
 201     reads contents of a file contained in a range
 202     (between offsets begin and end)
 203
 204 int sqlfs_set_value(sqlfs_t *sqlfs, const char *key, const key_value *value,
 205     size_t begin,  size_t end);
 206     writes contents of a file contained in a range
 207     (between offsets begin and end)
 208
 209 int sqlfs_get_attr(sqlfs_t *sqlfs, const char *key, key_attr *attr);
 210     reads the metadata of a file
 211
 212 int sqlfs_set_attr(sqlfs_t *sqlfs, const char *key, const key_attr *attr);
 213     write the metadata of a file
 214
 215 int sqlfs_set_type(sqlfs_t *sqlfs, const char *key, const char *type);
 216     sets the "type" of the file content.
 217
 218 int sqlfs_begin_transaction(sqlfs_t *sqlfs);
 219     begins a SQLite transaction
 220
 221 int sqlfs_complete_transaction(sqlfs_t *sqlfs, int i);
 222     ends a SQLite transaction
 223
 224 Note the transaction supports "levels"; that is, transaction calls can be
 225 nested and libsqlfs maintains an internal level count of the current
 226 transaction level.  The actual SQLite transaction are only started when the
 227 level goes above 0 and only ended when the level falls to zero.
 228
 229 For a sample application showing the usage of libsqlfs, see the test
 230 program test.c in the test directory.
 231
 232 Supported Platforms
 233 ===================
 234
 235 To date, libsqlfs is tested on 32-bit i386 and StrongArm (Treo 650
 236 phone) GNU/Linux (Ubnutu).
 237
 238 Currently libsqlfs, when used as a library, only has been tested on GNU/Linux
 239 (Ubnutu and Red Hat  Fedora 5) although it shall be usable on any Unix like
 240 platforms where SQLite runs with at most minor changes.   It shall also work
 241 on the Cygwin enviroment but this is not tested.  Patches for different
 242 platform support are welcome.
 243
 244 For use at the OS level, libsqlfs only supports the FUSE on the Linux kernel
 245 on both 32-bit i386 and StrongArm.
 246
 247 Supported Database
 248 ==================
 249
 250 To date, only SQLite is supported.
 251
 252
 253
 254 For more information, please contact:
 255
 256 Peter van der Linden  peter.vanderlinden@palmsource.com
 257 Andy Tai, andy.tai@palmsource.com
 258