tcgetwinsize(3) - NetBSD Manual Pages

TCGETWINSIZE(3)         NetBSD 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 remem-
                        bering 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, applica-
     tions planning to call tcsetwinsize() should call tcgetwinsize() first
     with the same fd parameter, and use the result obtained in *gws to ini-
     tialize 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