Run Time Access

Frequently Asked Questions

General questions

Building, modifying, and understanding RTA

General questions

What is RTA?
RTA is a memory resident database and virtual file system interface. It is not a stand-alone database server or file system but a library which offers up the program's internal structures and arrays as database tables or as files in a file system. The database interface uses a subset of the Postgres protocol and is compatible with the Postgres bindings for "C", PHP, and the Postgres command line tool, psql.

What is the purpose of RTA?
It provides a means for external programs to view and edit the tables in your running program. This makes debugging easier and means that the user interface parts of your system can be kept apart from the core functionality.

So, is this a database, or what?
No, it is *not* a database. It is an API which lets external programs view and edit your internal data as if the data were in a database or as files in a file system.

Is this like the /proc filesystem?
Yes, in a way. The /proc system lets you view the kernel's internal data as if the data were stored in files in a filesystem. RTA has two libraries, one lets you view your program's internal tables (arrays of structures) as if they were files in a file system, and the other lets you view your arrays of structures as if they were tables in a PostgreSQL database.

Why PostgreSQL?
Mostly because both the design and the documentation of the PostgreSQL protocol are very clean. PostgreSQL offers a simple, well documented protocol to the client. (Our thanks to the designers and tech-writers for PostgreSQL.)

What SQL commands are implemented?
Only two: SELECT and UPDATE, and even then it is only a subset of the usual SELECT and UPDATE. See rta.h for the syntax details of the commands. RTA does not implement transactions.

What SQL/Postgres commands are not implemented?
This is not a database. We do not implement INSERT or DELETE since tables are (for the most part) fixed in size. Nor do we have CREATE TABLE, ALTER TABLE, or DROP TABLE.

The command line tool for PostgreSQL, psql, will connect to a program with RTA, but none of the psql backslash commands will work (since most of the backslash commands require a real PostgreSQL database).

Why such a small subset of SQL?
This is not a database; it is an API. SELECT and UPDATE are the minimum needed to read and edit the data in your running program.

What file system commands are in RTA?
The read(), write(), and readdir() commands are implemented as is the stat() function. Minimal stubs are provided for both open() and truncate().

Who should not use RTA?
RTA is great if you have data already arranged as structs or as array of structs. It is a little more difficult to use if you have lots of structs pointing to other structs pointing to other structs. That is, it is a good fit for simple tables of data and is not a good fit for a deeply nested tree structure of data.

It is also best for single process applications where the data is in one memory space. For instance, it might not be a good fit for Apache which forks several equal, independent processes.

