curs_border(3X)

💖 curs_border — the manual page, but make it cute 💖

okay so bestie, this is curs_border(3X), a Library call from the ncurses crew, and it's literally all about drawing borders and lines in a curses window of characters. like, boxes. pretty lines. the whole aesthetic. 🎀

---

✨ NAME ✨

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

---

🌸 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 🦋

okay so wborder and border draw a box at the edges of the window you picked, or of stdscr respectively (that's the glow-up difference between them 💫). each chtype argument is a specific geometric component of the border, like a little puzzle piece:

• 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, and
• br — bottom right-hand corner.

and here's the tea: if any chtype argument is 0, curses just goes "say less" and uses forms-drawing characters instead (peep addch(3X)), in this exact correspondence:

• ACS_VLINE,
• ACS_VLINE,
• ACS_HLINE,
• ACS_HLINE,
• ACS_ULCORNER,
• ACS_URCORNER,
• ACS_LLCORNER, and
• ACS_LRCORNER.

ngl box(win, verch, horch) is just shorthand for:

wborder(win, verch, verch, horch, horch, 0, 0, 0, 0)

iconic, right? 💅

so whline draws a horizontal line of ch going left to right, and wvline does a vertical one going top to bottom. they stop once n characters have been drawn, or the moment they hit the boundary of win — whichever comes first, bestie, they know when to stop. 🛑

and the way that these functions do not update the cursor position (beyond any motion directed by their mv variants) — yeah, cursor stays put. ncurses(3X) is where the variants of these functions get described, iykyk.

---

⭐ RETURN VALUE ⭐

these functions return OK on success and ERR on failure. simple as that, periodt.

in ncurses:

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

and the functions prefixed with mv? they first perform cursor movement, and they fail if the position (y, x) is outside the window boundaries. so don't be sending them off-grid fr fr.

---

🎀 NOTES 🎀

unusually — and honestly this is a lil quirky of the codebase — there is no wbox function. like, at all. box just behaves as one would expect wbox to, accepting a WINDOW pointer argument. main character energy, honestly. 👑

also: border, box, hline, mvhline, mvwhline, vline, mvvline, and mvwvline may be implemented as macros. so no, you can't always take their address, bestie. 🙈

and one more thing: borders drawn by these functions are interior borders.

---

🌈 PORTABILITY 🌈

these functions are described in X/Open Curses Issue 4. it specifies no error conditions for them. wild, right?

SVr4 documentation says these functions return OK "or a non-negative integer if immedok() is set" — and 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 yeah, don't count on that one. 😭

and the history lesson: 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 used the default corner characters — because its box wrapped wborder. glow-up behavior, honestly. ✨

---

🧚 HISTORY 🧚

4BSD (1980) introduced box, defining it as a function.

SVr3.1 (1987) added whline and wvline and their variants, as well as border and wborder, redefining box as a macro wrapping the latter. we love an evolution arc. 💜

---

💜 SEE ALSO 💜

curses(3X), curs_outopts(3X)

---

and that's the whole page, bestie!! 🫶 this was ncurses 6.6, dated 2025-10-20, brought to you by the curs_border(3X) manual page. go draw some boxes, slay, and remember: interior borders only, no wbox, no cap. 💖✨🌸