|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH TCSETATTR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
tcsetattr
|
|
Packit |
7cfc04 |
\(em set the parameters associated with the terminal
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
#include <termios.h>
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
int tcsetattr(int \fIfildes\fP, int \fIoptional_actions\fP,
|
|
Packit |
7cfc04 |
const struct termios *\fItermios_p\fP);
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fItcsetattr\fR()
|
|
Packit |
7cfc04 |
function shall set the parameters associated with the terminal referred
|
|
Packit |
7cfc04 |
to by the open file descriptor
|
|
Packit |
7cfc04 |
.IR fildes
|
|
Packit |
7cfc04 |
(an open file descriptor associated with a terminal) from the
|
|
Packit |
7cfc04 |
.BR termios
|
|
Packit |
7cfc04 |
structure referenced by
|
|
Packit |
7cfc04 |
.IR termios_p
|
|
Packit |
7cfc04 |
as follows:
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.IR optional_actions
|
|
Packit |
7cfc04 |
is TCSANOW, the change shall occur immediately.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.IR optional_actions
|
|
Packit |
7cfc04 |
is TCSADRAIN, the change shall occur after all output written to
|
|
Packit |
7cfc04 |
.IR fildes
|
|
Packit |
7cfc04 |
is transmitted. This function should be used when changing parameters
|
|
Packit |
7cfc04 |
that affect output.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.IR optional_actions
|
|
Packit |
7cfc04 |
is TCSAFLUSH, the change shall occur after all output written to
|
|
Packit |
7cfc04 |
.IR fildes
|
|
Packit |
7cfc04 |
is transmitted, and all input so far received but not read shall be
|
|
Packit |
7cfc04 |
discarded before the change is made.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the output baud rate stored in the
|
|
Packit |
7cfc04 |
.BR termios
|
|
Packit |
7cfc04 |
structure pointed to by
|
|
Packit |
7cfc04 |
.IR termios_p
|
|
Packit |
7cfc04 |
is the zero baud rate, B0, the modem control lines shall no longer
|
|
Packit |
7cfc04 |
be asserted. Normally, this shall disconnect the line.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the input baud rate stored in the
|
|
Packit |
7cfc04 |
.BR termios
|
|
Packit |
7cfc04 |
structure pointed to by
|
|
Packit |
7cfc04 |
.IR termios_p
|
|
Packit |
7cfc04 |
is 0, the input baud rate given to the hardware is the same as the
|
|
Packit |
7cfc04 |
output baud rate stored in the
|
|
Packit |
7cfc04 |
.BR termios
|
|
Packit |
7cfc04 |
structure.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fItcsetattr\fR()
|
|
Packit |
7cfc04 |
function shall return successfully if it was able to perform any of the
|
|
Packit |
7cfc04 |
requested actions, even if some of the requested actions could not be
|
|
Packit |
7cfc04 |
performed. It shall set all the attributes that the implementation
|
|
Packit |
7cfc04 |
supports as requested and leave all the attributes not supported by
|
|
Packit |
7cfc04 |
the implementation unchanged. If no part of the request can be honored,
|
|
Packit |
7cfc04 |
it shall return \(mi1 and set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to
|
|
Packit |
7cfc04 |
.BR [EINVAL] .
|
|
Packit |
7cfc04 |
If the input and output baud rates differ and are a combination that is
|
|
Packit |
7cfc04 |
not supported, neither baud rate shall be changed. A subsequent call to
|
|
Packit |
7cfc04 |
\fItcgetattr\fR()
|
|
Packit |
7cfc04 |
shall return the actual state of the terminal device (reflecting both
|
|
Packit |
7cfc04 |
the changes made and not made in the previous
|
|
Packit |
7cfc04 |
\fItcsetattr\fR()
|
|
Packit |
7cfc04 |
call). The
|
|
Packit |
7cfc04 |
\fItcsetattr\fR()
|
|
Packit |
7cfc04 |
function shall not change the values found in the
|
|
Packit |
7cfc04 |
.BR termios
|
|
Packit |
7cfc04 |
structure under any circumstances.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The effect of
|
|
Packit |
7cfc04 |
\fItcsetattr\fR()
|
|
Packit |
7cfc04 |
is undefined if the value of the
|
|
Packit |
7cfc04 |
.BR termios
|
|
Packit |
7cfc04 |
structure pointed to by
|
|
Packit |
7cfc04 |
.IR termios_p
|
|
Packit |
7cfc04 |
was not derived from the result of a call to
|
|
Packit |
7cfc04 |
\fItcgetattr\fR()
|
|
Packit |
7cfc04 |
on
|
|
Packit |
7cfc04 |
.IR fildes ;
|
|
Packit |
7cfc04 |
an application should modify only fields and flags defined by this volume of POSIX.1\(hy2008
|
|
Packit |
7cfc04 |
between the call to
|
|
Packit |
7cfc04 |
\fItcgetattr\fR()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fItcsetattr\fR(),
|
|
Packit |
7cfc04 |
leaving all other fields and flags unmodified.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
No actions defined by this volume of POSIX.1\(hy2008, other than a call to
|
|
Packit |
7cfc04 |
\fItcsetattr\fR(),
|
|
Packit |
7cfc04 |
a close of the last file descriptor in the system associated with this
|
|
Packit |
7cfc04 |
terminal device, or an open of the first file descriptor in the system
|
|
Packit |
7cfc04 |
associated with this terminal device (using the O_TTY_INIT flag if it
|
|
Packit |
7cfc04 |
is non-zero and the device is not a pseudo-terminal), shall cause any
|
|
Packit |
7cfc04 |
of the terminal attributes defined by this volume of POSIX.1\(hy2008 to change.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
\fItcsetattr\fR()
|
|
Packit |
7cfc04 |
is called from a process which is a member of a background process
|
|
Packit |
7cfc04 |
group on a
|
|
Packit |
7cfc04 |
.IR fildes
|
|
Packit |
7cfc04 |
associated with its controlling terminal:
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
If the calling thread is blocking SIGTTOU signals or the process is
|
|
Packit |
7cfc04 |
ignoring SIGTTOU signals, the operation completes normally and no signal
|
|
Packit |
7cfc04 |
is sent.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
Otherwise, a SIGTTOU signal shall be sent to the process group.
|
|
Packit |
7cfc04 |
.SH "RETURN VALUE"
|
|
Packit |
7cfc04 |
Upon successful completion, 0 shall be returned. Otherwise,
|
|
Packit |
7cfc04 |
\(mi1 shall be returned and
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
set to indicate the error.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fItcsetattr\fR()
|
|
Packit |
7cfc04 |
function shall fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EBADF
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR fildes
|
|
Packit |
7cfc04 |
argument is not a valid file descriptor.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EINTR
|
|
Packit |
7cfc04 |
A signal interrupted
|
|
Packit |
7cfc04 |
\fItcsetattr\fR().
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EINVAL
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR optional_actions
|
|
Packit |
7cfc04 |
argument is not a supported value, or an attempt was made to change an
|
|
Packit |
7cfc04 |
attribute represented in the
|
|
Packit |
7cfc04 |
.BR termios
|
|
Packit |
7cfc04 |
structure to an unsupported value.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EIO
|
|
Packit |
7cfc04 |
The process group of the writing process is orphaned, the calling thread
|
|
Packit |
7cfc04 |
is not blocking SIGTTOU, and the process is not ignoring SIGTTOU.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENOTTY
|
|
Packit |
7cfc04 |
The file associated with
|
|
Packit |
7cfc04 |
.IR fildes
|
|
Packit |
7cfc04 |
is not a terminal.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
If trying to change baud rates, applications should call
|
|
Packit |
7cfc04 |
\fItcsetattr\fR()
|
|
Packit |
7cfc04 |
then call
|
|
Packit |
7cfc04 |
\fItcgetattr\fR()
|
|
Packit |
7cfc04 |
in order to determine what baud rates were actually selected.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
In general, there are two reasons for an application to change the
|
|
Packit |
7cfc04 |
parameters associated with a terminal device:
|
|
Packit |
7cfc04 |
.IP " 1." 4
|
|
Packit |
7cfc04 |
The device already has working parameter settings but the application
|
|
Packit |
7cfc04 |
needs a different behavior, such as non-canonical mode instead of
|
|
Packit |
7cfc04 |
canonical mode. The application sets (or clears) only a few flags or
|
|
Packit |
7cfc04 |
.IR c_cc [\^]
|
|
Packit |
7cfc04 |
values. Typically, the terminal device in this case is either the
|
|
Packit |
7cfc04 |
controlling terminal for the process or a pseudo-terminal.
|
|
Packit |
7cfc04 |
.IP " 2." 4
|
|
Packit |
7cfc04 |
The device is a modem or similar piece of equipment connected by a serial
|
|
Packit |
7cfc04 |
line, and it was not open before the application opened it. In this case,
|
|
Packit |
7cfc04 |
the application needs to initialize all of the parameter settings ``from
|
|
Packit |
7cfc04 |
scratch''. However, since the
|
|
Packit |
7cfc04 |
.BR termios
|
|
Packit |
7cfc04 |
structure may include both standard and non-standard parameters, the
|
|
Packit |
7cfc04 |
application cannot just initialize the whole structure in an arbitrary
|
|
Packit |
7cfc04 |
way (e.g., using
|
|
Packit |
7cfc04 |
\fImemset\fR())
|
|
Packit |
7cfc04 |
as this may cause some of the non-standard parameters to be set
|
|
Packit |
7cfc04 |
incorrectly, resulting in non-conforming behavior of the terminal
|
|
Packit |
7cfc04 |
device. Conversely, the application cannot just set the standard
|
|
Packit |
7cfc04 |
parameters, assuming that the non-standard parameters will already have
|
|
Packit |
7cfc04 |
suitable values, as the device might previously have been used with
|
|
Packit |
7cfc04 |
non-conforming parameter settings (and some implementations retain the
|
|
Packit |
7cfc04 |
settings from one use to the next). The solution is to open the terminal
|
|
Packit |
7cfc04 |
device using the O_TTY_INIT flag to initialize the terminal device to
|
|
Packit |
7cfc04 |
have conforming parameter settings, obtain those settings using
|
|
Packit |
7cfc04 |
\fItcgetattr\fR(),
|
|
Packit |
7cfc04 |
and then set all of the standard parameters to the desired settings.
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fItcsetattr\fR()
|
|
Packit |
7cfc04 |
function can be interrupted in the following situations:
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
It is interrupted while waiting for output to drain.
|
|
Packit |
7cfc04 |
.IP " *" 4
|
|
Packit |
7cfc04 |
It is called from a process in a background process group and SIGTTOU
|
|
Packit |
7cfc04 |
is caught.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
See also the RATIONALE section in
|
|
Packit |
7cfc04 |
.IR "\fItcgetattr\fR\^(\|)".
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
Using an input baud rate of 0 to set the input rate equal to the output
|
|
Packit |
7cfc04 |
rate may not necessarily be supported in a future version of this volume of POSIX.1\(hy2008.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "\fIcfgetispeed\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fItcgetattr\fR\^(\|)"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Chapter 11" ", " "General Terminal Interface",
|
|
Packit |
7cfc04 |
.IR "\fB<termios.h>\fP"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|