TICKIT_TERM_BUILD(3)

✨ TICKIT_TERM_BUILD ✨

okay bestie, welcome to tickit_term_build(3) — this is from the Library Functions Manual and it's literally the glow-up moment where your terminal instance gets born. 💖

🎀 NAME 🎀

tickit_term_build — create a new terminal instance with arguments

like, it builds a terminal. from arguments. that's the whole vibe.

🌸 SYNOPSIS 🌸

#include <tickit.h>

typedef void TickitTermOutputFunc(TickitTerm *tt, const char *bytes,
    size_t len, void *user);

struct TickitTermBuilder {
  const char *termtype;
  enum ... open;
  int input_fd, output_fd;
  TickitTermOutputFunc *output_func;
  void *output_func_user;
  size_t output_buffersize;
  ...
};

TickitTerm *tickit_term_build(const struct TickitTermBuilder *builder);

Link with -ltickit.

🦋 DESCRIPTION 🦋

tickit_term_build() creates a new TickitTerm instance, initialised from the various parameters you hand it in the builder struct. ✨

⚠️ heads up bestie — that struct definition up there is incomplete. The actual struct definition contains more fields than shown, because some of them are for internal purposes. Your user code should only attempt to interact with the fields documented right here. don't go poking at the mystery fields, they're not for you 🙈

The termtype field — if you set it, it should give the terminal type. If you leave it blank, the value of the TERM environment variable is used. And if that is blank too, a default of xterm will be assumed. so it always ends up knowing what it is. main character energy tbh 💅

The open field controls the selection of input and output file descriptors for the terminal to use. It should take one of these enumeration values:

• TICKIT_NO_OPEN — no file descriptors will be used at all. The terminal will operate entirely by abstract byte-buffered IO. just vibes, no fds 🫧
• TICKIT_OPEN_FDS — the terminal will use the file descriptors given by the input_fd and output_fd fields. Either one may be set to -1 to ignore it.
• TICKIT_OPEN_STDIO — the terminal will use the standard input and output streams.
• TICKIT_OPEN_STDTTY — the terminal will use the first file descriptor of standard input, output or error for which isatty(3) returns true. it goes shopping down the list and takes the first one that's actually a tty 🛍️

The output_func and output_func_user fields provide an output function which will be used for writing output data. If provided, this overrides the output file descriptor. yep, it wins. no cap.

The output_buffersize field sets the initial size of the output buffer. It defaults to zero, meaning no buffer will be allocated. tiny and unbothered ✨

The input file descriptor will be used by tickit_term_input_readable(3) to read more data from the terminal. The value -1 may be set to indicate an absence of a file descriptor, in which case input data may still be given by calling tickit_term_input_push_bytes(3). so like, no fd doesn't mean no input, it just means you're feeding it by hand 🍓

If set to a non-NULL value, output function is used to output bytes of data to the terminal even if a file descriptor is also set. When invoked, it is passed the terminal instance, a byte buffer and size, and the user data pointer that it was configured with. This pointer may be NULL if not required.

The output file descriptor will be used by tickit_term_refresh_size(3) to query the size of the terminal, by issuing the TIOCGWINSZ ioctl(2). It will also be used to write output to the terminal if no function has been set. The value -1 may be set to indicate no file descriptor, in which case the size must be set by tickit_term_set_size(3) and an output function must be set for output to occur. 👑

💀 fr fr, if you set the output fd to -1 and don't set an output function, nothing is going anywhere. just so you know.

The reference count of a newly-constructed terminal instance will be 1. This can be incremented or decremented using tickit_term_ref(3) and tickit_term_unref(3). When its reference count reaches zero it is destroyed. rest in peace little terminal 🕊️

After construction it is recommended to call tickit_term_await_started(3) to wait for the terminal to be set up. like, let it finish getting ready before you drag it to the party 💖

🌈 RETURN VALUE 🌈

If successful, tickit_term_build() returns a pointer to the new instance. 🎉 On failure, NULL is returned with errno set to indicate the failure. 😭 (check your errno bestie, it's telling you what went wrong)

💜 SEE ALSO 💜

• tickit_term_open_stdio(3)
• tickit_term_set_output_fd(3)
• tickit_term_set_output_func(3)
• tickit_term_set_input_fd(3)
• tickit_term_print(3)
• tickit_term_bind_event(3)
• tickit_term(7)
• tickit(7)

go read those too, they're all part of the same friend group 🫶

and that's the whole page, bestie! 🎀 this was TICKIT_TERM_BUILD(3) from the Library Functions Manual, and the footer says it's dated TICKIT_TERM_BUILD(3) — ok that footer is literally just the title again but shorter, iconic behaviour honestly, go off ✨💅🦋