RTBL(3) Library Functions Manual RTBL(3)

# [NAME](#NAME)

`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

# [LIBRARY](#LIBRARY)

The roken library (libroken, -lroken)

# [SYNOPSIS](#SYNOPSIS)

`#include <rtbl.h>`

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

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

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

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

`rtbl_t`  
`rtbl_create`(`void`);

`void`  
`rtbl_destroy`(`rtbl_t table`);

`int`  
`rtbl_new_row`(`rtbl_t table`);

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

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

`unsigned int`  
`rtbl_get_flags`(`rtbl_t table`);

`void`  
`rtbl_set_flags`(`rtbl_t table`, `unsigned int flags`);

`int`  
`rtbl_set_prefix`(`rtbl_t table`, `const char *prefix`);

`int`  
`rtbl_set_separator`(`rtbl_t table`, `const char *separator`);

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

# [DESCRIPTION](#DESCRIPTION)

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)](/man/os/heimdal/ls.1) or [netstat(1)](/man/os/heimdal/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`](#rtbl_create)() and destroyed with [`rtbl_destroy`](#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`](#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`](#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`](#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`](#rtbl_add_column_entry)() instead.

[`rtbl_new_row`](#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`.

# [EXAMPLES](#EXAMPLES)

This program:

```
#include <stdio.h>
#include <rtbl.h>
int
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_new_row(table);
    rtbl_add_column_entry_by_id(table, 1, "B-4");
    rtbl_new_row(table);
    rtbl_add_column_entry_by_id(table, 2, "C-4");
    rtbl_new_row(table);
    rtbl_format(table, stdout);
    rtbl_destroy(table);
    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
A-4
               B-4
                    C-4
```

June 26, 2004 HEIMDAL

---

Document: rtbl_set_column_affix_by_id(3) from heimdal 7.8.0-r55 (Chainguard OS)
Source: https://github.com/heimdal/heimdal