# tcsetattr

## 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.
    


## NAME



           tcsetattr — set the parameters associated with the terminal
    


## SYNOPSIS



           #include <termios.h>
    
           int tcsetattr(int _fildes_ , int _optional_actions_ ,
               const struct termios *_termios_p_);
    


## DESCRIPTION



           The _tcsetattr_() function shall set the parameters associated with
           the terminal referred to by the open file descriptor _fildes_ (an
           open file descriptor associated with a terminal) from the **termios**
           structure referenced by _termios_p_ as follows:
    
            *  If _optional_actions_ is TCSANOW, the change shall occur
               immediately.
    
            *  If _optional_actions_ is TCSADRAIN, the change shall occur after
               all output written to _fildes_ is transmitted. This function
               should be used when changing parameters that affect output.
    
            *  If _optional_actions_ is TCSAFLUSH, the change shall occur after
               all output written to _fildes_ is transmitted, and all input so
               far received but not read shall be discarded before the change
               is made.
    
           If the output baud rate stored in the **termios** structure pointed to
           by _termios_p_ is the zero baud rate, B0, the modem control lines
           shall no longer be asserted. Normally, this shall disconnect the
           line.
    
           If the input baud rate stored in the **termios** structure pointed to
           by _termios_p_ is 0, the input baud rate given to the hardware is
           the same as the output baud rate stored in the **termios** structure.
    
           The _tcsetattr_() 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 _errno_ to **[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 _tcgetattr_() shall return
           the actual state of the terminal device (reflecting both the
           changes made and not made in the previous _tcsetattr_() call). The
           _tcsetattr_() function shall not change the values found in the
           **termios** structure under any circumstances.
    
           The effect of _tcsetattr_() is undefined if the value of the **termios**
           structure pointed to by _termios_p_ was not derived from the result
           of a call to _tcgetattr_() on _fildes_ ; an application should modify
           only fields and flags defined by this volume of POSIX.1‐2017
           between the call to _tcgetattr_() and _tcsetattr_(), leaving all other
           fields and flags unmodified.
    
           No actions defined by this volume of POSIX.1‐2017, other than a
           call to _tcsetattr_(), 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‐2017 to change.
    
           If _tcsetattr_() is called from a process which is a member of a
           background process group on a _fildes_ associated with its
           controlling terminal:
    
            *  If the calling thread is blocking SIGTTOU signals or the
               process is ignoring SIGTTOU signals, the operation completes
               normally and no signal is sent.
    
            *  Otherwise, a SIGTTOU signal shall be sent to the process
               group.
    


## RETURN VALUE



           Upon successful completion, 0 shall be returned. Otherwise, -1
           shall be returned and _errno_ set to indicate the error.
    


## ERRORS



           The _tcsetattr_() function shall fail if:
    
           **EBADF** The _fildes_ argument is not a valid file descriptor.
    
           **EINTR** A signal interrupted _tcsetattr_().
    
           **EINVAL** The _optional_actions_ argument is not a supported 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, the
                  calling thread is not blocking SIGTTOU, and the process is
                  not ignoring SIGTTOU.
    
           **ENOTTY** The file associated with _fildes_ is not a terminal.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           If trying to change baud rates, applications should call
           _tcsetattr_() then call _tcgetattr_() in order to determine what baud
           rates were actually selected.
    
           In general, there are two reasons for an application to change the
           parameters associated with a terminal device:
    
            1. 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 _c_cc_[] values. Typically, the
               terminal device in this case is either the controlling
               terminal for the process or a pseudo-terminal.
    
            2. 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 **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 _memset_())
               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 _tcgetattr_(), and then set all of the standard
               parameters to the desired settings.
    


## RATIONALE



           The _tcsetattr_() function can be interrupted in the following
           situations:
    
            *  It is interrupted while waiting for output to drain.
    
            *  It is called from a process in a background process group and
               SIGTTOU is caught.
    
           See also the RATIONALE section in tcgetattr(3p).
    


## 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‐2017.
    


* * *