border(3NCURSES)

💅 border(3NCURSES) — Library calls 💅

okay bestie, welcome to the border(3NCURSES) page, it's giving frames, lines, and main character window energy ✨ this is the ncurses manual, and we're about to draw some boxes together 🎀

---

✨ NAME ✨

border, wborder, box, hline, whline, vline, wvline, mvhline, mvwhline, mvvline, mvwvline — draw borders and lines in a curses window of characters 💖

like… literally the girls that make your little terminal rectangle have an outline. iconic.

---

🌸 SYNOPSIS 🌸

#include <curses.h>

int border(chtype ls, chtype rs, chtype ts, chtype bs,
      chtype tl, chtype tr, chtype bl, chtype br);
int wborder(WINDOW *win, chtype ls, chtype rs,
      chtype ts, chtype bs, chtype tl, chtype tr,
      chtype bl, chtype br);

int box(WINDOW *win, chtype verch, chtype horch);

int hline(chtype ch, int n);
int whline(WINDOW *win, chtype ch, int n);
int mvhline(int y, int x, chtype ch, int n);
int mvwhline(WINDOW *win, int y, int x, chtype ch, int n);

int vline(chtype ch, int n);
int wvline(WINDOW *win, chtype ch, int n);
int mvvline(int y, int x, chtype ch, int n);
int mvwvline(WINDOW *win, int y, int x, chtype ch, int n);

---

🦋 DESCRIPTION 🦋

so wborder and border draw a box at the edges of the specified window, or stdscr respectively 💖 like one does the window you hand it, the other just does stdscr because it's confident like that.

every chtype argument maps to one lil geometric component of the border, and the assignment is:

• ls — left side
• rs — right side
• ts — top side
• bs — bottom side
• tl — top left-hand corner
• tr — top right-hand corner
• bl — bottom left-hand corner
• br — bottom right-hand corner

if any chtype argument is 0, then curses uses forms-drawing characters instead — see addch(3NCURSES) — and the correspondence goes like this, in order:

• ACS_VLINE
• ACS_VLINE
• ACS_HLINE
• ACS_HLINE
• ACS_ULCORNER
• ACS_URCORNER
• ACS_LLCORNER
• ACS_LRCORNER

like, it's giving default pretty lines when you can't be bothered to pick. no cap 🫶

box(win, verch, horch) is shorthand for "wborder(win, verch, verch, horch, horch, 0, 0, 0, 0)". that's it, that's the whole function, she's a shortcut queen 👑

whline draws a horizontal line of ch from left to right, and wvline draws a vertical one from top to bottom — stopping once n characters have been drawn, or upon reaching the boundary of win. whichever comes first, bestie, she knows when to stop 💅

these functions do not update the cursor position — beyond any motion directed by their mv variants, of course. ncurses(3NCURSES) describes the variants of these functions. iykyk ✨

---

😭 RETURN VALUE 😭

these functions return OK on success and ERR on failure. periodt.

in ncurses, specifically:

• these functions fail if the screen is not initialized; and
• functions taking a WINDOW pointer argument fail if win is a null pointer.

functions prefixed with mv first perform cursor movement, and they fail if the position (y, x) is outside the window boundaries. so like, don't go out of bounds, she will notice 🙈

---

🎀 NOTES 🎀

unusually, there is no wbox function. no wbox, bestie, she simply doesn't exist. box behaves as one would expect wbox to, accepting a WINDOW pointer argument. so she ate and left no crumbs 🌈

border, box, hline, mvhline, mvwhline, vline, mvvline, and mvwvline may be implemented as macros. sneaky! ⭐

borders drawn by these functions are interior borders. they live inside, like a cozy little fairy 🧚

---

💀 PORTABILITY 💀

these functions are described in X/Open Curses Issue 4. it specifies no error conditions for them. none. zero. nothing. the audacity 💀

SVr4 documentation says these functions return OK "or a non-negative integer if immedok() is set" — that's referring to the return value from wrefresh, which in SVr4 returns a count of characters written to the window if its immedok property is set. in ncurses, it does not. so don't go expecting that, fr fr.

BSD curses drew boxes with horch in every character cell of the top and bottom lines of the window. whereas SVr3.1 and later curses, because its box wrapped wborder, used the default corner characters. glow-up, honestly 🌸

---

💜 HISTORY 💜

4BSD (1980) introduced box, defining it as a function. yes, a whole function, she was born that way.

SVr3.1 (1987) added whline and wvline and their variants, as well as border and wborder, and redefined box as a macro wrapping the latter. evolution, we love to see it 🔥

---

🫶 SEE ALSO 🫶

• ncurses(3NCURSES)
• outopts(3NCURSES)

---

and that's the whole page, bestie 💖 this was ncurses 6.6, dated 2025-10-20, and it's called border(3NCURSES) — go draw ur lil boxes, you're gonna slay 👑✨🎀