librta:   Access Your Running Program

Live Demo
Table Editor

Contact Us!

Frequently Asked Questions

General questions

Building, modifying, and understanding librta

General questions

What is librta?
Librta is library that lets PostgreSQL clients talk to your daemon using SQL. It is not a stand-alone database server but a library which presents your program's internal structures and arrays as if they were database tables. Your program needs to open a socket to allow the clients to connect and you have to fill in two librta data structure to tell librta about the tables and columns you want to make visible as Postgres tables.

What is the purpose of librta?
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 program's internal data as if the data were in a database.

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. Librta lets you view your program's internal tables (linked lists or 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 and well done. PostgreSQL offers a simple, well documented protocol to the client. (BTW: Our thanks to the designers and tech-writers for PostgreSQL.)

What SQL commands are implemented?
Only four: SELECT, UPDATE, INSERT, and DELETE, and even these are only a subset of their PostgreSQL equivalents. See rta.h for the syntax details of the commands. While librta does not implement transactions, we've found that in practice most commands are self contained and transactions are not needed.

What SQL/Postgres commands are not implemented?
Since this is not a database, it does not need the usual PostgreSQL meta tables, nor does it need CREATE TABLE, ALTER TABLE, or DROP TABLE.

The command line tool for PostgreSQL, psql, will connect to a program with librta, 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?
Since this is not a database and just an API to your data, only SELECT and UPDATE are not really necessary.

Who should not use librta?
Librta 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 with different structure definitions at each branch.

How big is it?
The stripped shared-object SQL interface library ( is 56 KB and the static (.a) library is 50 KB. On NuttX on an ARM M3 the library size is about 35 KB.

Do I need to know SQL to use librta?
Not really. Usually only two commands are required and they match pretty well with the intuitive idea of "change this column in this table where ...". It is pretty simple.

How difficult is it to learn and use librta? 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.

Does it work with linked lists and B-trees?
Yes, it works with linked lists and B-trees. Table definitions include an optional iterator routine which steps from one row to the next. If your program can step from one element to the next you can define an iterator for it. See the API spec for more details on iterators.

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.

Do you need/take donations?
Please send bug reports and change requests. Send money to the Free Software Foundation.

Does hurt or help security?
It depends. Your application can be very secure using using Unix sockets that are owned by root and have 0600 permissions. Forcing the data into an SQL form may help prevent some kinds of attacks. On the other hand, using TCP sockets makes debugging much easier and makes it easy to work with web-sockets and some other types of web technology.

Building, modifying, and understanding librta

What do I need to do to use librta in my program?
You need to describe each table you wish to make available. A typical table might be an array of structures. Each member of the structure forms a column of the table and each instance of the structure is a row. You need to describe the table by giving the 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 tools are available to explore librta tables?
Librta uses two internal tables (rta_tables and rta_columns) to store information about all of the tables visible to librta. It includes a "table editor" written in PHP that lets you use a web browser to view and edit any table in your application. The librta table editor does not need prior knowledge about the tables since it can read everything it needs from the two meta tables. Follow the "Live Demo" link to see the table editor in action.

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 (bison) and lex (flex) to build librta.

Do I need the Postgres libraries?
Your daemon application does not need any libraries or include files from the PostgreSQL distribution, but your client applications probably will.

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 on Red Hat, SUSE, and Ubuntu systems. Builds are also available for FreeBSD, Macintosh and Windows. It also works on NuttX although there is no package for it.

Can I add my own data type?
Sure! 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 librta, 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 librta 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 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 rta_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 rta_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.

Can I export a simple variable?
Sure. Just define a single column for your variable and a table with a single row. Simple variables, single structures, linked lists, or arrays of structures are all easy to make visible as tables.

Is librta thread safe?
Librta 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:

  • Update to the latest PostgreSQL protocol
  • UTF-8 support
  • printf format string in the column definition
  • ability to register more than one trigger per column
  • secure login maintaining Postgres compatibility
  • Add support in shared memory by adding locking
  • specify pre or post for the write callback
  • count(*) function
  • add a column data type of "table" to allow nested tables
  • make it thread safe

Download Page

Source Code
  Source Tarball
  PPA Repository
  Debian Packages
  RPM Packages