1.\"- 2.\" Copyright (c) 2020 Soumendra Ganguly <soumendraganguly@gmail.com> 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 14.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 16.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 17.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 18.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 19.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 20.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 21.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 22.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 23.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" Portions of this text are reprinted and reproduced in electronic form 26.\" from P1003.1-202x, Draft 1.1, Draft Standard for Information Technology -- 27.\" Portable Operating System Interface (POSIX), The Open Group Base 28.\" Specifications Issue 8, Copyright (C) 2020 by the Institute of 29.\" Electrical and Electronics Engineers, Inc and The Open Group. In the 30.\" event of any discrepancy between this version and the original IEEE and 31.\" The Open Group Standard, the original IEEE and The Open Group Standard is 32.\" the referee document. The original Standard can be obtained online at 33.\" http://www.opengroup.org/unix/online.html. 34.\" 35.\" $FreeBSD$ 36.\" 37.Dd December 28, 2020 38.Dt TCGETWINSIZE 3 39.Os 40.Sh NAME 41.Nm tcgetwinsize , 42.Nm tcsetwinsize 43.Nd get, set the size of a terminal window 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In termios.h 48.Bd -literal 49struct winsize { 50 unsigned short ws_row; /* number of rows, in characters */ 51 unsigned short ws_col; /* number of columns, in characters */ 52 unsigned short ws_xpixel; /* horizontal size, in pixels */ 53 unsigned short ws_ypixel; /* vertical size, in pixels */ 54}; 55.Ed 56.Pp 57.Ft int 58.Fn tcgetwinsize "int fd" "struct winsize *w" 59.Ft int 60.Fn tcsetwinsize "int fd" "const struct winsize *w" 61.Sh DESCRIPTION 62The 63.Fn tcgetwinsize 64function gets the terminal window size of the terminal of which 65.Fa fd 66is an open file descriptor and stores it in the 67.Vt winsize 68structure of which 69.Fa w 70is a pointer. 71.Pp 72The 73.Fn tcsetwinsize 74function sets the terminal window size of the terminal of which 75.Fa fd 76is an open file descriptor from the 77.Vt winsize 78structure referenced by 79.Fa w . 80The change occurs immediately. 81If the terminal window size of the terminal 82is changed successfully to have a value that is different from the value that 83it had before the 84.Fn tcsetwinsize 85call, then the 86.Dv SIGWINCH 87signal is sent to all those members of the foreground process group of the 88terminal that have the terminal as their controlling terminal. 89.Pp 90The above declaration of 91.Vt "struct winsize" 92may not be literal. 93It is provided only to list the accessible members. 94Therefore, before calling 95.Fn tcsetwinsize , 96the members of the 97.Vt winsize 98structure must be initialized by calling 99.Fn tcgetwinsize . 100The information in a 101.Vt winsize 102structure is stored by the kernel in order to provide a consistent interface, 103but it is not used by the kernel. 104.Sh RETURN VALUE 105.Rv -std tcgetwinsize tcsetwinsize 106The terminal window size remains unchanged if 107.Fn tcsetwinsize 108fails. 109.Pp 110.Sh ERRORS 111The following are the possible failure conditions: 112.Bl -tag -width Er 113.It Bq Er EBADF 114The 115.Fa fd 116argument to 117.Fn tcgetwinsize 118or to 119.Fn tcsetwinsize 120is not a valid file descriptor. 121.It Bq Er ENOTTY 122The 123.Fa fd 124argument to 125.Fn tcgetwinsize 126or to 127.Fn tcsetwinsize 128is not associated with a character special device. 129.It Bq Er EINVAL 130The 131.Fa w 132argument to 133.Fn tcsetwinsize 134is not valid. 135.It Bq Er EFAULT 136The 137.Fa w 138argument to 139.Fn tcgetwinsize 140or to 141.Fn tcsetwinsize 142points outside the process's allocated address space. 143.El 144.Sh SEE ALSO 145.Xr stty 1 , 146.Xr ioctl 2 , 147.Xr sigaction 2 , 148.Xr termios 4 , 149.Xr tty 4 150.Sh STANDARDS 151The 152.Fn tcgetwinsize 153and 154.Fn tcsetwinsize 155functions are expected to conform to 156.St -p1003.1 157Base Specifications, Issue 8. 158The 159.Fa ws_xpixel 160and 161.Fa ws_ypixel 162members of 163.Vt "struct winsize" 164are FreeBSD extensions. 165