aboutsummaryrefslogtreecommitdiff
path: root/lib/libc
diff options
context:
space:
mode:
authorKonstantin Belousov <kib@FreeBSD.org>2021-01-01 22:28:42 +0000
committerKonstantin Belousov <kib@FreeBSD.org>2021-01-02 02:43:32 +0000
commit4e0c81c5fafb5b72cabc342f640aff6cac445853 (patch)
tree73dfbe9f15f32fafc4ec3ed5bf3399d1f41dd11b /lib/libc
parent741d78126b5584e860811c78f87f51597e375592 (diff)
downloadsrc-4e0c81c5fafb5b72cabc342f640aff6cac445853.tar.gz
src-4e0c81c5fafb5b72cabc342f640aff6cac445853.zip
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
Diffstat (limited to 'lib/libc')
-rw-r--r--lib/libc/gen/Makefile.inc2
-rw-r--r--lib/libc/gen/tcgetwinsize.3164
2 files changed, 166 insertions, 0 deletions
diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc
index 76a21975f1ac..0ab717600e56 100644
--- a/lib/libc/gen/Makefile.inc
+++ b/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
diff --git a/lib/libc/gen/tcgetwinsize.3 b/lib/libc/gen/tcgetwinsize.3
new file mode 100644
index 000000000000..1bc96689c792
--- /dev/null
+++ b/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.