--- name: "notcurses_output" section: "3" platform: "linux" package: "notcurses" version: "3.0.17-3" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/notcurses_output" --- # notcurses\_output(3) output to ncplanes ## NAME notcurses\_output - output to ncplanes ## SYNOPSIS **#include \** **static inline int ncplane\_putc(struct ncplane\*** *n***, const nccell\*** *c***);** **int ncplane\_putc\_yx(struct ncplane\*** *n***, int** *y***, int** *x***, const nccell\*** *c***);** **static inline int ncplane\_putchar(struct ncplane\*** *n***, char** *c***);** **static inline int ncplane\_putchar\_yx(struct ncplane\*** *n***, int** *y***, int** *x***, char** *c***);** **int ncplane\_putchar\_stained(struct ncplane\*** *n***,** **char** *c***);** **static inline int ncplane\_putwc(struct ncplane\*** *n***, wchar\_t** *w***);** **int ncplane\_putwc\_yx(struct ncplane\*** *n***, int** *y***, int** *x***, wchar\_t** *w***);** **static inline int ncplane\_putwc\_stained(struct ncplane\*** *n***, wchar\_t** *w***);** **static inline int ncplane\_putegc(struct ncplane\*** *n***, const char\*** *gclust***, int\*** *sbytes***);** **int ncplane\_putegc\_yx(struct ncplane\*** *n***, int** *y***, int** *x***, const char\*** *gclust***, int\*** *sbytes***);** **int ncplane\_putegc\_stained(struct ncplane\*** *n***,** **const char\*** *gclust***, int\*** *sbytes***);** **static inline int ncplane\_putwegc(struct ncplane\*** *n***, const wchar\_t\*** *gclust***, int\*** *sbytes***);** **static inline int ncplane\_putwegc\_yx(struct ncplane\*** *n***, int** *y***, int** *x***, const wchar\_t\*** *gclust***, int\*** *sbytes***);** **int ncplane\_putwegc\_stained(struct ncplane\*** *n***,** **const wchar\_t\*** *gclust***, int\*** *sbytes***);** **int ncplane\_putstr\_yx(struct ncplane\*** *n***, int** *y***, int** *x***, const char\*** *gclustarr***);** **static inline int ncplane\_putstr(struct ncplane\*** *n***, const char\*** *gclustarr***);** **int ncplane\_putstr\_aligned(struct ncplane\*** *n***,** **int** *y***, ncalign\_e** *align***, const** **char\*** *s***);** **int ncplane\_putstr\_stained(struct ncplane\*** *n***,** **const char\*** *s***);** **static inline int ncplane\_putwstr(struct ncplane\*** *n***, const wchar\_t\*** *gclustarr***);** **int ncplane\_putwstr\_yx(struct ncplane\*** *n***, int** *y***, int** *x***, const wchar\_t\*** *gclustarr***);** **static inline int ncplane\_putwstr\_aligned(struct ncplane\*** *n***, int** *y***, ncalign\_e** *align***, const wchar\_t\*** *gclustarr***);** **int ncplane\_putwstr\_stained(struct ncplane\*** *n***,** **const wchar\_t\*** *gclustarr***);** **static inline int ncplane\_putnstr(struct ncplane\*** *n***, size\_t** *s***, const char\*** *gclustarr***);** **int ncplane\_putnstr\_yx(struct ncplane\*** *n***, int** *y***, int** *x***, size\_t** *s***, const char\*** *gclusters***);** **int ncplane\_putnstr\_aligned(struct ncplane\*** *n***,** **int** *y***, ncalign\_e** *align***, size\_t** *s***, const char\*** *s***);** **int ncplane\_vprintf\_aligned(struct ncplane\*** *n***,** **int** *y***, ncalign\_e** *align***, const** **char\*** *format***, va\_list** *ap***);** **int ncplane\_vprintf\_yx(struct ncplane\*** *n***, int** *y***, int** *x***, const char\*** *format***, va\_list** *ap***);** **static inline int ncplane\_vprintf(struct ncplane\*** *n***, const char\*** *format***, va\_list** *ap***);** **static inline int ncplane\_printf(struct ncplane\*** *n***, const char\*** *format***,** *...***);** **static inline int ncplane\_printf\_yx(struct ncplane\*** *n***, int** *y***, int** *x***, const char\*** *format***,** *...***);** **static inline int ncplane\_printf\_aligned(struct ncplane\*** *n***, int** *y***, ncalign\_e** *align***, const char\*** *format***,** *...***);** **int ncplane\_cursor\_move\_yx(struct ncplane\*** *n***,** **int** *y***, int** *x***);** **int ncplane\_puttext(struct ncplane\*** *n***, int** *y***, ncalign\_e** *align***, const char\*** *text***, size\_t\*** *bytes***);** ## DESCRIPTION These functions write EGCs (Extended Grapheme Clusters) to the specified **struct ncplane**s. The following inputs are supported: - • **ncplane\_putc()**: writes a single **nccell** (see **[notcurses\_cell(3)](/notcurses_cell/3.md)**) - • **ncplane\_putchar()**: writes a single 7-bit ASCII character - • **ncplane\_putwc()**: writes a single **wchar\_t** (following UTF-8 conversion) - • **ncplane\_putwegc()**: writes a single EGC from an array of **wchar\_t** - • **ncplane\_putegc()**: writes a single EGC from an array of UTF-8 - • **ncplane\_putstr()**: writes a set of EGCs from an array of UTF-8 - • **ncplane\_putwstr()**: writes a set of EGCs from an array of **wchar\_t** - • **ncplane\_vprintf()**: formatted output using **va\_list** - • **ncplane\_printf()**: formatted output using variadic arguments - • **ncplane\_puttext()**: multi-line, line-broken, aligned text All of these use the **ncplane**'s active styling, save **notcurses\_putc()**, which uses the **nccell**'s styling. Functions accepting a single EGC expect a series of **wchar\_t** terminated by **L'\\0'** or a series of UTF-8 **char** terminated by **'\\0'**. The EGC must be well-formed, and must not contain any cluster breaks. For more information, consult Unicode® Standard Annex #29 ⟨https://unicode.org/reports/tr29/⟩\\c . Functions accepting a set of EGCs must consist of a series of well-formed EGCs, broken by cluster breaks, terminated by the appropriate NUL terminator. Control characters are rejected, aside from two exceptions: a horizontal tab (**'\\t'**, 0x09), and a newline (**'\\n'**, 0x0a) *when the output plane is in* *scrolling mode*. A newline outside of scrolling mode will be rejected. A tab will advance to the next tab stop, filling the space between with spaces. Tab stops are separated by eight columns, and the first character of each line is a tab stop. These functions output to the **ncplane**'s current cursor location. Aside from **ncplane\_puttext()**, they *do not* move to the next line upon reaching the right extreme of the containing plane. If the entirety of the content cannot be output, they will output as much as possible. Each of these base functions has two additional forms: - • **ncplane\_putc\_aligned()**, etc.: accepts a row and an alignment type - • **ncplane\_putc\_yx()**, etc.: accepts a row and column If a positional parameter is -1, no movement will be made along that axis. Passing **-1, -1** to e.g. **ncplane\_putc\_yx()** is equivalent to calling the base form. These functions are implemented by moving the cursor, and then performing the output. The two steps are *atomic* on success (it is not possible for another caller to move the cursor between when it is positioned, and when output begins), and thus these functions ought generally be preferred to an explicit **ncplane\_cursor\_move\_yx()**. Upon successful return, the cursor will follow the last cell output. ## RETURN VALUES **ncplane\_cursor\_move\_yx()** returns -1 on error (invalid coordinate), or 0 on success. For output functions, a negative return indicates an error with the inputs. Otherwise, the number of *screen columns* output is returned. It is entirely possible to get a short return, if there was insufficient room to output all EGCs. ## SEE ALSO **[fprintf(3)](/fprintf/3.md)** **[notcurses(3)](/notcurses/3.md)**, **[notcurses\_cell(3)](/notcurses_cell/3.md)**, **[notcurses\_plane(3)](/notcurses_plane/3.md)**, **[stdarg(3)](/stdarg/3.md)**, **[ascii(7)](/ascii/7.md)**, **[unicode(7)](/unicode/7.md)**, **[utf-8(7)](/utf-8/7.md)** ## AUTHORS nick black ⟨nickblack@linux.com⟩\\c.