The Open Group Base Specifications Issue 8
IEEE Std 1003.1-2024
Copyright © 2001-2024 The IEEE and The Open Group

NAME

tcsetwinsize — set the size of a terminal window

SYNOPSIS

#include <termios.h>

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

DESCRIPTION

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() on fildes; an application should modify only fields defined by this volume of POSIX.1-2024 between the call to tcgetwinsize() 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:

RETURN VALUE

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

ERRORS

The tcsetwinsize() function shall fail if:

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

The tcsetwinsize() function may fail if:

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

The following sections are informative.

EXAMPLES

None.

APPLICATION USAGE

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.

RATIONALE

This standard does not mention the ws_xpixel and ws_ypixel fields that appear in the winsize structure of some historical implementations. With current hardware, it is not obvious that the unsigned short 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() to initialize any fields that may be provided by an implementation before setting the ws_cols and ws_rows fields using tcsetwinsize() to avoid unintentionally destroying data in other fields in this structure.

FUTURE DIRECTIONS

None.

SEE ALSO

tcgetwinsize

XBD <termios.h>

CHANGE HISTORY

First released in Issue 8.

End of informative text.

 

return to top of page

UNIX® is a registered Trademark of The Open Group.
POSIX™ is a Trademark of The IEEE.
Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]