1TICKIT_TERM_BUILD(3) Library Functions Manual TICKIT_TERM_BUILD(3)
2
6 tickit_term_build - create a new terminal instance with arguments
7
9 #include <tickit.h>
10 typedef void TickitTermOutputFunc(TickitTerm *tt, const char *bytes,
12 size_t len, void *user);
13 struct TickitTermBuilder {
15 const char *termtype;
16 enum ... open;
17 int input_fd, output_fd;
18 TickitTermOutputFunc *output_func;
19 void *output_func_user;
20 size_t output_buffersize;
21 ...
22 };
23 TickitTerm *tickit_term_build(const struct TickitTermBuilder *builder);
25 Link with -ltickit.
27
29 tickit_term_build() creates a new TickitTerm instance initialised from
30 the various parameters given in the builder struct. Note that the above
31 definition for the struct is incomplete; the actual struct definition
32 contains more fields than shown as some are for internal purposes. User
33 code should only attempt to interact with those fields documented here.
34 If the termtype field is set, it should give the terminal type. If left
36 blank, the value of the TERM environment variable is used. If that too
37 is blank, a default of xterm will be assumed.
38 The open field controls the selection of input and output file descrip‐
40 tors for the terminal to use. It should take one of the following enu‐
41 meration values:
42 TICKIT_NO_OPEN
44 No file descriptors will be used. The terminal will operate en‐
45 tirely by abstract byte-buffered IO.
46 TICKIT_OPEN_FDS
48 The terminal will use the file descriptors given by the input_fd
49 and output_fd fields. Either may be set to -1 to ignore it.
50 TICKIT_OPEN_STDIO
52 The terminal will use the standard input and output streams.
53 TICKIT_OPEN_STDTTY
55 The terminal will use the first file descriptor of standard in‐
56 put, output or error for which isatty(3) returns true.
57 The output_func and output_func_user fields provide an output function
59 which will be used for writing output data. If provided, this overrides
60 the output file descriptor.
61 The output_buffersize field sets the initial size of the output buffer.
63 It defaults to zero, meaning no buffer will be allocated.
64 The input file descriptor will be used by tickit_term_input_readable(3)
66 to read more data from the terminal. The value -1 may be set to indi‐
67 cate an absence of a file descriptor, in which case input data may
68 still be given by calling tickit_term_input_push_bytes(3).
69 If set to a non-NULL value, output function is used to output bytes of
71 data to the terminal even if a file descriptor is also set. When in‐
72 voked, it is passed the terminal instance, a byte buffer and size, and
73 the user data pointer that it was configured with. This pointer may be
74 NULL if not required.
75 The output file descriptor will be used by tickit_term_refresh_size(3)
77 to query the size of the terminal, by issuing the TIOCGWINSZ ioctl(2).
78 It will also be used to write output to the terminal if no function has
79 been set. The value -1 may be set to indicate no file descriptor, in
80 which case the size must be set by tickit_term_set_size(3) and an out‐
81 put function must be set for output to occur.
82 The reference count of a newly-constructed terminal instance will be
84 one. This can be incremented or decremented using tickit_term_ref(3)
85 and tickit_term_unref(3). When its reference count reaches zero it is
86 destroyed.
87 After construction it is recommended to call
89 tickit_term_await_started(3) to wait for the terminal to be set up.
90
92 If successful, tickit_term_build() returns a pointer to the new in‐
93 stance. On failure, NULL is returned with errno set to indicate the
94 failure.
95
97 tickit_term_open_stdio(3), tickit_term_set_output_fd(3),
98 tickit_term_set_output_func(3), tickit_term_set_input_fd(3),
99 tickit_term_print(3), tickit_term_bind_event(3), tickit_term(7),
100 tickit(7)
101 TICKIT_TERM_BUILD(3)