Add `tb_init_ex`

[adsr]

Termbox started out with just 1 init function, tb_init. In 2016, tb_init_file and tb_init_fd were added. I added tb_init_rwfd in 2021 when I rewrote the library as termbox2, mainly for testing purposes, but also with some real world applications in mind.

Over time, feature requests have rolled in that would benefit from an init option. For example, an enable/disable flag for logging, region height for region mode, mask width for user-defined attributes, etc. Adding a new init function for all of these would explode the API, which we're trying very hard to keep tight and small. There's also a combinatoric problem. What if I want to initialize in region mode and pass in a tty fd?

This comment summarizes the potential solutions we've discussed:

1. struct (ABI compat issues)
2. struct with size
3. variadic (arg1_type, arg1, arg2_type, arg2 ...)
4. variadic (fmt, arg1, arg2, ...)
5. uintptr_t array
6. uintptr_t array with sentinel
7. string

My proposal for this work is option 2:

// struct with size
struct tb_init_opts o = {0};
o.size = sizeof(o);
o.file = "/dev/tty";
o.region_h = 3;
tb_init_ex(&o); // only reads up to `o.size`

We keep type safety but somewhat limit ABI compat issues (when the library is dynamically linked) via the size field.

[txgk]

struct tb_init_opts o = {0};
o.size = sizeof(o);
o.file = "/dev/tty";
o.region_h = 3;
tb_init_ex(&o); // only reads up to `o.size`

I like it. Clean and simple.

But let me just refine it a bit with a couple of suggestions:

1. Introduce macro for less cumbersome initialization:

#define TB_INIT_DEFAULT_OPTS (struct tb_init_opts){.size = sizeof(struct tb_init_opts)}

struct tb_init_opts o = TB_INIT_DEFAULT_OPTS;
o.file = "/dev/tty";
o.region_h = 3;
tb_init_ex(&o);

2. Make it never accept wrong sizes:

int tb_init_ex(struct tb_init_opts *opts) {
    if (!opts) {
        return TB_ERR_INIT_INVALID_OPT;
    }
    if (opts->size != sizeof(*opts)) {
        return TB_ERR_INIT_INVALID_ABI;
    }
}

[txgk]

Actually, maybe it's not as elegant as it seems. It can safeguard from UB but it doesn't save apps from crashing when partial upgrade took place - if TUI doesn't start, it means program is broken.

Another approach to the absolute foolproof ABI is opaque pointer, fully managed internally by termbox2, like libcurl's CURL. Here's a template:

typedef void tb_opts;
tb_opts *opts = tb_opts_default();
tb_opts_set(opts, TB_OPT_FILE, "/dev/tty");
tb_opts_set(opts, TB_OPT_REGION, 3);
tb_init_ex(opts);

[adsr]

@txgk Is there a specific case you're concerned about with partial upgrade? I wrote a small demo to test forward- and back-compat using the size trick, and it seems to work as I'd expect.

$ # header with opts struct
$ cat opts-v1.h 
#ifndef OPTS_H
#define OPTS_H

struct opts {
    size_t size;
    int i;
    float f;
    void *p;
};

void init(struct opts *o);

#endif
$ 
$ # lib with init function
$ cat opts-v1.c
#include <stdio.h>
#include <stddef.h>
#include <opts-v1.h>

void init(struct opts *o) {
    if (o->size >= offsetof(struct opts, i)  + sizeof(o->i))  printf("reading i=%d\n",  o->i);
    if (o->size >= offsetof(struct opts, f)  + sizeof(o->f))  printf("reading f=%f\n",  o->f);
    if (o->size >= offsetof(struct opts, p)  + sizeof(o->p))  printf("reading p=%p\n",  o->p);
}
$ 
$ # opts-v2 adds another field to opts struct (i2)
$ diff -u opts-v1.c opts-v2.c
--- opts-v1.c	2026-07-30 01:21:57.570981299 -0400
+++ opts-v2.c	2026-07-30 01:22:13.603522582 -0400
@@ -1,9 +1,10 @@
 #include <stdio.h>
 #include <stddef.h>
