1TCSETATTR(3P)              POSIX Programmer's Manual             TCSETATTR(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       tcsetattr — set the parameters associated with the terminal
13

SYNOPSIS

15       #include <termios.h>
16
17       int tcsetattr(int fildes, int optional_actions,
18           const struct termios *termios_p);
19

DESCRIPTION

21       The tcsetattr() function shall set the parameters associated  with  the
22       terminal  referred  to by the open file descriptor fildes (an open file
23       descriptor associated with a terminal) from the termios structure  ref‐
24       erenced by termios_p as follows:
25
26        *  If optional_actions is TCSANOW, the change shall occur immediately.
27
28        *  If  optional_actions is TCSADRAIN, the change shall occur after all
29           output written to fildes is transmitted. This  function  should  be
30           used when changing parameters that affect output.
31
32        *  If  optional_actions is TCSAFLUSH, the change shall occur after all
33           output written to fildes is  transmitted,  and  all  input  so  far
34           received but not read shall be discarded before the change is made.
35
36       If  the  output baud rate stored in the termios structure pointed to by
37       termios_p is the zero baud rate, B0, the modem control lines  shall  no
38       longer be asserted. Normally, this shall disconnect the line.
39
40       If  the  input  baud rate stored in the termios structure pointed to by
41       termios_p is 0, the input baud rate given to the hardware is  the  same
42       as the output baud rate stored in the termios structure.
43
44       The  tcsetattr()  function  shall return successfully if it was able to
45       perform any of the requested actions, even if  some  of  the  requested
46       actions  could  not  be performed. It shall set all the attributes that
47       the implementation supports as requested and leave all  the  attributes
48       not  supported  by  the  implementation  unchanged.  If  no part of the
49       request can be honored, it shall return -1 and set errno  to  [EINVAL].
50       If the input and output baud rates differ and are a combination that is
51       not supported, neither baud rate shall be changed. A subsequent call to
52       tcgetattr()  shall  return  the  actual  state  of  the terminal device
53       (reflecting both the changes made and not made in  the  previous  tcse‐
54       tattr()  call).  The  tcsetattr()  function shall not change the values
55       found in the termios structure under any circumstances.
56
57       The effect of tcsetattr() is undefined if  the  value  of  the  termios
58       structure  pointed to by termios_p was not derived from the result of a
59       call to tcgetattr() on fildes; an application should modify only fields
60       and  flags  defined  by this volume of POSIX.1‐2017 between the call to
61       tcgetattr() and tcsetattr(), leaving all other fields and flags unmodi‐
62       fied.
63
64       No actions defined by this volume of POSIX.1‐2017, other than a call to
65       tcsetattr(), a close of the last file descriptor in the system  associ‐
66       ated with this terminal device, or an open of the first file descriptor
67       in  the  system  associated  with  this  terminal  device  (using   the
68       O_TTY_INIT flag if it is non-zero and the device is not a pseudo-termi‐
69       nal), shall cause any of the terminal attributes defined by this volume
70       of POSIX.1‐2017 to change.
71
72       If  tcsetattr()  is  called from a process which is a member of a back‐
73       ground process group on a fildes associated with its controlling termi‐
74       nal:
75
76        *  If the calling thread is blocking SIGTTOU signals or the process is
77           ignoring SIGTTOU signals, the operation completes normally  and  no
78           signal is sent.
79
80        *  Otherwise, a SIGTTOU signal shall be sent to the process group.
81

RETURN VALUE

83       Upon successful completion, 0 shall be returned. Otherwise, -1 shall be
84       returned and errno set to indicate the error.
85

ERRORS

87       The tcsetattr() function shall fail if:
88
89       EBADF  The fildes argument is not a valid file descriptor.
90
91       EINTR  A signal interrupted tcsetattr().
92
93       EINVAL The optional_actions argument is not a supported  value,  or  an
94              attempt  was  made  to  change  an  attribute represented in the
95              termios structure to an unsupported value.
96
97       EIO    The process group of the writing process is orphaned, the  call‐
98              ing  thread  is  not  blocking  SIGTTOU,  and the process is not
99              ignoring SIGTTOU.
100
101       ENOTTY The file associated with fildes is not a terminal.
102
103       The following sections are informative.
104

EXAMPLES

106       None.
107

APPLICATION USAGE

109       If trying to change baud rates, applications  should  call  tcsetattr()
110       then  call tcgetattr() in order to determine what baud rates were actu‐
111       ally selected.
112
113       In general, there are two reasons for  an  application  to  change  the
114       parameters associated with a terminal device:
115
116        1. The  device already has working parameter settings but the applica‐
117           tion needs a different behavior, such as non-canonical mode instead
118           of  canonical  mode.  The  application  sets (or clears) only a few
119           flags or c_cc[] values. Typically, the terminal device in this case
120           is either the controlling terminal for the process or a pseudo-ter‐
121           minal.
122
123        2. The device is a modem or similar piece of equipment connected by  a
124           serial  line, and it was not open before the application opened it.
125           In this case, the application needs to initialize all of the param‐
126           eter  settings  ``from scratch''. However, since the termios struc‐
127           ture may include both standard  and  non-standard  parameters,  the
128           application  cannot just initialize the whole structure in an arbi‐
129           trary way (e.g., using memset()) as this may cause some of the non-
130           standard  parameters  to  be set incorrectly, resulting in non-con‐
131           forming behavior of the terminal device. Conversely,  the  applica‐
132           tion  cannot  just  set  the standard parameters, assuming that the
133           non-standard parameters will already have suitable values,  as  the
134           device  might previously have been used with non-conforming parame‐
135           ter settings (and some implementations retain the settings from one
136           use to the next). The solution is to open the terminal device using
137           the O_TTY_INIT flag to initialize the terminal device to have  con‐
138           forming  parameter  settings,  obtain  those  settings  using tcge‐
139           tattr(), and then set all of the standard parameters to the desired
140           settings.
141

RATIONALE

143       The  tcsetattr()  function  can  be interrupted in the following situa‐
144       tions:
145
146        *  It is interrupted while waiting for output to drain.
147
148        *  It is called from a process in a background process group and SIGT‐
149           TOU is caught.
150
151       See also the RATIONALE section in tcgetattr().
152

FUTURE DIRECTIONS

154       Using an input baud rate of 0 to set the input rate equal to the output
155       rate may not necessarily be supported in a future version of this  vol‐
156       ume of POSIX.1‐2017.
157

SEE ALSO

159       cfgetispeed(), tcgetattr()
160
161       The Base Definitions volume of POSIX.1‐2017, Chapter 11, General Termi‐
162       nal Interface, <termios.h>
163
165       Portions of this text are reprinted and reproduced in  electronic  form
166       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
167       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
168       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
169       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
170       event of any discrepancy between this version and the original IEEE and
171       The Open Group Standard, the original IEEE and The Open Group  Standard
172       is  the  referee document. The original Standard can be obtained online
173       at http://www.opengroup.org/unix/online.html .
174
175       Any typographical or formatting errors that appear  in  this  page  are
176       most likely to have been introduced during the conversion of the source
177       files to man page format. To report such errors,  see  https://www.ker
178       nel.org/doc/man-pages/reporting_bugs.html .
179
180
181
182IEEE/The Open Group                  2017                        TCSETATTR(3P)
Impressum