.TH TICKIT_TERM_BUILD 3
.SH NAME
tickit_term_build \- create a new terminal instance with arguments
.SH SYNOPSIS
.EX
.B #include <tickit.h>
.sp
.BI "typedef void " TickitTermOutputFunc "(TickitTerm *" tt ", const char *" bytes ,
.BI "    size_t " len ", void *" user );
.sp
.BI "struct " TickitTermBuilder " {"
.BI "  const char *" termtype ;
.BI "  enum ... " open ;
.BI "  int " input_fd ", " output_fd ;
.BI "  TickitTermOutputFunc *" output_func ;
.BI "  void *" output_func_user ;
.BI "  size_t " output_buffersize ;
.BI "  ..."
.BI "};"
.sp
.BI "TickitTerm *tickit_term_build(const struct TickitTermBuilder *" builder );
.EE
.sp
Link with \fI\-ltickit\fP.
.SH DESCRIPTION
\fBtickit_term_build\fP() creates a new \fBTickitTerm\fP instance initialised from the various parameters given in the \fIbuilder\fP 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.
.PP
If the \fItermtype\fP field is set, it should give the terminal type. If left blank, the value of the \fBTERM\fP environment variable is used. If that too is blank, a default of \f(Cwxterm\fP will be assumed.
.PP
The \fIopen\fP field controls the selection of input and output file descriptors for the terminal to use. It should take one of the following enumeration values:
.TP
.B TICKIT_NO_OPEN
No file descriptors will be used. The terminal will operate entirely by abstract byte-buffered IO.
.TP
.B TICKIT_OPEN_FDS
The terminal will use the file descriptors given by the \fIinput_fd\fP and \fIoutput_fd\fP fields. Either may be set to -1 to ignore it.
.TP
.B TICKIT_OPEN_STDIO
The terminal will use the standard input and output streams.
.TP
.B TICKIT_OPEN_STDTTY
The terminal will use the first file descriptor of standard input, output or error for which \fBisatty\fP(3) returns true.
.PP
The \fIoutput_func\fP and \fIoutput_func_user\fP fields provide an output function which will be used for writing output data. If provided, this overrides the output file descriptor.
.PP
The \fIoutput_buffersize\fP field sets the initial size of the output buffer. It defaults to zero, meaning no buffer will be allocated.
.PP
The input file descriptor will be used by \fBtickit_term_input_readable\fP(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 \fBtickit_term_input_push_bytes\fP(3).
.PP
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.
.PP
The output file descriptor will be used by \fBtickit_term_refresh_size\fP(3) to query the size of the terminal, by issuing the \fBTIOCGWINSZ\fP \fBioctl\fP(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 \fBtickit_term_set_size\fP(3) and an output function must be set for output to occur.
.PP
The reference count of a newly-constructed terminal instance will be one. This can be incremented or decremented using \fBtickit_term_ref\fP(3) and \fBtickit_term_unref\fP(3). When its reference count reaches zero it is destroyed.
.PP
After construction it is recommended to call \fBtickit_term_await_started\fP(3) to wait for the terminal to be set up.
.SH "RETURN VALUE"
If successful, \fBtickit_term_build\fP() returns a pointer to the new instance. On failure, \fBNULL\fP is returned with \fIerrno\fP set to indicate the failure.
.SH "SEE ALSO"
.BR tickit_term_open_stdio (3),
.BR tickit_term_set_output_fd (3),
.BR tickit_term_set_output_func (3),
.BR tickit_term_set_input_fd (3),
.BR tickit_term_print (3),
.BR tickit_term_bind_event (3),
.BR tickit_term (7),
.BR tickit (7)