TCSETWINSIZE(3) Library Functions Manual TCSETWINSIZE(3)

tcsetwinsize — set the size of a terminal window

#include <termios.h>

int tcsetwinsize(int fildes, const struct winsize *winsize_p);

The tcsetwinsize () function shall set the terminal window size associated with the terminal referred to by the open file descriptor fildes (an open file descriptor associated with a terminal) from the winsize structure referenced by winsize_p. The change shall occur immediately.

If the terminal size was changed successfully, a SIGWINCH shall be delivered to the foreground process group associated with the terminal. No signal shall be delivered if the terminal size was changed to the same value it had before the tcsetwinsize () call. A SIGWINCH may also be delivered to an implementation-defined set of other processes.

The tcsetwinsize () function shall return successfully if it was able to update all members of the winsize structure associated with the terminal.

It is unspecified whether changing the terminal window size causes any changes to the size of the terminal's font.

The effect of tcsetwinsize () is undefined if the value of the winsize structure pointed to by winsize_p was not derived from the result of a call to tcgetwinsize(3) on fildes; an application should modify only fields defined by this volume of POSIX.1-2024 between the call to tcgetwinsize(3) and tcsetwinsize (), leaving all other fields unmodified.

No actions defined by this volume of POSIX.1-2024, other than a call to tcsetwinsize (), a close of the last file descriptor in the system associated with this terminal device, or an open of the first file descriptor in the system associated with this terminal device (using the O_TTY_INIT flag if it is non-zero and the device is not a pseudo-terminal), shall cause the terminal window size to change.

If tcsetwinsize () is called from a process which is a member of a background process group on a fildes associated with its controlling terminal:

  • If the calling thread is blocking SIGTTOU signals or the process is ignoring SIGTTOU signals, the operation completes normally and no signal is sent.
  • Otherwise, a SIGTTOU signal shall be sent to the process group.

Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned, the terminal window size shall not be changed, and shall be set to indicate the error.

The tcsetwinsize () function shall fail if:

The fildes argument is not a valid file descriptor.
The process group of the writing process is orphaned, the calling thread is not blocking SIGTTOU, and the process is not ignoring SIGTTOU.
The file associated with fildes is not a terminal.

The tcsetwinsize () function may fail if:

An attempt was made to change an attribute represented in the winsize structure to an unsupported value.

None.

If the terminal window of a pseudo terminal is resized, the attached manager process should invoke tcsetwinsize () to relay the new terminal window size to the foreground process group.

If a process attached to the subsidiary device of a pseudo-terminal calls tcsetwinsize (), the attached manager process should attempt to change the screen to reflect the new size.

This standard does not mention the and fields that appear in the winsize structure of some historical implementations. With current hardware, it is not obvious that the type used for these fields is sufficient and no uses of these fields in portable code were found. However, since these and other fields may be included in the winsize structure, the standard requires that applications use tcgetwinsize(3) to initialize any fields that may be provided by an implementation before setting the and fields using tcsetwinsize () to avoid unintentionally destroying data in other fields in this structure.

None.

tcgetwinsize(3)

XBD <termios.h>

First released in Issue 8.

June 14, 2024 posix.fail