---
name: "tbl"
section: "3"
platform: "linux"
package: "libmandoc-dev"
version: "1.14.6-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/tbl/3"
---

# tbl(3)

roff table parser library for mandoc

## NAME

**tbl\_alloc**, **tbl\_read**, **tbl\_restart**, **tbl\_span**, **tbl\_end**, **tbl\_free** – roff table parser library for mandoc

## SYNOPSIS

**#include \<sys/types.h\>**

**#include \<tbl.h\>**

**#include \<tbl\_parse.h\>**

*struct* *tbl\_node* *\**\

**tbl\_alloc**(*int pos*, *int line*);

*void*\

**tbl\_read**(*struct tbl\_node \*tbl*, *int ln*, *const char \*p*, *int offs*);

*void*\

**tbl\_restart**(*int line*, *int pos*, *struct tbl\_node \*tbl*);

*const* *struct* *tbl\_span* *\**\

**tbl\_span**(*struct tbl\_node \*tbl*);

*void*\

**tbl\_end**(*struct tbl\_node \*\*tblp*);

*void*\

**tbl\_free**(*struct tbl\_node \*tbl*);

## DESCRIPTION

This library is tightly integrated into the [mandoc(1)](/mandoc/1.md) utility and not designed for stand-alone use. The present manual is intended as a reference for developers working on [mandoc(1)](/mandoc/1.md).

### Data structures

Unless otherwise noted, all of the following data structures are declared in ⟨tbl.h⟩ and are deleted in **tbl\_free**().

- *struct* *tbl\_node*

  This structure describes a complete table. It is declared in ⟨tbl\_int.h⟩, created in **tbl\_alloc**(), and stored in the members *first\_tbl*, *last\_tbl*, and *tbl* of *struct* *roff* \[*roff.c*\].

  The *first\_span*, *current\_span*, *last\_span*, and *next* members may be NULL. The *first\_row* and *last\_row* members may be NULL, but if there is a span, the function **tbl\_layout**() guarantees that these pointers are not NULL.

- *struct* *tbl\_opts*

  This structure describes the options of one table. It is used as a substructure of *struct* *tbl\_node* and thus created and deleted together with it. It is filled in **tbl\_options**().

- *struct* *tbl\_row*

  This structure describes one layout line in a table by maintaining a list of all the cells in that line. It is allocated and filled in **row**(*Bq*, *Pa*, *tbl\_layout.c*) and referenced from the *layout* member of *struct* *tbl\_node*.

  The *next* member may be NULL. The function **tbl\_layout**() guarantees that the *first* and *last* members are not NULL.

- *struct* *tbl\_cell*

  This structure describes one layout cell in a table, in particular its alignment, membership in spans, and usage for lines. It is allocated and filled in **cell\_alloc**(*Bq*, *Pa*, *tbl\_layout.c*) and referenced from the *first* and *last* members of *struct* *tbl\_row*.

  The *next* member may be NULL.

- *struct* *tbl\_span*

  This structure describes one data line in a table by maintaining a list of all data cells in that line or by specifying that it is a horizontal line. It is allocated and filled in **newspan**(*Bq*, *Pa*, *tbl\_data.c*) which is called from **tbl\_data**() and referenced from the *first\_span*, *current\_span*, and *last\_span* members of *struct* *tbl\_node*, and from the *span* members of *struct* *man\_node* and *struct* *mdoc\_node* from ⟨man.h⟩ and ⟨mdoc.h⟩.

  The *first*, *last*, *prev*, and *next* members may be NULL. The function **newspan**(*Bq*, *Pa*, *tbl\_data.c*) guarantees that the *opts* and *layout* members are not NULL.

- *struct* *tbl\_dat*

  This structure describes one data cell in a table by specifying whether it contains a line or data, whether it spans additional layout cells, and by storing the data. It is allocated and filled in **tbl\_data**() and referenced from the *first* and *last* members of *struct* *tbl\_span*.

  The *string* and *next* members may be NULL. The function **getdata**() guarantees that the *layout* member is not NULL.

### Interface functions

The following functions are implemented in *tbl.c*, and all callers are in *roff.c*.

- **tbl\_alloc**()

  Allocates, initializes, and returns a new *struct* *tbl\_node*. Called from **roff\_TS**().

- **tbl\_read**()

  Dispatches to **tbl\_option**(), **tbl\_layout**(), **tbl\_cdata**(), and **tbl\_data**(), see below. Called from **roff\_parseln**().

- **tbl\_restart**()

  Resets the *part* member of *struct* *tbl\_node* to TBL\_PART\_LAYOUT. Called from **roff\_T\_**().

- **tbl\_span**()

  On the first call, return the first *struct* *tbl\_span*; for later calls, return the next one or NULL. Called from **roff\_span**().

- **tbl\_end**()

  Flags the last span as TBL\_SPAN\_LAST and clears the pointer passed as an argment. Called from **roff\_TE**() and **roff\_endparse**().

- **tbl\_free**()

  Frees the specified *struct* *tbl\_node* and all the tbl\_row, tbl\_cell, tbl\_span, and tbl\_dat structures referenced from it. Called from **roff\_free**() and **roff\_reset**().

### Private functions

The following functions are declared in ⟨tbl\_int.h⟩.

- *int* **tbl\_options**(*struct tbl\_node \*tbl*, *int ln*, *const char \*p*)

  Parses the options line into *struct* *tbl\_opts*. Implemented in *tbl\_opts.c*, called from **tbl\_read**().

- *int* **tbl\_layout**(*struct tbl\_node \*tbl*, *int ln*, *const char \*p*)

  Allocates and fills one *struct* *tbl\_row* for each layout line and one *struct* *tbl\_cell* for each layout cell. Implemented in *tbl\_layout.c*, called from **tbl\_read**().

- *int* **tbl\_data**(*struct tbl\_node \*tbl*, *int ln*, *const char \*p*)

  Allocates one *struct* *tbl\_span* for each data line and calls **getdata**() for each data cell. Implemented in *tbl\_data.c*, called from **tbl\_read**().

- *int* **tbl\_cdata**(*struct tbl\_node \*tbl*, *int ln*, *const char \*p*)

  Continues parsing a data line: When finding ‘T}’, switches back to TBL\_PART\_DATA mode and calls **getdata**() if there are more data cells on the line. Otherwise, appends the data to the current data cell. Implemented in *tbl\_data.c*, called from **tbl\_read**().

-

  *int* **getdata**(*struct tbl\_node \*tbl*, *struct tbl\_span \*dp*, *int ln*, *const char \*p*, *int \*pos*) Parses one data cell into one *struct* *tbl\_dat*. Implemented in *tbl\_data.c*, called from **tbl\_data**() and **tbl\_cdata**().

## SEE ALSO

[mandoc(1)](/mandoc/1.md), [mandoc(3)](/mandoc/3.md), [tbl(7)](/tbl/7.md)

## AUTHORS

The **tbl** library was written by Kristaps Dzonsons ⟨*kristaps@bsd.lv*⟩ with contributions from Ingo Schwarze ⟨*schwarze@openbsd.org*⟩.