-#include <opts-v1.h>
+#include <opts-v2.h>
 
 void init(struct opts *o) {
     if (o->size >= offsetof(struct opts, i)  + sizeof(o->i))  printf("reading i=%d\n",  o->i);
     if (o->size >= offsetof(struct opts, f)  + sizeof(o->f))  printf("reading f=%f\n",  o->f);
     if (o->size >= offsetof(struct opts, p)  + sizeof(o->p))  printf("reading p=%p\n",  o->p);
+    if (o->size >= offsetof(struct opts, i2) + sizeof(o->i2)) printf("reading i2=%d\n", o->i2);
 }
$ diff -u opts-v1.h opts-v2.h 
--- opts-v1.h	2026-07-30 01:18:51.480700544 -0400
+++ opts-v2.h	2026-07-30 01:18:45.165578525 -0400
@@ -8,6 +8,7 @@
     int i;
     float f;
     void *p;
+    int i2;
 };
 
 void init(struct opts *o);
$ 
$ # compile both versions as shared libs
$ clang -shared -fPIC -I. -o libopts-v1.so opts-v1.c
$ clang -shared -fPIC -I. -o libopts-v2.so opts-v2.c
$ 
$ # a program compiled against v1 header
$ cat prog-with-v1-header.c 
#include <opts-v1.h>

int main(int argc, char **argv) {
    struct opts o = {0};
    o.size = sizeof(o);
    o.i = 42;
    o.f = 1.23f;
    o.p = &o;
    init(&o);
    return 0;
}
$ 
$ # same program compiled against v2 header
$ diff -u prog-with-v1-header.c prog-with-v2-header.c 
--- prog-with-v1-header.c	2026-07-30 01:21:23.297824294 -0400
+++ prog-with-v2-header.c	2026-07-30 01:21:20.513730312 -0400
@@ -1,4 +1,4 @@
-#include <opts-v1.h>
+#include <opts-v2.h>
 
 int main(int argc, char **argv) {
     struct opts o = {0};
@@ -6,6 +6,7 @@
     o.i = 42;
     o.f = 1.23f;
     o.p = &o;
+    o.i2 = 43;
     init(&o);
     return 0;
 }
$ 
$ # compile v1 and v2 programs against v1 and v2 libs
$ clang -I. prog-with-v1-header.c -o prog-with-v1-header-v1-lib libopts-v1.so -Wl,-rpath,.
$ clang -I. prog-with-v1-header.c -o prog-with-v1-header-v2-lib libopts-v2.so -Wl,-rpath,.
$ clang -I. prog-with-v2-header.c -o prog-with-v2-header-v1-lib libopts-v1.so -Wl,-rpath,.
$ clang -I. prog-with-v2-header.c -o prog-with-v2-header-v2-lib libopts-v2.so -Wl,-rpath,.
$ ldd prog-with-v1-header-v1-lib | grep libopts
	libopts-v1.so => ./libopts-v1.so (0x00007fa305136000)
$ ldd prog-with-v1-header-v2-lib | grep libopts
	libopts-v2.so => ./libopts-v2.so (0x00007f43b5589000)
$ ldd prog-with-v2-header-v1-lib | grep libopts
	libopts-v1.so => ./libopts-v1.so (0x00007f8caad9c000)
$ ldd prog-with-v2-header-v2-lib | grep libopts
	libopts-v2.so => ./libopts-v2.so (0x00007f51fc692000)
$ 
$ # test
$ ./prog-with-v1-header-v1-lib 
reading i=42
reading f=1.230000
reading p=0x7fff00c32c68
$ ./prog-with-v1-header-v2-lib 
reading i=42
reading f=1.230000
reading p=0x7fff2c909bb8
$ ./prog-with-v2-header-v1-lib 
reading i=42
reading f=1.230000
reading p=0x7ffd4dc6f520
$ ./prog-with-v2-header-v2-lib 
reading i=42
reading f=1.230000
reading p=0x7ffd4f5f2e70
reading i2=43

To make this keep working across versions, I think the requirements are to keep the field order the same, not change types, and only append to the end of the struct.