1RTBL(3) BSD Library Functions Manual RTBL(3)
2
4 rtbl_create, rtbl_destroy, rtbl_set_flags, rtbl_get_flags,
5 rtbl_set_prefix, rtbl_set_separator, rtbl_set_column_prefix,
6 rtbl_set_column_affix_by_id, rtbl_add_column, rtbl_add_column_by_id,
7 rtbl_add_column_entry, rtbl_add_column_entry_by_id, rtbl_new_row,
8 rtbl_format — format data in simple tables
9
11 The roken library (libroken, -lroken)
12
14 #include <rtbl.h>
15 int
17 rtbl_add_column(rtbl_t table, const char *column_name,
18 unsigned int flags);
19 int
21 rtbl_add_column_by_id(rtbl_t table, unsigned int column_id,
22 const char *column_header, unsigned int flags);
23 int
25 rtbl_add_column_entry(rtbl_t table, const char *column_name,
26 const char *cell_entry);
27 int
29 rtbl_add_column_entry_by_id(rtbl_t table, unsigned int column_id,
30 const char *cell_entry);
31 rtbl_t
33 rtbl_create(void);
34 void
36 rtbl_destroy(rtbl_t table);
37 int
39 rtbl_new_row(rtbl_t table);
40 int
42 rtbl_set_column_affix_by_id(rtbl_t table, unsigned int column_id, const,
43 char, *prefix", const char *suffix);
44 int
46 rtbl_set_column_prefix(rtbl_t table, const char *column_name,
47 const char *prefix);
48 unsigned int
50 rtbl_get_flags(rtbl_t table);
51 void
53 rtbl_set_flags(rtbl_t table, unsigned int flags);
54 int
56 rtbl_set_prefix(rtbl_t table, const char *prefix);
57 int
59 rtbl_set_separator(rtbl_t table, const char *separator);
60 int
62 rtbl_format(rtbl_t table, FILE, *file");
63
65 This set of functions assemble a simple table consisting of rows and col‐
66 umns, allowing it to be printed with certain options. Typical use would
67 be output from tools such as ls(1) or netstat(1), where you have a fixed
68 number of columns, but don't know the column widths before hand.
69 A table is created with rtbl_create() and destroyed with rtbl_destroy().
71 Global flags on the table are set with rtbl_set_flags and retrieved with
73 rtbl_get_flags. At present the only defined flag is
74 RTBL_HEADER_STYLE_NONE which suppresses printing the header.
75 Before adding data to the table, one or more columns need to be created.
77 This would normally be done with rtbl_add_column_by_id(), column_id is
78 any number of your choice (it's used only to identify columns),
79 column_header is the header to print at the top of the column, and flags
80 are flags specific to this column. Currently the only defined flag is
81 RTBL_ALIGN_RIGHT, aligning column entries to the right. Columns are
82 printed in the order they are added.
83 There's also a way to add columns by column name with rtbl_add_column(),
85 but this is less flexible (you need unique header names), and is consid‐
86 ered deprecated.
87 To add data to a column you use rtbl_add_column_entry_by_id(), where the
89 column_id is the same as when the column was added (adding data to a non-
90 existent column is undefined), and cell_entry is whatever string you wish
91 to include in that cell. It should not include newlines. For columns
92 added with rtbl_add_column() you must use rtbl_add_column_entry()
93 instead.
94 rtbl_new_row() fills all columns with blank entries until they all have
96 the same number of rows.
97 Each column can have a separate prefix and suffix, set with
99 rtbl_set_column_affix_by_id; rtbl_set_column_prefix allows setting the
100 prefix only by column name. In addition to this, columns may be separated
101 by a string set with rtbl_set_separator (by default columns are not
102 seprated by anything).
103 The finished table is printed to file with rtbl_format.
105
107 This program:
108 #include <stdio.h>
110 #include <rtbl.h>
111 int
112 main(int argc, char **argv)
113 {
114 rtbl_t table;
115 table = rtbl_create();
116 rtbl_set_separator(table, " ");
117 rtbl_add_column_by_id(table, 0, "Column A", 0);
118 rtbl_add_column_by_id(table, 1, "Column B", RTBL_ALIGN_RIGHT);
119 rtbl_add_column_by_id(table, 2, "Column C", 0);
120 rtbl_add_column_entry_by_id(table, 0, "A-1");
121 rtbl_add_column_entry_by_id(table, 0, "A-2");
122 rtbl_add_column_entry_by_id(table, 0, "A-3");
123 rtbl_add_column_entry_by_id(table, 1, "B-1");
124 rtbl_add_column_entry_by_id(table, 2, "C-1");
125 rtbl_add_column_entry_by_id(table, 2, "C-2");
126 rtbl_add_column_entry_by_id(table, 1, "B-2");
127 rtbl_add_column_entry_by_id(table, 1, "B-3");
128 rtbl_add_column_entry_by_id(table, 2, "C-3");
129 rtbl_add_column_entry_by_id(table, 0, "A-4");
130 rtbl_new_row(table);
131 rtbl_add_column_entry_by_id(table, 1, "B-4");
132 rtbl_new_row(table);
133 rtbl_add_column_entry_by_id(table, 2, "C-4");
134 rtbl_new_row(table);
135 rtbl_format(table, stdout);
136 rtbl_destroy(table);
137 return 0;
138 }
139 will output the following:
141 Column A Column B Column C
143 A-1 B-1 C-1
144 A-2 B-2 C-2
145 A-3 B-3 C-3
146 A-4
147 B-4
148 C-4
149HEIMDAL June 26, 2004 HEIMDAL