freebsd-dev/lib/libc/gen/tcsetattr.3

341 lines
8.9 KiB
Groff
Raw Normal View History

1994-05-27 05:00:24 +00:00
.\" Copyright (c) 1991, 1993
.\" 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. Neither the name of the University nor the names of its contributors
1994-05-27 05:00:24 +00:00
.\" 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 8.3 (Berkeley) 1/2/94
1999-08-28 00:22:10 +00:00
.\" $FreeBSD$
1994-05-27 05:00:24 +00:00
.\"
.Dd January 2, 1994
1994-05-27 05:00:24 +00:00
.Dt TCSETATTR 3
.Os
.Sh NAME
.Nm cfgetispeed ,
.Nm cfsetispeed ,
.Nm cfgetospeed ,
.Nm cfsetospeed ,
.Nm cfsetspeed ,
.Nm cfmakeraw ,
.Nm cfmakesane ,
1994-05-27 05:00:24 +00:00
.Nm tcgetattr ,
.Nm tcsetattr
.Nd manipulating the termios structure
.Sh LIBRARY
.Lb libc
1994-05-27 05:00:24 +00:00
.Sh SYNOPSIS
.In termios.h
1994-05-27 05:00:24 +00:00
.Ft speed_t
.Fn cfgetispeed "const struct termios *t"
1994-05-27 05:00:24 +00:00
.Ft int
.Fn cfsetispeed "struct termios *t" "speed_t speed"
.Ft speed_t
.Fn cfgetospeed "const struct termios *t"
1994-05-27 05:00:24 +00:00
.Ft int
.Fn cfsetospeed "struct termios *t" "speed_t speed"
.Ft int
.Fn cfsetspeed "struct termios *t" "speed_t speed"
.Ft void
.Fn cfmakeraw "struct termios *t"
.Ft void
.Fn cfmakesane "struct termios *t"
1994-05-27 05:00:24 +00:00
.Ft int
.Fn tcgetattr "int fd" "struct termios *t"
.Ft int
.Fn tcsetattr "int fd" "int action" "const struct termios *t"
1994-05-27 05:00:24 +00:00
.Sh DESCRIPTION
The
.Fn cfmakeraw ,
.Fn cfmakesane ,
.Fn tcgetattr
1994-05-27 05:00:24 +00:00
and
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
functions are provided for getting and setting the termios structure.
.Pp
The
.Fn cfgetispeed ,
.Fn cfsetispeed ,
.Fn cfgetospeed ,
.Fn cfsetospeed
1994-05-27 05:00:24 +00:00
and
.Fn cfsetspeed
1994-05-27 05:00:24 +00:00
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
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
function is called.
Certain values for baud rates set in the termios structure and passed to
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
have special meanings.
These are discussed in the portion of the manual page that describes the
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
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
2002-12-27 12:15:40 +00:00
is typedef'd in the include file
.In termios.h .
1994-05-27 05:00:24 +00:00
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
.Fn cfgetispeed
1994-05-27 05:00:24 +00:00
function returns the input baud rate in the termios structure referenced by
.Fa tp .
.Pp
The
.Fn cfsetispeed
1994-05-27 05:00:24 +00:00
function sets the input baud rate in the termios structure referenced by
.Fa tp
to
.Fa speed .
.Pp
The
.Fn cfgetospeed
1994-05-27 05:00:24 +00:00
function returns the output baud rate in the termios structure referenced by
.Fa tp .
.Pp
The
.Fn cfsetospeed
1994-05-27 05:00:24 +00:00
function sets the output baud rate in the termios structure referenced by
.Fa tp
to
.Fa speed .
.Pp
The
.Fn cfsetspeed
1994-05-27 05:00:24 +00:00
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
.Fn cfsetispeed ,
.Fn cfsetospeed ,
1994-05-27 05:00:24 +00:00
and
.Fn cfsetspeed
1994-05-27 05:00:24 +00:00
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
.Fn cfmakeraw
1994-05-27 05:00:24 +00:00
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 ,
while the
.Fn cfmakesane
function sets them to a state similar to those of a newly created
terminal device.
1994-05-27 05:00:24 +00:00
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
.Fn tcgetattr ,
setting raw or sane mode with
.Fn cfmakeraw
or
.Fn cfmakesane
1994-05-27 05:00:24 +00:00
and the subsequent
.Fn tcsetattr ,
1994-05-27 05:00:24 +00:00
and then using another
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
with the saved state to revert to the previous terminal state.
.Pp
The
.Fn tcgetattr
1994-05-27 05:00:24 +00:00
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
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
function sets the parameters associated with the terminal from the
termios structure referenced by
.Fa tp .
The
.Fa action
2002-12-19 09:40:28 +00:00
argument is created by
1994-05-27 05:00:24 +00:00
.Em or Ns 'ing
the following values, as specified in the include file
.In termios.h .
1994-05-27 05:00:24 +00:00
.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
.Va c_cflag ,
.Va c_ispeed ,
1994-05-27 05:00:24 +00:00
and
.Va c_ospeed
1994-05-27 05:00:24 +00:00
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
.Fn tcsetattr ,
1994-05-27 05:00:24 +00:00
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
.Fn tcsetattr ,
1994-05-27 05:00:24 +00:00
the input baud rate will be set to the same value as that specified by
the output baud rate.
.Pp
If
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
is unable 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
.Fn tcgetattr
1994-05-27 05:00:24 +00:00
and
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
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
.Fn tcgetattr
1994-05-27 05:00:24 +00:00
or
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
was not a valid file descriptor.
.It Bq Er EINTR
The
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
function was interrupted by a signal.
.It Bq Er EINVAL
The
.Fa action
argument to the
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
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
.Fn tcgetattr
1994-05-27 05:00:24 +00:00
or
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
is not a terminal.
.El
.Sh SEE ALSO
.Xr tcsendbreak 3 ,
.Xr termios 4
.Sh STANDARDS
The
.Fn cfgetispeed ,
.Fn cfsetispeed ,
.Fn cfgetospeed ,
.Fn cfsetospeed ,
.Fn tcgetattr
1994-05-27 05:00:24 +00:00
and
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
functions are expected to be compliant with the
.St -p1003.1-88
specification.
The
.Fn cfmakeraw ,
.Fn cfmakesane
1994-05-27 05:00:24 +00:00
and
.Fn cfsetspeed
1994-05-27 05:00:24 +00:00
functions,
as well as the
.Li TCSASOFT
option to the
.Fn tcsetattr
1994-05-27 05:00:24 +00:00
function are extensions to the
.St -p1003.1-88
specification.