---
name: "tickit_term_build"
section: "3"
platform: "linux"
package: "libtickit-dev"
version: "0.4.3-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/tickit_term_build"
---

# tickit\_term\_build(3)

create a new terminal instance with arguments

## NAME

tickit\_term\_build - create a new terminal instance with arguments

## 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 given in the *builder* struct. Note that the above definition for the struct is incomplete; the actual struct definition contains more fields than shown as some are for internal purposes. User code should only attempt to interact with those fields documented here.

If the *termtype* field is set, it should give the terminal type. If left blank, the value of the **TERM** environment variable is used. If that too is blank, a default of `xterm` will be assumed.

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

- **TICKIT\_NO\_OPEN**

  No file descriptors will be used. The terminal will operate entirely by abstract byte-buffered IO.

- **TICKIT\_OPEN\_FDS**

  The terminal will use the file descriptors given by the *input\_fd* and *output\_fd* fields. Either 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)](/isatty/3.md) returns true.

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.

The *output\_buffersize* field sets the initial size of the output buffer. It defaults to zero, meaning no buffer will be allocated.

The input file descriptor will be used by [**tickit\_term\_input\_readable**(3)](/tickit_term_input_readable/3.md) 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)](/tickit_term_input_push_bytes/3.md).

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)](/tickit_term_refresh_size/3.md) to query the size of the terminal, by issuing the **TIOCGWINSZ** [**ioctl**(2)](/ioctl/2.md). 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)](/tickit_term_set_size/3.md) and an output function must be set for output to occur.

The reference count of a newly-constructed terminal instance will be one. This can be incremented or decremented using [**tickit\_term\_ref**(3)](/tickit_term_ref/3.md) and [**tickit\_term\_unref**(3)](/tickit_term_unref/3.md). When its reference count reaches zero it is destroyed.

After construction it is recommended to call **tickit\_term\_await\_started**(3) to wait for the terminal to be set up.

## 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.

## SEE ALSO

[**tickit\_term\_open\_stdio**(3)](/tickit_term_open_stdio/3.md), [**tickit\_term\_set\_output\_fd**(3)](/tickit_term_set_output_fd/3.md), [**tickit\_term\_set\_output\_func**(3)](/tickit_term_set_output_func/3.md), [**tickit\_term\_set\_input\_fd**(3)](/tickit_term_set_input_fd/3.md), [**tickit\_term\_print**(3)](/tickit_term_print/3.md), [**tickit\_term\_bind\_event**(3)](/tickit_term_bind_event/3.md), [**tickit\_term**(7)](/tickit_term/7.md), [**tickit**(7)](/tickit/7.md)