scols_copy_table ()

struct libscols_table *
scols_copy_table (struct libscols_table *tb);

Creates a new independent table copy, except struct libscols_symbols that are shared between the tables.

scols_new_table ()

struct libscols_table *
scols_new_table (void);

scols_ref_table ()

void
scols_ref_table (struct libscols_table *tb);

Increases the refcount of tb .

scols_sort_table ()

int
scols_sort_table (struct libscols_table *tb,
                  struct libscols_column *cl);

Orders the table by the column. See also scols_column_set_cmpfunc(). If the tree output is enabled then children in the tree are recursively sorted too.

The column cl is saved as the default sort column to the tb and the next time is possible to call scols_sort_table(tb, NULL). The saved column is also used by scols_sort_table_by_tree().

scols_sort_table_by_tree ()

int
scols_sort_table_by_tree (struct libscols_table *tb);

Reorders lines in the table by parent->child relation. Note that order of the lines in the table is independent on the tree hierarchy by default.

The children of the lines are sorted according to the default sort column if scols_sort_table() has been previously called.

Since: 2.30

scols_table_add_column ()

int
scols_table_add_column (struct libscols_table *tb,
                        struct libscols_column *cl);

Adds cl to tb 's column list. The column cannot be shared between more tables.

scols_table_add_line ()

int
scols_table_add_line (struct libscols_table *tb,
                      struct libscols_line *ln);

Note that this function calls scols_line_alloc_cells() if number of the cells in the line is too small for tb .

scols_table_colors_wanted ()

int
scols_table_colors_wanted (const struct libscols_table *tb);

scols_table_enable_ascii ()

int
scols_table_enable_ascii (struct libscols_table *tb,
                          int enable);

The ASCII-only output is relevant for tree-like outputs. The library checks if the current environment is UTF8 compatible by default. This function overrides this check and force the library to use ASCII chars for the tree.

