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