Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

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.

NetBSD 10.99                   October 25, 2017                   NetBSD 10.99