Differential D27787 Diff 81467 lib/libc/gen/tcgetwinsize.3

Changeset View

Standalone View

lib/libc/gen/tcgetwinsize.3

This file was added.

				.\"-
				.\" 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
				kibUnsubmitted Not Done Inline Actions .Vt and not .Fa I believe kib: .Vt and not .Fa I believe
				.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.
				kibUnsubmitted Not Done Inline Actions the .Dv SIGWINCH signal is sent ... kib: the .Dv SIGWINCH signal is sent ...
				.Pp
				The above declaration of
				.Vt "struct winsize"
				kibUnsubmitted Not Done Inline Actions I do not think this reference is useful, remove the sentence. kib: I do not think this reference is useful, remove the sentence.
				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:
				kibUnsubmitted Not Done Inline Actions This can be typesetted as .Rv -std kib: This can be typesetted as .Rv -std
				0.gangzta_gmail.comAuthorUnsubmitted Done Inline Actions Yes! Awesome! 0.gangzta_gmail.com: Yes! Awesome!
				.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.
				kibUnsubmitted Not Done Inline Actions Usually we note that some members are 'FreeBSD extensions' instead of saying that standard does not specify something. kib: Usually we note that some members are 'FreeBSD extensions' instead of saying that standard does…