Date: Sat, 16 Jan 2021 06:41:44 GMT From: Konstantin Belousov <kib@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org Subject: git: 8af3b2026a8e - stable/12 - tcgetwinsize(3): provide man page Message-ID: <202101160641.10G6finf086788@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch stable/12 has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=8af3b2026a8eafba9f22d823c30900b019b813fe commit 8af3b2026a8eafba9f22d823c30900b019b813fe Author: Konstantin Belousov <kib@FreeBSD.org> AuthorDate: 2021-01-01 22:28:42 +0000 Commit: Konstantin Belousov <kib@FreeBSD.org> CommitDate: 2021-01-16 06:39:15 +0000 tcgetwinsize(3): provide man page (cherry picked from commit 4e0c81c5fafb5b72cabc342f640aff6cac445853) --- lib/libc/gen/Makefile.inc | 2 + lib/libc/gen/tcgetwinsize.3 | 164 ++++++++++++++++++++++++++++++++++++++++++++ share/man/man4/termios.4 | 1 + 3 files changed, 167 insertions(+) diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc index 264b079b9ed0..5431ea33f7c3 100644 --- a/lib/libc/gen/Makefile.inc +++ b/lib/libc/gen/Makefile.inc @@ -301,6 +301,7 @@ MAN+= alarm.3 \ syslog.3 \ tcgetpgrp.3 \ tcgetsid.3 \ + tcgetwinsize.3 \ tcsendbreak.3 \ tcsetattr.3 \ tcsetpgrp.3 \ @@ -516,6 +517,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. diff --git a/share/man/man4/termios.4 b/share/man/man4/termios.4 index a08abfa12c66..81d76aa873fd 100644 --- a/share/man/man4/termios.4 +++ b/share/man/man4/termios.4 @@ -1575,6 +1575,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 ,
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202101160641.10G6finf086788>