tcsetattr Subroutine

Purpose

Sets terminal state.

Library

Standard C Library (libc.a)

Syntax

#include <termios.h>

int tcsetattr (FileDescriptor, OptionalActions, TermiosPointer) int FileDescriptor, OptionalActions; const struct termios * TermiosPointer;

Description

The tcsetattr subroutine sets the parameters associated with the object referred to by the FileDescriptor parameter (unless support required from the underlying hardware is unavailable), from the termios structure referenced by the TermiosPointer parameter.

The value of the OptionalActions parameter determines how the tcsetattr subroutine is handled.

The 0 baud rate (B0) is used to terminate the connection. If B0 is specified as the output baud rate when the tcsetattr subroutine is called, the modem control lines are no longer asserted. Normally, this disconnects the line.

Using 0 as the input baud rate in the termios structure to cause tcsetattr to change the input baud rate to the same value as that specified by the value of the output baud rate, is obsolete.

If an attempt is made using the tcsetattr subroutine to set:

An unsupported baud rate
Baud rates, such that the input and output baud rates differ and the hardware does not support that combination
Other features not supported by the hardware

but the tcsetattr subroutine is able to perform some of the requested actions, then the subroutine returns successfully, having set all supported attributes and leaving the above unsupported attributes unchanged.

If no part of the request can be honored, the tcsetattr subroutine returns a value of -1 and the errno global variable is set to EINVAL.

If the input and output baud rates differ and are a combination that is not supported, neither baud rate is changed. A subsequent call to the tcgetattr subroutine returns the actual state of the terminal device (reflecting both the changes made and not made in the previous tcsetattr call). The tcsetattr subroutine does not change the values in the termios structure whether or not it actually accepts them.

If the tcsetattr subroutine is called by a process which is a member of a background process group on a FileDescriptor associated with its controlling terminal, a SIGTTOU signal is sent to the background process group. If the calling process is blocking or ignoring SIGTTOU signals, the process performs the operation and no signal is sent.

Parameters

Item	Description
FileDescriptor	Specifies an open file descriptor.
OptionalActions	Specifies one of the following values: TCSANOW The change occurs immediately. TCSADRAIN The change occurs after all output written to the object referred to by FileDescriptor has been transmitted. This function should be used when changing parameters that affect output. TCSAFLUSH The change occurs after all output written to the object referred to by FileDescriptor has been transmitted. All input that has been received but not read is discarded before the change is made.
TermiosPointer	Points to a termios structure.

Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The tcsetattr subroutine is unsuccessful if one of the following is true:

Item	Description
EBADF	The FileDescriptor parameter does not specify a valid file descriptor.
EINTR	A signal interrupted the tcsetattr subroutine.
EINVAL	The OptionalActions argument is not a proper value, or an attempt was made to change an attribute represented in the termios structure to an unsupported value.
EIO	The process group of the writing process is orphaned, and the writing process does not ignore or block the SIGTTOU signal.
ENOTTY	The file associated with the FileDescriptor parameter is not a terminal.

Example

To set the terminal state after the current output completes, enter:

rc = tcsetattr(stdout, TCSADRAIN, &my_termios);