TCGETWINSIZE(3)

TCGETWINSIZE(3) | Library Functions Manual | TCGETWINSIZE(3)

# NAME

`tcgetwinsize`, `tcsetwinsize` —
manipulate terminal window size

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <termios.h>`

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

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

# DESCRIPTION

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 `tcgetwinsize`() 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 `tcsetwinsize`() 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 `tcsetwinsize`() does not necessarily change the actual window size, and if not, will not generate a `SIGWINCH`.

# ERRORS

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:

[`EBADF`]
  The fd argument to `tcgetwinsize`() or `tcsetwinsize`() is not a valid file descriptor.
[`EFAULT`]
  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.
[`EINVAL`]
  The values passed in the sws `winsize` structure to `tcsetwinsize`() represent an attempt to set the window size to an invalid state.
[`ENOTTY`]
  The fd argument to `tcgetwinsize`() or `tcsetwinsize`() does not represent a terminal device capable of remembering a window size.

# SEE ALSO

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

# STANDARDS

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.

# HISTORY

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.

# CAVEATS

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 9.0