tcgetwinsize(3): provide man page

The current POSIX.1-202x draft (1.1) was used as source material.

Submitted by:	Soumendra Ganguly <soumendraganguly@gmail.com>
MFC after:	2 weeks
Differential Revision:	https://reviews.freebsd.org/D27787

lib/libc/gen/Makefile.inc

@@ -302,6 +302,7 @@ MAN+=	alarm.3 \
 	syslog.3 \
 	tcgetpgrp.3 \
 	tcgetsid.3 \
+	tcgetwinsize.3 \
 	tcsendbreak.3 \
 	tcsetattr.3 \
 	tcsetpgrp.3 \
@@ -517,6 +518,7 @@ MLINKS+=syslog.3 closelog.3 \
 	syslog.3 openlog.3 \
 	syslog.3 setlogmask.3 \
 	syslog.3 vsyslog.3
+MLINKS+=tcgetwinsize.3 tcsetwinsize.3
 MLINKS+=tcsendbreak.3 tcdrain.3 \
 	tcsendbreak.3 tcflow.3 \
 	tcsendbreak.3 tcflush.3

lib/libc/gen/tcgetwinsize.3

@@ -0,0 +1,164 @@
+.\"-
+.\" Copyright (c) 2020 Soumendra Ganguly <soumendraganguly@gmail.com>
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
+.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
+.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" Portions of this text are reprinted and reproduced in electronic form
+.\" from P1003.1-202x, Draft 1.1, Draft Standard for Information Technology --
+.\" Portable Operating System Interface (POSIX), The Open Group Base
+.\" Specifications Issue 8, Copyright (C) 2020 by the Institute of
+.\" Electrical and Electronics Engineers, Inc and The Open Group. In the
+.\" event of any discrepancy between this version and the original IEEE and
+.\" The Open Group Standard, the original IEEE and The Open Group Standard is
+.\" the referee document. The original Standard can be obtained online at
+.\"	http://www.opengroup.org/unix/online.html.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd December 28, 2020
+.Dt TCGETWINSIZE 3
+.Os
+.Sh NAME
+.Nm tcgetwinsize ,
+.Nm tcsetwinsize
+.Nd get, set the size of a terminal window
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In termios.h
+.Bd -literal
+struct winsize {
+	unsigned short	ws_row;		/* number of rows, in characters */
+	unsigned short	ws_col;		/* number of columns, in characters */
+	unsigned short	ws_xpixel;	/* horizontal size, in pixels */
+	unsigned short	ws_ypixel;	/* vertical size, in pixels */
+};
+.Ed
+.Pp
+.Ft int
+.Fn tcgetwinsize "int fd" "struct winsize *w"
+.Ft int
+.Fn tcsetwinsize "int fd" "const struct winsize *w"
+.Sh DESCRIPTION
+The
+.Fn tcgetwinsize
+function gets the terminal window size of the terminal of which
+.Fa fd
+is an open file descriptor and stores it in the
+.Vt winsize
+structure of which
+.Fa w
+is a pointer.
+.Pp
+The
+.Fn tcsetwinsize
+function sets the terminal window size of the terminal of which
+.Fa fd
+is an open file descriptor from the
+.Vt winsize
+structure referenced by
+.Fa w .
+The change occurs immediately.
+If the terminal window size of the terminal
+is changed successfully to have a value that is different from the value that
+it had before the
+.Fn tcsetwinsize
+call, then the
+.Dv SIGWINCH
+signal is sent to all those members of the foreground process group of the
+terminal that have the terminal as their controlling terminal.
+.Pp
+The above declaration of
+.Vt "struct winsize"
+may not be literal.
+It is provided only to list the accessible members.
+Therefore, before calling
+.Fn tcsetwinsize ,
+the members of the
+.Vt winsize
+structure must be initialized by calling
+.Fn tcgetwinsize .
+The information in a
+.Vt winsize
+structure is stored by the kernel in order to provide a consistent interface,
+but it is not used by the kernel.
+.Sh RETURN VALUE
+.Rv -std tcgetwinsize tcsetwinsize
+The terminal window size remains unchanged if
+.Fn tcsetwinsize
+fails.
+.Pp
+.Sh ERRORS
+The following are the possible failure conditions:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa fd
+argument to
+.Fn tcgetwinsize
+or to
+.Fn tcsetwinsize
+is not a valid file descriptor.
+.It Bq Er ENOTTY
+The
+.Fa fd
+argument to
+.Fn tcgetwinsize
+or to
+.Fn tcsetwinsize
+is not associated with a character special device.
+.It Bq Er EINVAL
+The
+.Fa w
+argument to
+.Fn tcsetwinsize
+is not valid.
+.It Bq Er EFAULT
+The
+.Fa w
+argument to
+.Fn tcgetwinsize
+or to
+.Fn tcsetwinsize
+points outside the process's allocated address space.
+.El
+.Sh SEE ALSO
+.Xr stty 1 ,
+.Xr ioctl 2 ,
+.Xr sigaction 2 ,
+.Xr termios 4 ,
+.Xr tty 4
+.Sh STANDARDS
+The
+.Fn tcgetwinsize
+and
+.Fn tcsetwinsize
+functions are expected to conform to
+.St -p1003.1
+Base Specifications, Issue 8.
+The
+.Fa ws_xpixel
+and
+.Fa ws_ypixel
+members of
+.Vt "struct winsize"
+are FreeBSD extensions.

share/man/man4/termios.4

@@ -1590,6 +1590,7 @@ the values in the header
 .Sh SEE ALSO
 .Xr stty 1 ,
 .Xr tcgetsid 3 ,
+.Xr tcgetwinsize 3,
 .Xr tcsendbreak 3 ,
 .Xr tcsetattr 3 ,
 .Xr tcsetsid 3 ,