'\"macro stdmacro
.if n .pH g2.termios @(#)termios	40.15 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} termios 2 "" "\&"
.if \nX=1 .ds x} termios 2 ""
.if \nX=2 .ds x} termios 2 "" "\&"
.if \nX=3 .ds x} termios "" "" "\&"
.TH \*(x}
.SH NAME
\f4termios\f1: \f4tcgetattr\f1, \f4tcsetattr\f1, \f4tcsendbreak\f1, \f4tcdrain\f1, \f4tcflush\f1, \f4tcflow\f1, \f4cfgetospeed\f1, \f4cfgetispeed\f1, \f4cfsetispeed\f1, \f4cfsetospeed\f1, \f4tcgetpgrp\f1, \f4tcsetpgrp\f1, \f4tcgetsid\f1 \- general terminal interface
.SH SYNOPSIS
.nf
.ft4
#include <termios.h>
.sp .5
int tcgetattr(int fildes, struct termios *termios_p);
.sp .5
int tcsetattr(int fildes, int optional_actions,
	const struct termios *termios_p);
.sp .5
int tcsendbreak(int fildes, int duration);
.sp .5
int tcdrain(int fildes);
.sp .5
int tcflush(int fildes, int queue_selector);
.sp .5
int tcflow(int fildes, int action);
.sp .5
speed_t cfgetospeed(struct termios *termios_p);
.sp .5
int cfsetospeed(const struct termios *termios_p, speed_t speed);
.sp .5
speed_t cfgetispeed(struct termios *termios_p);
.sp .5
int cfsetispeed(const struct termios *termios_p, speed_t speed);
.sp .5
#include <sys/types.h>
.br
#include <termios.h>
.sp .5
pid_t tcgetpgrp(int fildes);
.sp .5
int tcsetpgrp(int fildes, pid_t pgid);
.sp .5
pid_t tcgetsid(int fildes);
.ft1
.fi
.SH DESCRIPTION
These functions describe a general terminal interface
for controlling asynchronous communications ports.
A more detailed overview of the terminal interface can be found in
\f4termio\fP(7), which also describes an
\f4ioctl\fP(2) interface that provides the same functionality.
However, the function interface described here is the preferred user interface.
.PP
Many of the functions described here have a
\f2termios_p\f1 argument that is a pointer to a
\f4termios\f1 structure.
This structure contains the following members:
.PP
.RS
.nf
.ft 4
tcflag_t   c_iflag;        /* input modes */
tcflag_t   c_oflag;        /* output modes */
tcflag_t   c_cflag;        /* control modes */
tcflag_t   c_lflag;        /* local modes */
cc_t       c_cc[NCCS];     /* control chars */
.ft 1
.fi
.RE
.PP
These structure members are described in detail in
\f4termio\f2(7).
.SS "Get and Set Terminal Attributes"
The \f4tcgetattr\fP function gets the parameters associated with the
object referred by \f2fildes\f1 and stores them in the \f4termios\fP structure
referenced by \f2termios_p\f1.
This function may be invoked from a background
process; however, the terminal attributes may be subsequently changed by a
foreground process.
.PP
The \f4tcsetattr\fP function sets the parameters associated with the
terminal (unless support is required from the underlying hardware that is
not available) from the \f4termios\fP structure
referenced by \f2termios_p\f1
as follows:
.RS
.P
If \f2optional_actions\f1 is \f4TCSANOW\fP, the change occurs immediately.
.P
If \f2optional_actions\f1 is \f4TCSADRAIN\fP,
the change occurs after all output
written to \f2fildes\f1 has been transmitted.
This function should be used 
when changing parameters that affect output.
.P
If \f2optional_actions\f1 is \f4TCSAFLUSH\fP,
the change occurs after all output
written to the object referred by \f2fildes\f1 has been transmitted, and all
input that has been received but not read is discarded before the change
is made.
.RE
.PP
The symbolic constants for the values of \f2optional_actions\f1 are defined
in
\f4<termios.h>\f1.
.SS "Line Control"
If the terminal is using asynchronous serial data transmission, the
\f4tcsendbreak\fP function causes transmission of a continuous stream
of zero-valued bits for a specific duration.
If \f2duration\f1 is zero, it
causes transmission of zero-valued bits for at least 0.25 seconds, and
not more than 0.5 seconds.
If \f2duration\f1 is not zero, it behaves
in a way similar to \f4tcdrain\fP.
.PP
If the terminal is not using asynchronous serial data transmission, 
the \f4tcsendbreak\fP function sends data to 
generate a break condition or returns without taking any action.
.PP
The \f4tcdrain\fP function waits until all output written to the object
referred to by \f2fildes\f1 has been transmitted.
.PP
The \f4tcflush\fP function discards data written to the object referred
to by \f2fildes\f1 but not transmitted, or data received but not read,
depending on the value of \f2queue_selector\f1:
.RS
.P
If \f2queue_selector\f1 is \f4TCIFLUSH\fP,
it flushes data received but not
read.
.P
If \f2queue_selector\f1 is \f4TCOFLUSH\fP,
it flushes data written but not
transmitted.
.P
If \f2queue_selector\f1 is \f4TCIOFLUSH\fP, it flushes both data received but
not read, and data written but not transmitted.
.RE
.PP
The \f4tcflow\fP function suspends transmission or reception of data on
the object referred to by \f2fildes\f1, depending on the value of \f2action\f1:
.RS
.P
If \f2action\f1 is \f4TCOOFF\fP, it suspends output.
.P
If \f2action\f1 is \f4TCOON\fP, it restarts suspended output.
.P
If \f2action\f1 if \f4TCIOFF\fP,
the system transmits a
.SM STOP
character, which causes the terminal device to stop transmitting data to the system.
.P
If \f2action\f1 is \f4TCION\fP,
the system transmits a
.SM START
character, which causes the terminal device to start transmitting data to the system.
.RE
.SS "Get and Set Baud Rate"
The baud rate functions get and set the values
of the input and output baud rates in the \f4termios\fP structure.
The effects
on the terminal device described below do not become effective until the
\f4tcsetattr\fP function is successfully called.
.PP
The input and output baud rates are stored in the \f4termios\fP structure.
The values shown in the table are supported.
The names in this table
are defined in \f4<termios.h\f1>.
.TS
center, tab(:);
c c c c c
lf4 r r lf4 r.
Name:Description::Name:Description
_
B0:Hang up::B600:600 baud
B50:50 baud::B1200:1200 baud
B75:75 baud::B1800:1800 baud
B110:110 baud::B2400:2400 baud
B134:134.5 baud::B4800:4800 baud
B150:150 baud::B9600:9600 baud
B200:200 baud::B19200:19200 baud
B300:300 baud::B38400:38400 baud
.TE
.PP
\f4cfgetospeed\fP gets the output baud rate and stores it in the \f4termios\fP
structure pointed to by \f2termios_p.\f1
.PP
\f4cfsetospeed\fP sets the output baud rate stored in the \f4termios\fP 
structure pointed to by \f2termios_p\f1 to \f2speed\f1.
The zero baud rate,
\f4B0\fP, is used to terminate the connection.
If \f4B0\fP is specified, the modem
control lines are no longer be asserted.
Normally, this disconnects the line.
.PP
\f4cfgetispeed\fP gets the input baud rate and stores it in the \f4termios\fP
structure pointed to by \f2termios_p\f1.
.PP
\f4cfsetispeed\fP sets the input baud rate stored in the \f4termios\fP
structure pointed to by \f2termios_p\f1
to \f2speed\f1.
If the input baud rate is set to zero, the
input baud rate is specified by the value of the output baud rate.
Both \f4cfsetispeed\fP and \f4cfsetospeed\f1 return a value of zero if
successful and \-1 to indicate an error.
Attempts to set unsupported baud rates are ignored.
This refers both to changes to baud rates not
supported by the hardware, and to changes setting the input and output
baud rates to different values if the hardware does not support this.
.SS "Get and Set Terminal Foreground Process Group \s-1ID\s+1"
\f4tcsetpgrp\fP
sets the foreground process group
.SM ID
of the terminal specified by
\f2fildes\f1
to
\f2pgid\f1.
The file associated with \f2fildes\fP must be the controlling terminal of
the calling process and the controlling terminal must be currently
associated with the session of the calling process. \f2pgid\fP must
match a process group
.SM ID
of a process in the same session as the calling
process.
.PP
\f4tcgetpgrp\fP returns the foreground process group
.SM ID
of the terminal
specified by \f2fildes\f1.
\f4tcgetpgrp\f1 is allowed from a process that is a member of a background
process group; however, the information may be subsequently changed by a
process that is a member of a foreground process group.
.SS "Get Terminal Session \s-1ID\s+1"
\f4tcgetsid\f1
returns the session
.SM ID
of the terminal specified by
\f2fildes\f1.
.SH DIAGNOSTICS 
On success,
\f4tcgetpgrp\^\f1
returns the process group
.SM ID
of the foreground process group associated with the specified terminal.
Otherwise, it returns \-1 and sets
\f4errno\f1
to indicate the error.
.PP
On success,
\f4tcgetsid\f1
returns the session
.SM ID
associated with the specified terminal.
Otherwise, it returns \-1 and sets
\f4errno\f1
to indicate the error.
.PP
On success, all other functions return
a value of 0\f1.
Otherwise, they return \-1 and set
\f4errno\f1
to indicate the error.
.PP
All of the functions fail if one of more of the following is true:
.TP 15
\f4EBADF\f1
The \f2fildes\f1 argument is not a valid file descriptor.
.TP
\f4ENOTTY\f1
The file associated with \f2fildes\f1 is not a terminal.
.PP
\f4tcsetattr\fP also fails if the following is true:
.TP 15
\f4EINVAL\f1
The \f2optional_actions\f1 argument is not a proper value, or an
attempt was made to change an attribute represented in the \f4termios\fP
structure to an unsupported value.
.PP
\f4tcsendbreak\fP also fails if the following is true:
.TP 15
\f4EINVAL\f1
The device does not support the \f4tcsendbreak\fP function.
.PP
\f4tcdrain\fP also fails if one or more of the following is true:
.TP 15
\f4EINTR\f1
A signal interrupted the \f4tcdrain\fP function.
.TP
\f4EINVAL\f1
The device does not support the \f4tcdrain\fP function.
.PP
\f4tcflush\f1 also fails if the following is true:
.TP 15
\f4EINVAL\f1
The device does not support the \f4tcflush\fP function or the 
\f2queue_selector\f1 argument is not a proper value.
.PP
\f4tcflow\fP also fails if the following is true:
.TP 15
\f4EINVAL\f1
The device does not support the \f4tcflow\fP function or the \f2action\f1
argument is not a proper value.
.PP
\f4tcgetpgrp\fP also fails if the following is true:
.TP 15
\f4ENOTTY\f1
the calling process does not have a controlling terminal, or \f2fildes\fP
does not refer to the controlling terminal.
.PP
\f4tcsetpgrp\fP also fails if the following is true:
.TP 15
\f4EINVAL\fP
\f2pgid\f1 is not a valid process group
.SM ID .
.TP 15
\f4ENOTTY\f1
the calling process does not have a controlling terminal, or \f2fildes\fP
does not refer to the controlling terminal, or the controlling terminal
is no longer associated with the session of the calling process.
.TP 15
\f4EPERM\f1
\f2pgid\f1
does not match the process group 
of an existing process in the same session as the calling process.
.PP
\f4tcgetsid\f1 also fails if the following is true:
.TP 15
\f4EACCES
\f2fildes\f1
is a terminal that is not allocated to a session.
.SH SEE ALSO
\f4setsid\fP(2), \f4setpgid\fP(2).
.sp .2
\f4termio\fP(7) in the \f2System Administrator's Reference Manual\f1.
