Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
RTBL(3) 		     Library Functions Manual			 RTBL(3)

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
     The roken library (libroken, -lroken)

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
     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 spe-
     cific 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 pre-
     fix 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
     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

HEIMDAL 			  June 26, 2004 			 RTBL(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=rtbl_create&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help