notcurses_init prepares the terminal for cursor-addressable (multiline) mode, writing to some FILE. If
the FILE provided as fp is NULL, stdout will be used. Whatever FILE is used must be writable, is ideally
fully buffered, and must be byte-oriented (see fwide(3)). If the FILE is not connected to a terminal
(for example when redirected to a file), /dev/tty will be opened (if possible) for communication with the
controlling terminal. Most output (including all styling and coloring) is written to the FILE; only
queries need be sent to a true terminal. If no terminal is available (for example when running as a dae‐
mon), defaults regarding such things as screen size and the palette are assumed.
The structnotcurses_option passed as opts controls behavior. Passing a NULLopts is equivalent to pass‐
ing an all-zero (default) opts. A process can have only one Notcurses context active at a time; calling
notcurses_init again before calling notcurses_stop will return NULL (this is reliable even if called con‐
currently from two threads).
On success, a pointer to a valid structnotcurses is returned. NULL is returned on failure. Before the
process exits, notcurses_stop(3) should be called to reset the terminal and free up resources.
An appropriate terminfo(5) entry must exist for the terminal. This entry is usually selected using the
value of the TERM environment variable (see getenv(3)), but a non-NULL value for termtype will override
this (terminfo is not used on Microsoft Windows, where it is neither meaningful nor necessary to define
TERM). An invalid terminfo specification can lead to reduced performance, reduced display capabilities,
and/or display errors. Notcurses natively targets 24bpp/8bpc RGB color, and it is thus desirable to use
a terminal with the rgb capability (e.g. xterm's xterm-direct). Colors will otherwise be quantized down
to whatever the terminal supports.
If the terminal advertises support for an "alternate screen" via the smcup terminfo capability, Notcurses
will employ it by default. This can be prevented by setting NCOPTION_NO_ALTERNATE_SCREEN in flags.
Users tend to have strong opinions regarding the alternate screen, so it's often useful to expose this
via a command-line option. When the alternate screen is not used, the contents of the terminal at start‐
up remain visible until obliterated, on a cell-by-cell basis (see notcurses_plane(3) for details on
clearing the screen at startup without using the alternate screen). If the alternate screen is not
available, the display will still be cleared without NCOPTION_NO_ALTERNATE_SCREEN.
Notcurses hides the cursor by default. It can be dynamically enabled, moved, or disabled during execu‐
tion via notcurses_cursor_enable and notcurses_cursor_disable. It will be hidden while updating the
screen. The current location of the terminal cursor can be acquired with notcurses_cursor_yx, whether
visible or not.
notcurses_init typically emits some diagnostics at startup, including version information and some de‐
tails of the configured terminal. This can be inhibited with NCOPTION_SUPPRESS_BANNERS. This will also
inhibit the performance summary normally printed by notcurses_stop(3).
Notcurses can render to a subregion of the terminal by specifying desired margins on all four sides. By
default, all margins are zero, and thus rendering will be performed on the entirety of the viewing area.
This is orthogonal to use of the alternate screen; using the alternate screen plus margins will see the
full screen cleared, followed by rendering to a subregion. Inhibiting the alternate screen plus margins
will render to a subregion, with the screen outside this region not cleared. Margins are best-effort.
notcurses_lex_margins provides lexing a margin argument expression in one of two forms:
• a single number, which will be applied to all sides, or
• four comma-delimited numbers, applied to top, right, bottom, and left.
To allow future options without requiring redefinition of the structure, the flags field is only a par‐
tially-defined bitfield. Undefined bits should be zero. The following flags are defined:
• NCOPTION_INHIBIT_SETLOCALE: Unless this flag is set, notcurses_init will call setlocale(LC_ALL,NULL).
If the result is either "C" or "POSIX", it will print a diagnostic to stderr, and then call setlo‐cale(LC_ALL,""). This will attempt to set the locale based off the LANG environment variable. Your
program should call setlocale(3) itself, usually as one of the first lines.
• NCOPTION_NO_CLEAR_BITMAPS: On entry, make no special attempt to clear any preexisting bitmaps. Note
that they might still get cleared even if this is set, and they might not get cleared even if this is
not set.
• NCOPTION_NO_WINCH_SIGHANDLER: A signal handler will usually be installed for SIGWINCH and SIGCONT, re‐
sulting in NCKEY_RESIZE events being generated on input. With this flag, the handler will not be in‐
stalled.
• NCOPTION_NO_QUIT_SIGHANDLERS: A signal handler will usually be installed for SIGABRT, SIGBUS, SIGFPE,
SIGILL, SIGINT, SIGQUIT, SIGSEGV, and SIGTERM, cleaning up the terminal on such exceptions. With this
flag, the handler will not be installed.
• NCOPTION_PRESERVE_CURSOR: The virtual cursor is typically placed at the screen's origin at startup.
With this flag, it is instead placed wherever the cursor was at program launch.
• NCOPTION_SUPPRESS_BANNERS: Disables the diagnostics and version information printed on startup, and the
performance summary on exit.
• NCOPTION_NO_ALTERNATE_SCREEN: Do not use the alternate screen (see terminfo(5)), even if it is avail‐
able.
• NCOPTION_NO_FONT_CHANGES: Do not touch the font. Notcurses might otherwise attempt to extend the font,
especially in the Linux console.
• NCOPTION_DRAIN_INPUT: Standard input may be freely discarded. If you do not intend to process input,
pass this flag. Otherwise, input can buffer up, and eventually prevent Notcurses from processing mes‐
sages from the terminal. It will furthermore avoid wasting time processing useless input.
• NCOPTION_SCROLLING: Enable scrolling on the standard plane. This is equivalent to calling nc‐plane_set_scrolling(stdn,true) on some standard plane stdn.
NCOPTION_CLI_MODE is provided as an alias for the bitwise OR of NCOPTION_SCROLLING, NCOPTION_NO_ALTER‐NATE_SCREEN, NCOPTION_PRESERVE_CURSOR, and NCOPTION_NO_CLEAR_BITMAPS. If writing a CLI, it is recommend‐
ed to use NCOPTION_CLI_MODE rather than explicitly listing these options.
notcurses_default_foreground returns the default foreground color, if it could be detected. notcurs‐es_default_background returns the default background color, if it could be detected.
Fatalsignals
It is important to reset the terminal before exiting, whether terminating due to intended operation or a
received signal. This is usually accomplished by explicitly calling notcurses_stop(3) during shutdown.
For convenience, Notcurses by default installs signal handlers for various signals which would typically
result in process termination (see signal(7)). These signal handlers call notcurses_stop(3) for each
structnotcurses in the process, and then propagate the signal to any previously-configured handler.
These handlers are disabled upon entry to notcurses_stop(3).
To prevent signal handler registration, provide NCOPTION_NO_QUIT_SIGHANDLERS. No means is provided to
selectively register fatal signal handlers. If this is done, the caller ought be sure to effect similar
functionality themselves.
ResizeeventsSIGWINCH (SIGnal WINdow CHange) is delivered to the process when the terminal is resized. The default
action is to ignore it (SIG_IGN). Notcurses installs a handler for this signal. The handler causes
Notcurses to update its idea of the terminal's size using TIOCGWINSZ (see ioctl_tty(2)), and generates an
NCKEY_RESIZE input event (see notcurses_input(3). This signal handler can be inhibited by setting NCOP‐TION_NO_WINCH_SIGHANDLER in flags. If this is done, the caller should probably watch for the signal, and
invoke notcurses_refresh(3) or notcurses_render(3) upon its receipt.
A resize event does not invalidate any references returned earlier by Notcurses. The content of any new
screen area is undefined until the next call to notcurses_render(3). This is true even if an existing
structncplane (see notcurses_plane(3)) overlaps the new area, since the signal could arrive while the
ncplanes are being modified. Signal handlers are quite restricted as to what actions they can perform,
so minimal work is performed in the handler proper.
Thus, in the absence of NCOPTION_NO_WINCH_SIGHANDLER, SIGWINCH results in:
• interruption of some thread to process the signal
• a TIOCGWINSZioctl to retrieve the new screen size
• queuing of a NCKEY_RESIZE input event (if there is space in the queue)
Upon the next call to notcurses_render(3) or notcurses_refresh(3), the standard plane (see notcurses_std‐plane(3)) will be resized to the new screen size. The next notcurses_render(3) call will function as ex‐
pected across the new screen geometry.
Thehardwarecursor
Most terminals provide a cursor, a visual indicator of where output will next be placed. There is usual‐
ly (but not always) some degree of control over what glyph forms this cursor, and whether it e.g.
blinks.
By default, Notcurses disables this cursor in rendered mode. It can be turned back on with notcurses_en‐able_cursor, which has immediate effect (there is no need to call notcurses_render(3)). If already visi‐
ble, this function updates the location. Each time the physical screen is updated, Notcurses will dis‐
able the cursor, write the update, move the cursor back to this location, and finally make the cursor
visible. notcurses_cursor_yx retrieves the location of the cursor, whether visible or not. notcurs‐es_disable_cursor hides the cursor.
You generally shouldn't need to touch the terminal cursor. It's only really relevant with echoed user
input, and you don't want echoed user input in rendered mode (instead, read the input, and write it to a
plane yourself). A subprocess can be streamed to a plane with an ncsubproc, etc.
If the NCOPTION_PRESERVE_CURSOR flag is provided, the cursor's location will be determined at startup,
and the standard plane's virtual cursor will be placed to match it (instead of in the upper-left corner).
Combined with NCOPTION_NO_ALTERNATE_SCREEN and a scrolling standard plane, this allows rendered mode to
be used as a normal scrolling shell application.
Install Now
PNG Icons
