From ca073b5fd0ab317ca0499e99493f33393cbb3d84 Mon Sep 17 00:00:00 2001 From: glass Date: Sun, 25 Jul 1993 23:05:00 +0000 Subject: [PATCH] adding man pages for termios support functions --- lib/libc/gen/tcgetpgrp.3 | 79 +++++++++ lib/libc/gen/tcsendbreak.3 | 154 +++++++++++++++++ lib/libc/gen/tcsetattr.3 | 330 +++++++++++++++++++++++++++++++++++++ lib/libc/gen/tcsetpgrp.3 | 100 +++++++++++ 4 files changed, 663 insertions(+) create mode 100644 lib/libc/gen/tcgetpgrp.3 create mode 100644 lib/libc/gen/tcsendbreak.3 create mode 100644 lib/libc/gen/tcsetattr.3 create mode 100644 lib/libc/gen/tcsetpgrp.3 diff --git a/lib/libc/gen/tcgetpgrp.3 b/lib/libc/gen/tcgetpgrp.3 new file mode 100644 index 000000000000..03396104caf6 --- /dev/null +++ b/lib/libc/gen/tcgetpgrp.3 @@ -0,0 +1,79 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. +.\" +.\" @(#)tcgetpgrp.3 5.3 (Berkeley) 3/29/92 +.\" +.Dd "March 29, 1992" +.Dt TCGETPGRP 3 +.Os +.Sh NAME +.Nm tcgetpgrp +.Nd get foreground process group ID +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Ft pid_t +.Fn tcgetpgrp "int fd" +.Sh DESCRIPTION +The +.Nm tcgetpgrp +function returns the value of the process group ID of the foreground +process group associated with the terminal device. +If there is no foreground process group, +.Nm tcgetpgrp +returns an invalid process ID. +.Sh ERRORS +If an error occurs, +.Nm tcgetpgrp +returns -1 and the global variable +.Va errno +is set to indicate the error, as follows: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er ENOTTY +The calling process does not have a controlling terminal or the +underlying terminal device represented by +.Fa fd +is not the controlling terminal. +.El +.Sh SEE ALSO +.Xr setpgid 3 , +.Xr setsid 2 , +.Xr tcsetpgrp 3 +.Sh STANDARDS +The +.Nm tcgetpgrp +function is expected to be compliant with the +.St -p1003.1-88 +specification. diff --git a/lib/libc/gen/tcsendbreak.3 b/lib/libc/gen/tcsendbreak.3 new file mode 100644 index 000000000000..99d7d4588757 --- /dev/null +++ b/lib/libc/gen/tcsendbreak.3 @@ -0,0 +1,154 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. +.\" +.\" @(#)tcsendbreak.3 5.3 (Berkeley) 3/4/92 +.\" +.Dd "March 4, 1992" +.Dt TCSENDBREAK 3 +.Os +.Sh NAME +.Nm tcsendbreak , +.Nm tcdrain , +.Nm tcflush , +.Nm tcflow +.Nd line control functions +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn tcdrain "int fd" +.Ft int +.Fn tcflow "int fd" "int action" +.Ft int +.Fn tcflush "int fd" "int action" +.Ft int +.Fn tcsendbreak "int fd" "int len" +.Sh DESCRIPTION +The +.Nm tcdrain +function waits until all output written to the terminal referenced by +.Fa fd +has been transmitted to the terminal. +.Pp +The +.Nm tcflow +function suspends transmission of data to or the reception of data from +the terminal referenced by +.Fa fd +depending on the value of +.Fa action . +The value of +.Fa action +must be one of the following: +.Bl -tag -width "TCIOFF" +.It Fa TCOOFF +Suspend output. +.It Fa TCOON +Restart suspended output. +.It Fa TCIOFF +Transmit a STOP character, which is intended to cause the terminal to stop +transmitting data to the system. +(See the description of IXOFF in the +.Ql Input Modes +section of +.Xr termios 4 ). +.It Fa TCION +Transmit a START character, which is intended to cause the terminal to start +transmitting data to the system. +(See the description of IXOFF in the +.Ql Input Modes +section of +.Xr termios 4 ). +.El +.Pp +The +.Nm tcflush +function discards any data written to the terminal referenced by +.Fa fd +which has not been transmitted to the terminal, or any data received +from the terminal but not yet read, depending on the value of +.Fa action . +The value of +.Fa action +must be one of the following: +.Bl -tag -width "TCIOFLUSH" +.It Fa TCIFLUSH +Flush data received but not read. +.It Fa TCOFLUSH +Flush data written but not transmitted. +.It Fa TCIOFLUSH +Flush both data received but not read and data written but not transmitted. +.El +.Pp +The +.Nm tcsendbreak +function transmits a continuous stream of zero-valued bits for four-tenths +of a second to the terminal referenced by +.Fa fd . +The +.Fa len +parameter is ignored in this implementation. +.Sh RETURN VALUES +Upon successful completion, all of these functions return a value of zero. +.Sh ERRORS +If any error occurs, a value of -1 is returned and the global variable +.Va errno +is set to indicate the error, as follows: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er EINVAL +The +.Fa action +argument is not a proper value. +.It Bq Er ENOTTY +The file associated with +.Fa fd +is not a terminal. +.It Bq Er EINTR +A signal interrupted the +.Nm tcdrain +function. +.El +.Sh SEE ALSO +.Xr tcsetattr 3 , +.Xr termios 4 +.Sh STANDARDS +The +.Nm tcsendbreak , +.Nm tcdrain , +.Nm tcflush +and +.Nm tcflow +functions are expected to be compliant with the +.St -p1003.1-88 +specification. diff --git a/lib/libc/gen/tcsetattr.3 b/lib/libc/gen/tcsetattr.3 new file mode 100644 index 000000000000..b206beec6b91 --- /dev/null +++ b/lib/libc/gen/tcsetattr.3 @@ -0,0 +1,330 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. +.\" +.\" @(#)tcsetattr.3 5.2 (Berkeley) 3/4/92 +.\" +.Dd "March 4, 1992" +.Dt TCSETATTR 3 +.Os +.Sh NAME +.Nm cfgetispeed , +.Nm cfsetispeed , +.Nm cfgetospeed , +.Nm cfsetospeed , +.Nm cfsetspeed , +.Nm cfmakeraw , +.Nm tcgetattr , +.Nm tcsetattr +.Nd manipulating the termios structure +.Sh SYNOPSIS +.Fd #include +.Ft speed_t +.Fn cfgetispeed "struct termios *t" +.Ft int +.Fn cfsetispeed "struct termios *t" "speed_t speed" +.Ft speed_t +.Fn cfgetospeed "struct termios *t" +.Ft int +.Fn cfsetospeed "struct termios *t" "speed_t speed" +.Ft void +.Fn cfsetspeed "struct termios *t" "speed_t speed" +.Ft void +.Fn cfmakeraw "struct termios *t" +.Ft int +.Fn tcgetattr "int fd" "struct termios *t" +.Ft int +.Fn tcsetattr "int fd" "int action" "struct termios *t" +.Sh DESCRIPTION +The +.Nm cfmakeraw , +.Nm tcgetattr +and +.Nm tcsetattr +functions are provided for getting and setting the termios structure. +.Pp +The +.Nm cfgetispeed , +.Nm cfsetispeed , +.Nm cfgetospeed , +.Nm cfsetospeed +and +.Nm cfsetspeed +functions are provided for getting and setting the baud rate values in +the termios structure. +The effects of the functions on the terminal as described below +do not become effective, nor are all errors detected, until the +.Nm tcsetattr +function is called. +Certain values for baud rates set in the termios structure and passed to +.Nm tcsetattr +have special meanings. +These are discussed in the portion of the manual page that describes the +.Nm tcsetattr +function. +.Sh GETTING AND SETTING THE BAUD RATE +The input and output baud rates are found in the termios structure. +The unsigned integer +.Li speed_t +is typdef'd in the include file +.Aq Pa termios.h . +The value of the integer corresponds directly to the baud rate being +represented, however, the following symbolic values are defined. +.Bd -literal +#define B0 0 +#define B50 50 +#define B75 75 +#define B110 110 +#define B134 134 +#define B150 150 +#define B200 200 +#define B300 300 +#define B600 600 +#define B1200 1200 +#define B1800 1800 +#define B2400 2400 +#define B4800 4800 +#define B9600 9600 +#define B19200 19200 +#define B38400 38400 +#ifndef _POSIX_SOURCE +#define EXTA 19200 +#define EXTB 38400 +#endif /*_POSIX_SOURCE */ +.Ed +.Pp +The +.Nm cfgetispeed +function returns the input baud rate in the termios structure referenced by +.Fa tp . +.Pp +The +.Nm cfsetispeed +function sets the input baud rate in the termios structure referenced by +.Fa tp +to +.Fa speed . +.Pp +The +.Nm cfgetospeed +function returns the output baud rate in the termios structure referenced by +.Fa tp . +.Pp +The +.Nm cfsetospeed +function sets the output baud rate in the termios structure referenced by +.Fa tp +to +.Fa speed . +.Pp +The +.Nm cfsetspeed +function sets both the input and output baud rate in the termios structure +referenced by +.Fa tp +to +.Fa speed . +.Pp +Upon successful completion, the functions +.Nm cfsetispeed , +.Nm cfsetospeed , +and +.Nm cfsetspeed +return a value of 0. +Otherwise, a value of -1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh GETTING AND SETTING THE TERMIOS STATE +This section describes the functions that are used to control the general +terminal interface. +Unless otherwise noted for a specific command, these functions are restricted +from use by background processes. +Attempts to perform these operations shall cause the process group to be sent +a SIGTTOU signal. +If the calling process is blocking or ignoring SIGTTOU signals, the process +is allowed to perform the operation and the SIGTTOU signal is not sent. +.Pp +In all the functions, although +.Fa fd +is an open file descriptor, the functions affect the underlying terminal +file, not just the open file description associated with the particular +file descriptor. +.Pp +The +.Nm cfmakeraw +function sets the flags stored in the termios structure to a state disabling +all input and output processing, giving a +.Dq raw I/O path. +It should be noted that there is no function to reverse this effect. +This is because there are a variety of processing options that could be +re-enabled and the correct method is for an application to snapshot the +current terminal state using the function +.Nm tcgetattr , +setting raw mode with +.Nm cfmakeraw +and the subsequent +.Nm tcsetattr , +and then using another +.Nm tcsetattr +with the saved state to revert to the previous terminal state. +.Pp +The +.Nm tcgetattr +function copies the parameters associated with the terminal referenced +by +.Fa fd +in the termios structure referenced by +.Fa tp . +This function is allowed from a background process, however, the terminal +attributes may be subsequently changed by a foreground process. +.Pp +The +.Nm tcsetattr +function sets the parameters associated with the terminal from the +termios structure referenced by +.Fa tp . +The +.Fa action +field is created by +.Em or Ns 'ing +the following values, as specified in the include file +.Aq Pa termios.h . +.Bl -tag -width "TCSADRAIN" +.It Fa TCSANOW +The change occurs immediately. +.It Fa TCSADRAIN +The change occurs after all output written to +.Fa fd +has been transmitted to the terminal. +This value of +.Fa action +should be used when changing parameters that affect output. +.It Fa TCSAFLUSH +The change occurs after all output written to +.Fa fd +has been transmitted to the terminal +Additionally, any input that has been received but not read is discarded. +.It Fa TCSASOFT +If this value is +.Em or Ns 'ed +into the +.Fa action +value, the values of the +.Em c_cflag , +.Em c_ispeed , +and +.Em c_ospeed +fields are ignored. +.El +.Pp +The 0 baud rate is used to terminate the connection. +If 0 is specified as the output speed to the function +.Nm tcsetattr , +modem control will no longer be asserted on the terminal, disconnecting +the terminal. +.Pp +If zero is specified as the input speed to the function +.Nm tcsetattr , +the input baud rate will be set to the same value as that specified by +the output baud rate. +.Pp +If +.Nm tcsetattr +is unable able to make any of the requested changes, it returns -1 and +sets errno. +Otherwise, it makes all of the requested changes it can. +If the specified input and output baud rates differ and are a combination +that is not supported, neither baud rate is changed. +.Pp +Upon successful completion, the functions +.Nm tcgetattr +and +.Nm tcsetattr +return a value of 0. +Otherwise, they +return -1 and the global variable +.Va errno +is set to indicate the error, as follows: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument to +.Nm tcgetattr +or +.Nm tcsetattr +was not a valid file descriptor. +.It Bq Er EINTR +The +.Nm tcsetattr +function was interrupted by a signal. +.It Bq Er EINVAL +The +.Fa action +argument to the +.Nm tcsetattr +function was not valid, or an attempt was made to change an attribute +represented in the termios structure to an unsupported value. +.It Bq Er ENOTTY +The file associated with the +.Fa fd +argument to +.Nm tcgetattr +or +.Nm tcsetattr +is not a terminal. +.El +.Sh SEE ALSO +.Xr tcsendbreak 3 , +.Xr termios 4 +.Sh STANDARDS +The +.Nm cfgetispeed , +.Nm cfsetispeed , +.Nm cfgetospeed , +.Nm cfsetospeed , +.Nm tcgetattr +and +.Nm tcsetattr +functions are expected to be compliant with the +.St -p1003.1-88 +specification. +The +.Nm cfmakeraw +and +.Nm cfsetspeed +functions, +as well as the +.Li TCSASOFT +option to the +.Nm tcsetattr +function are extensions to the +.St -p1003.1-88 +specification. diff --git a/lib/libc/gen/tcsetpgrp.3 b/lib/libc/gen/tcsetpgrp.3 new file mode 100644 index 000000000000..ff881cb437d8 --- /dev/null +++ b/lib/libc/gen/tcsetpgrp.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" 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. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. +.\" +.\" @(#)tcsetpgrp.3 5.3 (Berkeley) 3/29/92 +.\" +.Dd "March 29, 1992" +.Dt TCSETPGRP +.Os +.Sh NAME +.Nm tcsetpgrp +.Nd set foreground process group ID +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Ft int +.Fn tcsetpgrp "int fd" "pid_t pgrp_id" +.Sh DESCRIPTION +If the process has a controlling terminal, the +.Nm tcsetpgrp +function sets the foreground process group ID associated with the +terminal device to +.Fa pgrp_id . +The terminal device associated with +.Fa fd +must be the controlling terminal of the calling process and the +controlling terminal must be currently associated with the session +of the calling process. +The value of +.Fa pgrp_id +must be the same as the process group ID of a process in the same +session as the calling process. +.Pp +Upon successful completion, +.Nm tcsetpgrp +returns a value of zero. +.Sh ERRORS +If an error occurs, +.Nm tcgetpgrp +returns -1 and the global variable +.Va errno +is set to indicate the error, as follows: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa fd +argument is not a valid file descriptor. +.It Bq Er EINVAL +An invalid value of +.Fa pgrp_id +was specified. +.It Bq Er ENOTTY +The calling process does not have a controlling terminal, or the file +represented by +.Fa fd +is not the controlling terminal, or the controlling terminal is no +longer associated with the session of the calling process. +.It Bq Er EPERM +The +.Fa pgrp_id +argument does not match the process group ID of a process in the same +session as the calling process. +.El +.Sh SEE ALSO +.Xr setpgid 3 , +.Xr setsid 2 , +.Xr tcgetpgrp 3 +.Sh STANDARDS +The +.Nm tcsetpgprp +function is expected to be compliant with the +.St -p1003.1-88 +specification.