Scroll to navigation

TICKIT_TERM_BUILD(3) Library Functions Manual TICKIT_TERM_BUILD(3)

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:

No file descriptors will be used. The terminal will operate entirely by abstract byte-buffered IO.
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.
The terminal will use the standard input and output streams.
The terminal will use the first file descriptor of standard input, output or error for which isatty(3) 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) 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).

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.

The reference count of a newly-constructed terminal instance will be one. 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.

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_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)