lib/libc/gen/tcgetwinsize.3

   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
  49 struct 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
  62 The
  63 .Fn tcgetwinsize
  64 function gets the terminal window size of the terminal of which
  65 .Fa fd
  66 is an open file descriptor and stores it in the
  67 .Vt winsize
  68 structure of which
  69 .Fa w
  70 is a pointer.
  71 .Pp
  72 The
  73 .Fn tcsetwinsize
  74 function sets the terminal window size of the terminal of which
  75 .Fa fd
  76 is an open file descriptor from the
  77 .Vt winsize
  78 structure referenced by
  79 .Fa w .
  80 The change occurs immediately.
  81 If the terminal window size of the terminal
  82 is changed successfully to have a value that is different from the value that
  83 it had before the
  84 .Fn tcsetwinsize
  85 call, then the
  86 .Dv SIGWINCH
  87 signal is sent to all those members of the foreground process group of the
  88 terminal that have the terminal as their controlling terminal.
  89 .Pp
  90 The above declaration of
  91 .Vt "struct winsize"
  92 may not be literal.
  93 It is provided only to list the accessible members.
  94 Therefore, before calling
  95 .Fn tcsetwinsize ,
  96 the members of the
  97 .Vt winsize
  98 structure must be initialized by calling
  99 .Fn tcgetwinsize .
 100 The information in a
 101 .Vt winsize
 102 structure is stored by the kernel in order to provide a consistent interface,
 103 but it is not used by the kernel.
 104 .Sh RETURN VALUE
 105 .Rv -std tcgetwinsize tcsetwinsize
 106 The terminal window size remains unchanged if
 107 .Fn tcsetwinsize
 108 fails.
 109 .Pp
 110 .Sh ERRORS
 111 The following are the possible failure conditions:
 112 .Bl -tag -width Er
 113 .It Bq Er EBADF
 114 The
 115 .Fa fd
 116 argument to
 117 .Fn tcgetwinsize
 118 or to
 119 .Fn tcsetwinsize
 120 is not a valid file descriptor.
 121 .It Bq Er ENOTTY
 122 The
 123 .Fa fd
 124 argument to
 125 .Fn tcgetwinsize
 126 or to
 127 .Fn tcsetwinsize
 128 is not associated with a character special device.
 129 .It Bq Er EINVAL
 130 The
 131 .Fa w
 132 argument to
 133 .Fn tcsetwinsize
 134 is not valid.
 135 .It Bq Er EFAULT
 136 The
 137 .Fa w
 138 argument to
 139 .Fn tcgetwinsize
 140 or to
 141 .Fn tcsetwinsize
 142 points 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
 151 The
 152 .Fn tcgetwinsize
 153 and
 154 .Fn tcsetwinsize
 155 functions are expected to conform to
 156 .St -p1003.1
 157 Base Specifications, Issue 8.
 158 The
 159 .Fa ws_xpixel
 160 and
 161 .Fa ws_ypixel
 162 members of
 163 .Vt "struct winsize"
 164 are FreeBSD extensions.