1notcurses_init(3) notcurses_init(3)
2
6 notcurses_init - initialize a notcurses instance
7
9 #include <notcurses/notcurses.h>
10 #define NCOPTION_INHIBIT_SETLOCALE 0x0001ull
12 #define NCOPTION_NO_WINCH_SIGHANDLER 0x0004ull
13 #define NCOPTION_NO_QUIT_SIGHANDLERS 0x0008ull
14 #define NCOPTION_SUPPRESS_BANNERS 0x0020ull
15 #define NCOPTION_NO_ALTERNATE_SCREEN 0x0040ull
16 #define NCOPTION_NO_FONT_CHANGES 0x0080ull
17 typedef enum {
19 NCLOGLEVEL_SILENT, // default. print nothing once fullscreen service begins
20 NCLOGLEVEL_PANIC, // print diagnostics immediately related to crashing
21 NCLOGLEVEL_FATAL, // we're hanging around, but we've had a horrible fault
22 NCLOGLEVEL_ERROR, // we can't keep doing this, but we can do other things
23 NCLOGLEVEL_WARNING, // you probably don't want what's happening to happen
24 NCLOGLEVEL_INFO, // "standard information"
25 NCLOGLEVEL_VERBOSE, // "detailed information"
26 NCLOGLEVEL_DEBUG, // this is honestly a bit much
27 NCLOGLEVEL_TRACE, // there's probably a better way to do what you want
28 } ncloglevel_e;
29 typedef struct notcurses_options {
31 const char* termtype;
32 FILE* renderfp;
33 ncloglevel_e loglevel;
34 int margin_t, margin_r, margin_b, margin_l;
35 uint64_t flags; // from NCOPTION_* bits
36 } notcurses_options;
37 struct notcurses* notcurses_init(const notcurses_options* opts, FILE*
39 fp);
40 void notcurses_version_components(int* major, int* minor, int* patch,
42 int* tweak);
43 int notcurses_lex_margins(const char* op, notcurses_options* opts);
45 int notcurses_cursor_enable(struct notcurses* nc, int y, int x);
47 int notcurses_cursor_disable(struct notcurses* nc);
49
51 notcurses_init prepares the terminal for cursor-addressable (multiline)
52 mode. The FILE provided as fp must be writable and attached to a ter‐
53 minal, or NULL. If it is NULL, /dev/tty will be opened. The struct
54 notcurses_option passed as opts controls behavior. Only one instance
55 should be associated with a given terminal at a time, though it is no
56 problem to have multiple instances in a given process.
57 On success, a pointer to a valid struct notcurses is returned. NULL is
59 returned on failure. Before the process exits, notcurses_stop(3)
60 should be called to reset the terminal and free up resources.
61 An appropriate terminfo(5) entry must exist for the terminal. This en‐
63 try is usually selected using the value of the TERM environment vari‐
64 able (see getenv(3)), but a non-NULL value for termtype will override
65 this. An invalid terminfo specification can lead to reduced perfor‐
66 mance, reduced display capabilities, and/or display errors. notcurses
67 natively targets 24bpp/8bpc RGB color, and it is thus desirable to use
68 a terminal with the rgb capability (e.g. xterm's xterm-direct).
69 If the terminal advertises support for an "alternate screen" via the
71 smcup terminfo capability, notcurses will employ it by default. This
72 can be prevented by setting NCOPTION_NO_ALTERNATE_SCREEN in flags.
73 Users tend to have strong opinions regarding the alternate screen, so
74 it's often useful to expose this via a command-line option.
75 notcurses hides the cursor by default. It can be dynamically enabled,
77 moved, or disabled during execution via notcurses_cursor_enable(3) and
78 notcurses_cursor_disable(3).
79 notcurses_init typically emits some diagnostics at startup, including
81 version information and some details of the configured terminal. This
82 can be inhibited with NCOPTION_SUPPRESS_BANNERS. This will also inhib‐
83 it the performance summary normally printed by notcurses_stop(3).
84 Notcurses can render to a subregion of the terminal by specifying de‐
86 sired margins on all four sides. By default, all margins are zero, and
87 thus rendering will be performed on the entirety of the viewing area.
88 This is orthogonal to use of the alternate screen; using the alternate
89 screen plus margins will see the full screen cleared, followed by ren‐
90 dering to a subregion. Inhibiting the alternate screen plus margins
91 will see rendering to a subregion, with the screen outside this region
92 not cleared. This is the only means by which existing output can be
93 undisturbed by notcurses. Margins are best-effort. Supplying any neg‐
94 ative margin is an error. notcurses_lex_margins provides lexing a mar‐
95 gin argument expression in one of two forms:
96 · a single number, which will be applied to all sides, or
98 · four comma-delimited numbers, applied to top, right, bottom, and
100 left.
101 To allow future options without requiring redefinition of the struc‐
103 ture, the flags field is only a partially-defined bitfield. Undefined
104 bits should be zero. The following flags are defined:
105 · NCOPTION_INHIBIT_SETLOCALE: Unless this flag is set, notcurses_init
107 will call setlocale(LC_ALL, NULL). If the result is either "C" or
108 "POSIX", it will print a diagnostic to stderr, and then call setlo‐
109 cale(LC_ALL, ""). This will attempt to set the locale based off the
110 LANG environment variable. Your program should call setlocale(3) it‐
111 self, usually as one of the first lines.
112 · NCOPTION_NO_WINCH_SIGHANDLER: A signal handler will usually be in‐
114 stalled for SIGWINCH and SIGCONT, resulting in NCKEY_RESIZE events
115 being generated on input. With this flag, the handler will not be
116 installed.
117 · NCOPTION_NO_QUIT_SIGHANDLERS: A signal handler will usually be in‐
119 stalled for SIGINT, SIGILL, SIGQUIT, SIGSEGV, SIGTERM, and SIGABRT,
120 cleaning up the terminal on such exceptions. With this flag, the
121 handler will not be installed.
122 · NCOPTION_SUPPRESS_BANNERS: Disables the diagnostics and version in‐
124 formation printed on startup, and the performance summary on exit.
125 · NCOPTION_NO_ALTERNATE_SCREEN: Do not use the alternate screen (see
127 terminfo(5)), even if it is available.
128 · NCOPTION_NO_FONT_CHANGES: Do not touch the font. Notcurses might
130 otherwise attempt to extend the font, especially in the Linux con‐
131 sole.
132 Fatal signals
134 It is important to reset the terminal before exiting, whether terminat‐
135 ing due to intended operation or a received signal. This is usually
136 accomplished by explicitly calling notcurses_stop(3) during shutdown.
137 For convenience, notcurses by default installs signal handlers for var‐
138 ious signals which would typically result in process termination (see
139 signal(7)). These signal handlers call notcurses_stop(3) for each
140 struct notcurses in the process, and then propagate the signal to any
141 previously-configured handler. These handlers are disabled upon entry
142 to notcurses_stop(3).
143 To prevent signal handler registration, provide NCOP‐
145 TION_NO_QUIT_SIGHANDLERS. No means is provided to selectively register
146 fatal signal handlers. If this is done, the caller ought be sure to
147 effect similar functionality themselves.
148 Resize events
150 SIGWINCH (SIGnal WINdow CHange) is delivered to the process when the
151 terminal is resized. The default action is to ignore it (SIG_IGN).
152 notcurses installs a handler for this signal. The handler causes
153 notcurses to update its idea of the terminal's size using TIOCGWINSZ
154 (see ioctl_tty(2)), and generates an NCKEY_RESIZE input event (see
155 notcurses_input(3). This signal handler can be inhibited by setting
156 NCOPTION_NO_WINCH_SIGHANDLER in flags. If this is done, the caller
157 should probably watch for the signal, and invoke notcurses_refresh(3)
158 or notcurses_render(3) upon its receipt.
159 A resize event does not invalidate any references returned earlier by
161 notcurses. The content of any new screen area is undefined until the
162 next call to notcurses_render(3). This is true even if an existing
163 struct ncplane (see notcurses_plane(3)) overlaps the new area, since
164 the signal could arrive while the ncplanes are being modified. Signal
165 handlers are quite restricted as to what actions they can perform, so
166 minimal work is performed in the handler proper.
167 Thus, in the absence of NCOPTION_NO_WINCH_SIGHANDLER, SIGWINCH results
169 in:
170 · interruption of some thread to process the signal
172 · a TIOCGWINSZ ioctl to retrieve the new screen size
174 · queuing of a NCKEY_RESIZE input event (if there is space in the
176 queue)
177 Upon the next call to notcurses_render(3) or notcurses_refresh(3), the
179 standard plane (see notcurses_stdplane(3)) will be resized to the new
180 screen size. The next notcurses_render(3) call will function as ex‐
181 pected across the new screen geometry.
182
184 NULL is returned on failure. Otherwise, the return value points at a
185 valid struct notcurses, which can be used until it is provided to
186 notcurses_stop(3).
187
189 getenv(3), setlocale(3), termios(3), notcurses(3), notcurses_input(3),
190 notcurses_plane(3), notcurses_refresh(3), notcurses_render(3), notcurs‐
191 es_stop(3), terminfo(5), signal(7)
192
194 nick black <nickblack@linux.com>.
195 v2.2.3 notcurses_init(3)