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)