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.