If a custom libcols_symbols are specified (see scols_table_set_symbols() then ASCII flag setting is ignored.

scols_table_enable_colors ()

int
scols_table_enable_colors (struct libscols_table *tb,
                           int enable);

Enable/disable colors.

scols_table_enable_export ()

int
scols_table_enable_export (struct libscols_table *tb,
                           int enable);

Enable/disable export output format (COLUMNAME="value" ...). The parsable output formats (export and raw) are mutually exclusive.

See also scols_table_enable_shellvar(). Note that in version 2.37 (and only in this version) scols_table_enable_shellvar() functionality has been automatically enabled for "export" format. This behavior has been reverted in version 2.38 due to backward compatibility issues. Now it's necessary to explicitly call scols_table_enable_shellvar().

scols_table_enable_header_repeat ()

int
scols_table_enable_header_repeat (struct libscols_table *tb,
                                  int enable);

Enable/disable header line repeat. The header line is printed only once by default. Note that the flag will be silently ignored and disabled if the output is not on terminal or output format is JSON, raw, etc.

Since: 2.31

scols_table_enable_json ()

int
scols_table_enable_json (struct libscols_table *tb,
                         int enable);

Enable/disable JSON output format. The parsable output formats (export, raw, JSON, ...) are mutually exclusive.

Since: 2.27

scols_table_enable_maxout ()

int
scols_table_enable_maxout (struct libscols_table *tb,
                           int enable);

The extra space after last column is ignored by default. The output maximization add padding for all columns.

This setting is mutually exclusive to scols_table_enable_minout().

scols_table_enable_minout ()

int
scols_table_enable_minout (struct libscols_table *tb,
                           int enable);

Force library to terminate line after last column with data. The extra padding is not added to the empty cells at the end of the line. The default is fill tailing empty cells except the last line cell.

This setting is mutually exclusive to scols_table_enable_maxout().

Since: 2.35

scols_table_enable_noencoding ()

int
scols_table_enable_noencoding (struct libscols_table *tb,
                               int enable);

The library encode non-printable and control chars by \xHEX by default.

Since: 2.31

scols_table_enable_noheadings ()

int
scols_table_enable_noheadings (struct libscols_table *tb,
                               int enable);

Enable/disable header line.

scols_table_enable_nolinesep ()

int
scols_table_enable_nolinesep (struct libscols_table *tb,
                              int enable);

Enable/disable line separator printing. This is useful if you want to re-printing the same line more than once (e.g. progress bar). Don't use it if you're not sure.

Note that for the last line in the table the separator is disabled at all. The library differentiate between table terminator and line terminator (although for standard output \n byte is used in both cases).

scols_table_enable_nowrap ()

int
scols_table_enable_nowrap (struct libscols_table *tb,
                           int enable);

Never continue on next line, remove last column(s) when too large, truncate last column.

Since: 2.28

scols_table_enable_raw ()

int
scols_table_enable_raw (struct libscols_table *tb,
                        int enable);

Enable/disable raw output format. The parsable output formats (export, raw, JSON, ...) are mutually exclusive.

scols_table_enable_shellvar ()

int
scols_table_enable_shellvar (struct libscols_table *tb,
                             int enable);

Force library to print column names to be compatible with shell requirements to variable names. For example "1FOO%" will be printed as "_1FOO_PCT".

Since: 2.38

scols_table_get_column ()

struct libscols_column *
scols_table_get_column (struct libscols_table *tb,
                        size_t n);

scols_table_get_column_by_name ()

struct libscols_column *
scols_table_get_column_by_name (struct libscols_table *tb,
                                const char *name);

scols_table_get_column_separator ()

const char *
scols_table_get_column_separator (const struct libscols_table *tb);

scols_table_get_line ()

struct libscols_line *
scols_table_get_line (struct libscols_table *tb,
                      size_t n);

scols_table_get_line_separator ()

const char *
scols_table_get_line_separator (const struct libscols_table *tb);

scols_table_get_name ()

const char *
scols_table_get_name (const struct libscols_table *tb);

Since: 2.29

scols_table_get_ncols ()

size_t
scols_table_get_ncols (const struct libscols_table *tb);

scols_table_get_nlines ()

size_t
scols_table_get_nlines (const struct libscols_table *tb);

scols_table_get_stream ()

FILE *
scols_table_get_stream (const struct libscols_table *tb);

Gets the output stream for table tb .

scols_table_get_symbols ()

struct libscols_symbols *
scols_table_get_symbols (const struct libscols_table *tb);

Since: 2.29

scols_table_get_termforce ()

int
scols_table_get_termforce (const struct libscols_table *tb);

Since: 2.29

scols_table_get_termheight ()

size_t
scols_table_get_termheight (const struct libscols_table *tb);

Since: 2.31

scols_table_get_termwidth ()

size_t
scols_table_get_termwidth (const struct libscols_table *tb);

scols_table_get_title ()

struct libscols_cell *
scols_table_get_title (struct libscols_table *tb);

The returned pointer is possible to modify by cell functions. Note that title output alignment on non-tty is hardcoded to 80 output chars. For the regular terminal it's based on terminal width.

Since: 2.28

scols_table_is_ascii ()

int
scols_table_is_ascii (const struct libscols_table *tb);

scols_table_is_empty ()

int
scols_table_is_empty (const struct libscols_table *tb);

scols_table_is_export ()

int
scols_table_is_export (const struct libscols_table *tb);

scols_table_is_header_repeat ()

int
scols_table_is_header_repeat (const struct libscols_table *tb);

Since: 2.31

scols_table_is_json ()

int
scols_table_is_json (const struct libscols_table *tb);

Since: 2.27

scols_table_is_maxout ()

int
scols_table_is_maxout (const struct libscols_table *tb);

scols_table_is_minout ()

int
scols_table_is_minout (const struct libscols_table *tb);

Since: 2.35

scols_table_is_noencoding ()

int
scols_table_is_noencoding (const struct libscols_table *tb);

Since: 2.31

scols_table_is_noheadings ()

int
scols_table_is_noheadings (const struct libscols_table *tb);

scols_table_is_nolinesep ()

int
scols_table_is_nolinesep (const struct libscols_table *tb);

Since: 2.29

scols_table_is_nowrap ()

int
scols_table_is_nowrap (const struct libscols_table *tb);

Since: 2.29

scols_table_is_raw ()

int
scols_table_is_raw (const struct libscols_table *tb);

scols_table_is_shellvar ()

int
scols_table_is_shellvar (const struct libscols_table *tb);

Since: 2.38

scols_table_is_tree ()

int
scols_table_is_tree (const struct libscols_table *tb);

scols_table_move_column ()

int
scols_table_move_column (struct libscols_table *tb,
                         struct libscols_column *pre,
                         struct libscols_column *cl);

Move the cl behind pre . If the pre is NULL then the col is the first column in the table.

Since: 2.30

scols_table_new_column ()

struct libscols_column *
scols_table_new_column (struct libscols_table *tb,
                        const char *name,
                        double whint,
                        int flags);

This is shortcut for

cl = scols_new_column(); scols_column_set_....(cl, ...); scols_table_add_column(tb, cl);

The column width is possible to define by:

whint : 0 < N < 1 : relative width, percent of terminal width

whint : N >= 1 : absolute width, empty column will be truncated to the column header width if no specified STRICTWIDTH flag

Note that if table has disabled "maxout" flag (disabled by default) than relative width is used as a hint only. It's possible that column will be narrow if the specified size is too large for column data.

If the width of all columns is greater than terminal width then library tries to reduce width of the individual columns. It's done in three stages:

#1 reduce columns with SCOLS_FL_TRUNC flag and with relative width if the width is greater than width defined by whint (whint * terminal_width)

#2 reduce all columns with SCOLS_FL_TRUNC flag

#3 reduce all columns with relative width

The next stage is always used if the previous stage is unsuccessful. Note that SCOLS_FL_WRAP is interpreted as SCOLS_FL_TRUNC when calculate column width (if custom wrap function is not specified), but the final text is not truncated, but wrapped to multi-line cell.

The column is necessary to address by sequential number. The first defined column has the colnum = 0. For example:

scols_table_new_column(tab, "FOO", 0.5, 0); // colnum = 0 scols_table_new_column(tab, "BAR", 0.5, 0); // colnum = 1 . . scols_line_get_cell(line, 0); // FOO column scols_line_get_cell(line, 1); // BAR column

scols_table_new_line ()

struct libscols_line *
scols_table_new_line (struct libscols_table *tb,
                      struct libscols_line *parent);

This is shortcut for

ln = scols_new_line(); scols_table_add_line(tb, ln); scols_line_add_child(parent, ln);

scols_table_next_column ()

int
scols_table_next_column (struct libscols_table *tb,
                         struct libscols_iter *itr,
                         struct libscols_column **cl);

Returns the next column of tb via cl .

scols_table_next_line ()

int
scols_table_next_line (struct libscols_table *tb,
                       struct libscols_iter *itr,
                       struct libscols_line **ln);

Finds the next line and returns a pointer to it via ln .

scols_table_reduce_termwidth ()

int
scols_table_reduce_termwidth (struct libscols_table *tb,
                              size_t reduce);

If necessary then libsmartcols use all terminal width, the reduce setting provides extra space (for example for borders in ncurses applications).

The reduce must be smaller than terminal width, otherwise it's silently ignored. The reduction is not applied when STDOUT_FILENO is not terminal.

Note that after output initialization (scols_table_print_* calls) the width will be reduced, this behavior affects subsequenced scols_table_get_termwidth() calls.

scols_table_remove_column ()

int
scols_table_remove_column (struct libscols_table *tb,
                           struct libscols_column *cl);

Removes cl from tb .

scols_table_remove_columns ()

int
scols_table_remove_columns (struct libscols_table *tb);

Removes all of tb 's columns.

scols_table_remove_line ()

int
scols_table_remove_line (struct libscols_table *tb,
                         struct libscols_line *ln);

Note that this function does not destroy the parent<->child relationship between lines. You have to call scols_line_remove_child()

scols_table_remove_lines ()

void
scols_table_remove_lines (struct libscols_table *tb);

This empties the table and also destroys all the parent<->child relationships.

scols_table_set_column_separator ()

int
scols_table_set_column_separator (struct libscols_table *tb,
                                  const char *sep);

Sets the column separator of tb to sep .

scols_table_set_columns_iter ()

int
scols_table_set_columns_iter (struct libscols_table *tb,
                              struct libscols_iter *itr,
                              struct libscols_column *cl);

Sets iter to the position of cl in the file tb .

Since: 2.35

scols_table_set_default_symbols ()

int
scols_table_set_default_symbols (struct libscols_table *tb);

The library check the current environment to select ASCII or UTF8 symbols. This default behavior could be controlled by scols_table_enable_ascii().

Use scols_table_set_symbols() to unset symbols or use your own setting.

Since: 2.29

scols_table_set_line_separator ()

int
scols_table_set_line_separator (struct libscols_table *tb,
                                const char *sep);

Sets the line separator of tb to sep .

scols_table_set_name ()

int
scols_table_set_name (struct libscols_table *tb,
                      const char *name);

The table name is used for example for JSON top level object name.

Since: 2.27

scols_table_set_stream ()

int
scols_table_set_stream (struct libscols_table *tb,
                        FILE *stream);

Sets the output stream for table tb .

scols_table_set_symbols ()

int
scols_table_set_symbols (struct libscols_table *tb,
                         struct libscols_symbols *sy);

Add a reference to sy from the table. The symbols are used by library to draw tree output. If no symbols are used for the table then library creates default temporary symbols to draw output by scols_table_set_default_symbols().

If sy is NULL then remove reference from the currently used symbols.

scols_table_set_termforce ()

int
scols_table_set_termforce (struct libscols_table *tb,
                           int force);

Forces library to use stdout as terminal, non-terminal or use automatic detection (default).

Since: 2.29

scols_table_set_termheight ()

int
scols_table_set_termheight (struct libscols_table *tb,
                            size_t height);

The library automatically detects terminal height or defaults to 24 lines if detections is unsuccessful. This function override this behaviour.

Since: 2.31

scols_table_set_termwidth ()

int
scols_table_set_termwidth (struct libscols_table *tb,
                           size_t width);

The library automatically detects terminal width or defaults to 80 chars if detections is unsuccessful. This function override this behaviour.

Since: 2.29

scols_unref_table ()

void
scols_unref_table (struct libscols_table *tb);

Decreases the refcount of tb . When the count falls to zero, the instance is automatically deallocated.

struct libscols_table

struct libscols_table;

A table - The most abstract object, encapsulating lines, columns, symbols and cells