How big is it?
The stripped shared-object SQL interface library ( is 55 KB and the static (.a) library is 46 KB. The stripped virtual file system interface ( is 28KB and the static library is 11KB. Note that to use the virtual file system interface you need to load the SQL interface as well.

Do I need to know SQL to use RTA?
Not really. There are only two commands and they match pretty well with the intuitive idea of "change this column in this table where ...". It is pretty simple.
Also, the librtafs library lets you avoid SQL entirely if you wish.

How difficult is it to learn and use RTA?
It is easy to learn. There are only two important data structures (one to describe a table and one to describe a column) and only seven subroutines in the API. The tutorial elsewhere on this page should give you a pretty good idea of the simplicity of the approach.
It is simple but *may* require some effort on your part. Each table and each column in each table needs to be defined in a data structure. While simple, it can be a fair amount of work.

How do I report bugs?
Please select "Contact Info" from the menu above to open a query form. Please give as much detail as possible.

Where can I get help?
Please select "Contact Info" from the menu above to open a query form. Please give as much detail as possible.

Can I send you money?
Please send bug reports and change requests. Send money to the Free Software Foundation.

Building, modifying, and understanding RTA

What do I need to do to use RTA in my program?
You need to describe each table you wish to make available. A table is an array of structures. Each member of the structure forms a column of the table. The table description includes attributes of the table in general and a description of each column in the table. See the sample application and the API reference for more detail.

What libraries, tools and include files are needed?
We use the following system include files: libgen.h, limits.h, stdarg.h, stddef.h, stdio.h, stdlib.h, string.h, syslog.h, and the following system and utility calls: closelog(), dirname(), fclose(), fdopen(), fgets(), fopen(), fprintf(), free(), malloc(), memchr(), mkstemp(), offsetof(), openlog(), rename(), snprintf(), sprintf(), sscanf(), strcat(), strcmp(), strcpy(), strlen(), strncmp(), strncpy(), strstr(), syslog(), va_arg(), va_end(), va_start(). You will need yacc and lex to build RTA.
The virtual file system interface to RTA (librtafs) is built on top of librtadb and the "FUSE" package by Miklos Szeredi

Do I need the Postgres libraries?
Your application does not need any libraries or include files from the PostgreSQL distribution. Your *client* applications may need PostgreSQL libraries as appropriate.

Can I link to it statically?
Yes, You can link to the .a file or just include the .c files in the build of your application.

What has it been tested on?
It has been used successfully Red Hat 8.0 and 9.0, and on Mandrake 9.1 and 9.2 systems.

Can I add my own data type?
Yes. You will need to modify the lex program to recognize the new data type as well as the .c files which print or compare its values.

Why are there "magic" numbers in the code?
Several places in the code contain what seem like magic values. These are all related to the PostgreSQL protocol and should all be described by comments in the surrounding code.

Why are the pseudo-tables arrays of pointers?
The short answer is to save memory. If rta_add_table() were to copy the table definition your application would have the definition two places in memory: internal to RTA, and in your application code. By saving the pointers to the table and column definitions we avoid using lots of memory to duplicate data. Saving pointers has the second advantage of letting you change the table definition on the fly if needed.

Why do I get segmentation violations?
We've tried very hard to eliminate memory leaks and segmentation violations from the RTA package but some might have slipped through. A common source of problems is overrunning a string. Be sure to verify that your strings have the proper size specified in the column definitions.

How can I change the size of a table?
Allocate enough memory to store the new, larger table. Copy the old table into the new space. Initialize the new rows added. Copy the address of the new table into the "address" field of the table definition and update the "nrows" field with the new number of rows.

Why use native data type instead of INT4 and INT8?
The idea is to give easy access to *your* data structures. Since most programmers use the native int, long long, and float, we do too.

Why do I get "error while loading shared libraries:"?
You need to put the and files into one of the system library directories or you need to something like "export LD_LIBRARY_PATH=../src" in order to let the application find the library.

How big should I make the output buffer for dbcommand()?
It depends on the number of rows and the size and number of fields you request. You should be able to estimate the number of characters in your response. Assume that strings are returned with all bytes filled, that integers return 12 characters per field, longs return 24, and floats return 24. Thus if you request two integers, a 40 byte string and a float, you would need about 40+(2*12)+24=88 bytes. The Postgres overhead per row returned is about 4 bytes. Make the output buffer for dbcommand() big enough to hold the maximum number of rows you want times the size of each row. Be sure to use LIMIT and OFFSET to step through a big list of returned rows.

Why must a write() have all data in a single buffer?
There are two reasons. First, RTA requires a single write buffer in order to be sure that all table writes are atomic. Without atomic table writes we could not guarantee table consistency. Second, the FUSE package, upon which the file system interface is based, does not implement or use file descriptors. The write call has as input a path, buffer, count, and offset. This leaves open the possibility that two programs writing to the same row or column could conflict and leave the table an inconsistent state.

Can I export a simple variable?
Sure. Just define a single column for your variable and a table with a single row. You can make visible simple variables, single structures, or arrays of structures.

Which is better, the file system or the database interface?
The database interface is better in most applications. It is faster and it is atomic. That is, a single statement can do an update based on the results of WHERE clause. Our use of the file system interface has shown it to be a little fragile. You need to be careful to not leave a mounted file system when your program exits abnormally. This means you need some supervisory program to unmount the file system and possibly remove and re-install the fuse kernel module.

Is RTA thread safe?
RTA is not currently thread safe. Please contact the authors if this is very high on your wish list.

What is in the To-Do list?
Please let the authors know what features you would like added or removed from Run Time Access. No additional changes are anticipated at this time, but the list of possible changes includes: