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  cre-
       ated.   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 col-
       umn, 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	 sepa-
       rated  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_set_flags&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help