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
This commit is contained in:
parent
741d78126b
commit
4e0c81c5fa
@ -302,6 +302,7 @@ MAN+= alarm.3 \
|
|||||||
syslog.3 \
|
syslog.3 \
|
||||||
tcgetpgrp.3 \
|
tcgetpgrp.3 \
|
||||||
tcgetsid.3 \
|
tcgetsid.3 \
|
||||||
|
tcgetwinsize.3 \
|
||||||
tcsendbreak.3 \
|
tcsendbreak.3 \
|
||||||
tcsetattr.3 \
|
tcsetattr.3 \
|
||||||
tcsetpgrp.3 \
|
tcsetpgrp.3 \
|
||||||
@ -517,6 +518,7 @@ MLINKS+=syslog.3 closelog.3 \
|
|||||||
syslog.3 openlog.3 \
|
syslog.3 openlog.3 \
|
||||||
syslog.3 setlogmask.3 \
|
syslog.3 setlogmask.3 \
|
||||||
syslog.3 vsyslog.3
|
syslog.3 vsyslog.3
|
||||||
|
MLINKS+=tcgetwinsize.3 tcsetwinsize.3
|
||||||
MLINKS+=tcsendbreak.3 tcdrain.3 \
|
MLINKS+=tcsendbreak.3 tcdrain.3 \
|
||||||
tcsendbreak.3 tcflow.3 \
|
tcsendbreak.3 tcflow.3 \
|
||||||
tcsendbreak.3 tcflush.3
|
tcsendbreak.3 tcflush.3
|
||||||
|
164
lib/libc/gen/tcgetwinsize.3
Normal file
164
lib/libc/gen/tcgetwinsize.3
Normal file
@ -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.
|
@ -1590,6 +1590,7 @@ the values in the header
|
|||||||
.Sh SEE ALSO
|
.Sh SEE ALSO
|
||||||
.Xr stty 1 ,
|
.Xr stty 1 ,
|
||||||
.Xr tcgetsid 3 ,
|
.Xr tcgetsid 3 ,
|
||||||
|
.Xr tcgetwinsize 3,
|
||||||
.Xr tcsendbreak 3 ,
|
.Xr tcsendbreak 3 ,
|
||||||
.Xr tcsetattr 3 ,
|
.Xr tcsetattr 3 ,
|
||||||
.Xr tcsetsid 3 ,
|
.Xr tcsetsid 3 ,
|
||||||
|
Loading…
Reference in New Issue
Block a user