rtbl man page

rtbl_create, rtbl_destroy, rtbl_set_flags, rtbl_get_flags, rtbl_set_prefix, rtbl_set_separator, rtbl_set_column_prefix, rtbl_set_column_affix_by_id, rtbl_add_column, rtbl_add_column_by_id, rtbl_add_column_entry, rtbl_add_column_entry_by_id, rtbl_new_row, rtbl_format ā€” format data in simple tables


The roken library (libroken, -lroken)


#include <rtbl.h>

rtbl_add_column(rtbl_t table, const char *column_name, unsigned int flags);

rtbl_add_column_by_id(rtbl_t table, unsigned int column_id, const char *column_header, unsigned int flags);

rtbl_add_column_entry(rtbl_t table, const char *column_name, const char *cell_entry);

rtbl_add_column_entry_by_id(rtbl_t table, unsigned int column_id, const char *cell_entry);


rtbl_destroy(rtbl_t table);

rtbl_new_row(rtbl_t table);

rtbl_set_column_affix_by_id(rtbl_t table, unsigned int column_id , const, char, *prefix", const char *suffix);

rtbl_set_column_prefix(rtbl_t table, const char *column_name, const char *prefix);

unsigned int
rtbl_get_flags(rtbl_t table);

rtbl_set_flags(rtbl_t table, unsigned int flags);

rtbl_set_prefix(rtbl_t table, const char *prefix);

rtbl_set_separator(rtbl_t table, const char *separator);

rtbl_format(rtbl_t table , FILE, *file");


This set of functions assemble a simple table consisting of rows and columns, allowing it to be printed with certain options. Typical use would be output from tools such as ls(1) or netstat(1), where you have a fixed number of columns, but don't know the column widths before hand.

A table is created with rtbl_create() and destroyed with rtbl_destroy().

Global flags on the table are set with rtbl_set_flags and retrieved with rtbl_get_flags. At present the only defined flag is RTBL_HEADER_STYLE_NONE which suppresses printing the header.

Before adding data to the table, one or more columns need to be created. This would normally be done with rtbl_add_column_by_id(), column_id is any number of your choice (it's used only to identify columns), column_header is the header to print at the top of the column, and flags are flags specific to this column. Currently the only defined flag is RTBL_ALIGN_RIGHT, aligning column entries to the right. Columns are printed in the order they are added.

There's also a way to add columns by column name with rtbl_add_column(), but this is less flexible (you need unique header names), and is considered deprecated.

To add data to a column you use rtbl_add_column_entry_by_id(), where the column_id is the same as when the column was added (adding data to a non-existent column is undefined), and cell_entry is whatever string you wish to include in that cell. It should not include newlines. For columns added with rtbl_add_column() you must use rtbl_add_column_entry() instead.

rtbl_new_row() fills all columns with blank entries until they all have the same number of rows.

Each column can have a separate prefix and suffix, set with rtbl_set_column_affix_by_id; rtbl_set_column_prefix allows setting the prefix only by column name. In addition to this, columns may be separated by a string set with rtbl_set_separator (by default columns are not seprated by anything).

The finished table is printed to file with rtbl_format.


This program:

#include <stdio.h> 
#include <rtbl.h> 
main(int argc, char **argv) 
    rtbl_t table; 
    table = rtbl_create(); 
    rtbl_set_separator(table, "  "); 
    rtbl_add_column_by_id(table, 0, "Column A", 0); 
    rtbl_add_column_by_id(table, 1, "Column B", RTBL_ALIGN_RIGHT); 
    rtbl_add_column_by_id(table, 2, "Column C", 0); 
    rtbl_add_column_entry_by_id(table, 0, "A-1"); 
    rtbl_add_column_entry_by_id(table, 0, "A-2"); 
    rtbl_add_column_entry_by_id(table, 0, "A-3"); 
    rtbl_add_column_entry_by_id(table, 1, "B-1"); 
    rtbl_add_column_entry_by_id(table, 2, "C-1"); 
    rtbl_add_column_entry_by_id(table, 2, "C-2"); 
    rtbl_add_column_entry_by_id(table, 1, "B-2"); 
    rtbl_add_column_entry_by_id(table, 1, "B-3"); 
    rtbl_add_column_entry_by_id(table, 2, "C-3"); 
    rtbl_add_column_entry_by_id(table, 0, "A-4"); 
    rtbl_add_column_entry_by_id(table, 1, "B-4"); 
    rtbl_add_column_entry_by_id(table, 2, "C-4"); 
    rtbl_format(table, stdout); 
    return 0; 

will output the following:

Column A  Column B  Column C 
A-1            B-1  C-1 
A-2            B-2  C-2 
A-3            B-3  C-3 

Referenced By

The man pages rtbl_add_column(3), rtbl_add_column_by_id(3), rtbl_add_column_entry(3), rtbl_add_column_entry_by_id(3), rtbl_create(3), rtbl_destroy(3), rtbl_format(3), rtbl_get_flags(3), rtbl_new_row(3), rtbl_set_column_affix_by_id(3), rtbl_set_column_prefix(3), rtbl_set_flags(3), rtbl_set_prefix(3) and rtbl_set_separator(3) are aliases of rtbl(3).

June 26, 2004