1.\" $NetBSD: tcgetwinsize.3,v 1.2 2017/10/30 15:43:21 wiz Exp $ 2.\" 3.\" Copyright (c) 2017 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd October 25, 2017 28.Dt TCGETWINSIZE 3 29.Os 30.Sh NAME 31.Nm tcgetwinsize , 32.Nm tcsetwinsize 33.Nd manipulate terminal window size 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In termios.h 38.Ft int 39.Fn tcgetwinsize "int fd" "struct winsize *gws" 40.Ft int 41.Fn tcsetwinsize "int fd" "const struct winsize *sws" 42.Sh DESCRIPTION 43The 44.Nm tcgetwinsize 45function fills in the 46.Ic winsize 47structure pointed to by 48.Fa gws 49with values that represent the size of the 50terminal window for which 51.Fa fd 52provides an open file descriptor. 53If no error occurs 54.Fn tcgetwinsize 55returns zero (0). 56.Pp 57The 58.Nm tcsetwinsize 59function sets the terminal window size, 60for the terminal referenced by 61.Fa fd , 62to the sizes from the 63.Ic winsize 64structure pointed to by 65.Fa sws . 66If no error occurs 67.Fn tcsetwinsize 68returns zero (0). 69.Pp 70The 71.Ic winsize 72structure, defined in 73.In termios.h , 74contains (at least) the following four fields 75.Bd -literal 76 unsigned short ws_row; /* Number of rows, in characters */ 77 unsigned short ws_col; /* Number of columns, in characters */ 78 unsigned short ws_xpixel; /* Width, in pixels */ 79 unsigned short ws_ypixel; /* Height, in pixels */ 80.Ed 81.Pp 82If the actual window size of the controlling terminal 83of a process changes, the process is sent a 84.Dv SIGWINCH 85signal. 86See 87.Xr signal 7 . 88Note simply changing the sizes using 89.Fn tcsetwinsize 90does not necessarily change the actual window size, 91and if not, will not generate a 92.Dv SIGWINCH . 93.Sh ERRORS 94If an error occurs, 95.Fn tcgetwinsize 96and 97.Fn tcsetwinsize 98return \-1 and cause the global variable 99.Va errno 100to be set to indicate the error. 101Common errors are as follows: 102.Bl -tag -width Er 103.It Bq Er EBADF 104The 105.Fa fd 106argument to 107.Fn tcgetwinsize 108or 109.Fn tcsetwinsize 110is not a valid file descriptor. 111.It Bq Er EFAULT 112The 113.Fa gws 114argument to 115.Fn tcgetwinsize 116does not point to a suitable location 117into which to store the resulting 118.Ic winsize 119structure, 120or the 121.Fa sws 122argument to 123.Fn tcsetwinsize 124does not refer to a suitable location 125from which the 126.Ic winsize 127structure can be obtained. 128.It Bq Er EINVAL 129The values passed in the 130.Ar sws 131.Ic winsize 132structure to 133.Fn tcsetwinsize 134represent an attempt to set the window size to an invalid state. 135.It Bq Er ENOTTY 136The 137.Fa fd 138argument to 139.Fn tcgetwinsize 140or 141.Fn tcsetwinsize 142does not represent a terminal device capable 143of remembering a window size. 144.El 145.Sh SEE ALSO 146.Xr stty 1 , 147.Xr pty 4 , 148.Xr termios 4 , 149.Xr tty 4 , 150.Xr signal 7 151.Sh STANDARDS 152The 153.Nm tcgetwinsize 154and 155.Nm tcsetwinsize 156functions will conform to 157.St -p1003.1 158issue 8, when it is published. 159.Pp 160The 161.Ic ws_xpixel 162and 163.Ic ws_ypixel 164fields are extensions to the standard. 165.Pp 166The standard only requires pseudo-terminals 167.Pq Xr pty 4 168to support these operations. 169In 170.Nx 171all terminal devices can set and recall a window size, 172regardless of whether any actual window exists. 173.Sh HISTORY 174The 175.Fn tcgetwinsize 176and 177.Fn tcsetwinsize 178functions were added in 179.Nx 8.0 180after specification by POSIX 181as more portable alternatives to ancient 182.Ic ioctl 183operations from 184.Bx 4.3 . 185.Sh CAVEATS 186It is unspecified whether calling the 187.Nm tcsetwinsize 188function causes the underlying terminal window to be resized. 189Nor is it specified whether altering the relationship between 190the character fields (ws_row and ws_col) and the pixel fields 191(ws_xpixel and ws_ypixel) causes the font size to change, or 192whether the application is required to maintain any specific 193relationship between these fields. 194In general, the 195.Nm tcsetwinsize 196function is best avoided except by applications responsible 197for actually implementing terminal windows. 198.Pp 199As the 200.Ic winsize 201structure may have more fields than documented, applications 202planning to call 203.Fn tcsetwinsize 204should call 205.Fn tcgetwinsize 206first with the same 207.Ar fd 208parameter, and use the result obtained in 209.Ar *gws 210to initialize the 211.Ic winsize 212structure to be used (after altering fields that are to be changed) 213as the 214.Ar sws 215operand of 216.Nm tcsetwinsize . 217