TCGETWINSIZE(3)

🌸 tcgetwinsize, tcsetwinsize — get, set the size of a terminal window 🌸

okay bestie, this is TCGETWINSIZE(3) from the Library Functions Manual, and it's literally the page for getting and setting your terminal window size. no cap. 🫶

💖 NAME 💖

tcgetwinsize, tcsetwinsize — get, set the size of a terminal window.

📚 LIBRARY 📚

Standard C Library (libc, -lc).

✨ SYNOPSIS ✨

#include <termios.h>

struct winsize {
        unsigned short  ws_row;         /* number of rows, in characters */
        unsigned short  ws_col;         /* number of columns, in characters */
        unsigned short  ws_xpixel;      /* horizontal size, in pixels */
        unsigned short  ws_ypixel;      /* vertical size, in pixels */
};

int
tcgetwinsize(int fd, struct winsize *w);

int
tcsetwinsize(int fd, const struct winsize *w);

🎀 DESCRIPTION 🎀

tcgetwinsize() is the “read the room” function: it gets the terminal window size of the terminal of which fd is an open file descriptor and stores it in the winsize structure of which w is a pointer. 💅

tcsetwinsize() is the “set the vibe” function: it sets the terminal window size of the terminal of which fd is an open file descriptor from the winsize structure referenced by w. The change occurs immediately. If the terminal window size of the terminal is changed successfully to have a value that is different from the value that it had before the tcsetwinsize() call, then the SIGWINCH signal is sent to all those members of the foreground process group of the terminal that have the terminal as their controlling terminal. periodt. 🌈

The above declaration of struct winsize may not be literal. It is provided only to list the accessible members. Therefore, before calling tcsetwinsize(), the members of the winsize structure must be initialized by calling tcgetwinsize(). The information in a winsize structure is stored by the kernel in order to provide a consistent interface, but it is not used by the kernel. (The kernel is keeping receipts but not using them, iconic. 💀)

💜 RETURN VALUE 💜

tcgetwinsize() and tcsetwinsize() return the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. The terminal window size remains unchanged if tcsetwinsize() fails. 🫶

💀 ERRORS 💀

The following are the possible failure conditions:

• [EBADF] — the fd argument to tcgetwinsize() or to tcsetwinsize() is not a valid file descriptor.
• [ENOTTY] — the fd argument to tcgetwinsize() or to tcsetwinsize() is not associated with a character special device.
• [EINVAL] — the w argument to tcsetwinsize() is not valid.
• [EFAULT] — the w argument to tcgetwinsize() or to tcsetwinsize() points outside the process's allocated address space.

👀 SEE ALSO 👀

stty(1), ioctl(2), sigaction(2), termios(4), tty(4)

🌈 STANDARDS 🌈

tcgetwinsize() and tcsetwinsize() are expected to conform to IEEE Std 1003.1 (“POSIX.1”) Base Specifications, Issue 8. The ws_xpixel and ws_ypixel members of struct winsize are FreeBSD extensions. ✨

mwah 💋 source/version says Debian, date says December 28, 2020, and the page is TCGETWINSIZE(3) — that's the tea, bestie. 🍵👑