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.Dd December 28, 2020 36.Dt TCGETWINSIZE 3 37.Os 38.Sh NAME 39.Nm tcgetwinsize , 40.Nm tcsetwinsize 41.Nd get, set the size of a terminal window 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In termios.h 46.Bd -literal 47struct winsize { 48 unsigned short ws_row; /* number of rows, in characters */ 49 unsigned short ws_col; /* number of columns, in characters */ 50 unsigned short ws_xpixel; /* horizontal size, in pixels */ 51 unsigned short ws_ypixel; /* vertical size, in pixels */ 52}; 53.Ed 54.Pp 55.Ft int 56.Fn tcgetwinsize "int fd" "struct winsize *w" 57.Ft int 58.Fn tcsetwinsize "int fd" "const struct winsize *w" 59.Sh DESCRIPTION 60The 61.Fn tcgetwinsize 62function gets the terminal window size of the terminal of which 63.Fa fd 64is an open file descriptor and stores it in the 65.Vt winsize 66structure of which 67.Fa w 68is a pointer. 69.Pp 70The 71.Fn tcsetwinsize 72function sets the terminal window size of the terminal of which 73.Fa fd 74is an open file descriptor from the 75.Vt winsize 76structure referenced by 77.Fa w . 78The change occurs immediately. 79If the terminal window size of the terminal 80is changed successfully to have a value that is different from the value that 81it had before the 82.Fn tcsetwinsize 83call, then the 84.Dv SIGWINCH 85signal is sent to all those members of the foreground process group of the 86terminal that have the terminal as their controlling terminal. 87.Pp 88The above declaration of 89.Vt "struct winsize" 90may not be literal. 91It is provided only to list the accessible members. 92Therefore, before calling 93.Fn tcsetwinsize , 94the members of the 95.Vt winsize 96structure must be initialized by calling 97.Fn tcgetwinsize . 98The information in a 99.Vt winsize 100structure is stored by the kernel in order to provide a consistent interface, 101but it is not used by the kernel. 102.Sh RETURN VALUE 103.Rv -std tcgetwinsize tcsetwinsize 104The terminal window size remains unchanged if 105.Fn tcsetwinsize 106fails. 107.Pp 108.Sh ERRORS 109The following are the possible failure conditions: 110.Bl -tag -width Er 111.It Bq Er EBADF 112The 113.Fa fd 114argument to 115.Fn tcgetwinsize 116or to 117.Fn tcsetwinsize 118is not a valid file descriptor. 119.It Bq Er ENOTTY 120The 121.Fa fd 122argument to 123.Fn tcgetwinsize 124or to 125.Fn tcsetwinsize 126is not associated with a character special device. 127.It Bq Er EINVAL 128The 129.Fa w 130argument to 131.Fn tcsetwinsize 132is not valid. 133.It Bq Er EFAULT 134The 135.Fa w 136argument to 137.Fn tcgetwinsize 138or to 139.Fn tcsetwinsize 140points outside the process's allocated address space. 141.El 142.Sh SEE ALSO 143.Xr stty 1 , 144.Xr ioctl 2 , 145.Xr sigaction 2 , 146.Xr termios 4 , 147.Xr tty 4 148.Sh STANDARDS 149The 150.Fn tcgetwinsize 151and 152.Fn tcsetwinsize 153functions are expected to conform to 154.St -p1003.1 155Base Specifications, Issue 8. 156The 157.Fa ws_xpixel 158and 159.Fa ws_ypixel 160members of 161.Vt "struct winsize" 162are FreeBSD extensions. 163