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

                                                                             TICKIT_TERM_BUILD(3)