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

The tcgetwinsize() function 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.

The tcsetwinsize() function 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.

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.

RETURN VALUE

The tcgetwinsize() and tcsetwinsize() functions 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.

STANDARDS

The tcgetwinsize() and tcsetwinsize() functions 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.