TCGETWINSIZE(3) Library Functions Manual TCGETWINSIZE(3)

tcgetwinsize, tcsetwinsize — manipulate terminal window size

Standard C Library (libc, -lc)

#include <termios.h>

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

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

The tcgetwinsize function fills in the winsize structure pointed to by gws with values that represent the size of the terminal window for which fd provides an open file descriptor. If no error occurs () returns zero (0).

The tcsetwinsize function sets the terminal window size, for the terminal referenced by fd, to the sizes from the winsize structure pointed to by sws. If no error occurs () returns zero (0).

The winsize structure, defined in <termios.h>, contains (at least) the following four fields

	unsigned short ws_row;      /* Number of rows, in characters */
	unsigned short ws_col;      /* Number of columns, in characters */
	unsigned short ws_xpixel;   /* Width, in pixels */
	unsigned short ws_ypixel;   /* Height, in pixels */

If the actual window size of the controlling terminal of a process changes, the process is sent a SIGWINCH signal. See signal(7). Note simply changing the sizes using () does not necessarily change the actual window size, and if not, will not generate a SIGWINCH.

If an error occurs, tcgetwinsize() and tcsetwinsize() return -1 and cause the global variable errno to be set to indicate the error. Common errors are as follows:

[]
The fd argument to tcgetwinsize() or tcsetwinsize() is not a valid file descriptor.
[]
The gws argument to tcgetwinsize() does not point to a suitable location into which to store the resulting winsize structure, or the sws argument to tcsetwinsize() does not refer to a suitable location from which the winsize structure can be obtained.
[]
The values passed in the sws winsize structure to tcsetwinsize() represent an attempt to set the window size to an invalid state.
[]
The fd argument to tcgetwinsize() or tcsetwinsize() does not represent a terminal device capable of remembering a window size.

stty(1), pty(4), termios(4), tty(4), signal(7)

The tcgetwinsize and tcsetwinsize functions will conform to IEEE Std 1003.1 (“POSIX.1”) issue 8, when it is published.

The ws_xpixel and ws_ypixel fields are extensions to the standard.

The standard only requires pseudo-terminals (pty(4)) to support these operations. In NetBSD all terminal devices can set and recall a window size, regardless of whether any actual window exists.

The tcgetwinsize() and tcsetwinsize() functions were added in NetBSD 8.0 after specification by POSIX as more portable alternatives to ancient ioctl operations from 4.3BSD.

It is unspecified whether calling the tcsetwinsize function causes the underlying terminal window to be resized. Nor is it specified whether altering the relationship between the character fields (ws_row and ws_col) and the pixel fields (ws_xpixel and ws_ypixel) causes the font size to change, or whether the application is required to maintain any specific relationship between these fields. In general, the tcsetwinsize function is best avoided except by applications responsible for actually implementing terminal windows.

As the winsize structure may have more fields than documented, applications planning to call tcsetwinsize() should call tcgetwinsize() first with the same fd parameter, and use the result obtained in *gws to initialize the winsize structure to be used (after altering fields that are to be changed) as the sws operand of tcsetwinsize.

October 25, 2017 NetBSD 11.0