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