Commit | Line | Data |
---|---|---|
984263bc MD |
1 | .\" Copyright (c) 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
dc71b7ab | 12 | .\" 3. Neither the name of the University nor the names of its contributors |
984263bc MD |
13 | .\" may be used to endorse or promote products derived from this software |
14 | .\" without specific prior written permission. | |
15 | .\" | |
16 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
17 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
18 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
19 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
20 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
21 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
22 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
23 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
24 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
25 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
26 | .\" SUCH DAMAGE. | |
27 | .\" | |
28 | .\" @(#)tcsetattr.3 8.3 (Berkeley) 1/2/94 | |
29 | .\" $FreeBSD: src/lib/libc/gen/tcsetattr.3,v 1.6.2.4 2002/12/29 16:35:34 schweikh Exp $ | |
30 | .\" | |
81c399c9 | 31 | .Dd December 10, 2017 |
984263bc MD |
32 | .Dt TCSETATTR 3 |
33 | .Os | |
34 | .Sh NAME | |
35 | .Nm cfgetispeed , | |
36 | .Nm cfsetispeed , | |
37 | .Nm cfgetospeed , | |
38 | .Nm cfsetospeed , | |
39 | .Nm cfsetspeed , | |
40 | .Nm cfmakeraw , | |
81c399c9 | 41 | .Nm cfmakesane , |
984263bc MD |
42 | .Nm tcgetattr , |
43 | .Nm tcsetattr | |
44 | .Nd manipulating the termios structure | |
45 | .Sh LIBRARY | |
46 | .Lb libc | |
47 | .Sh SYNOPSIS | |
48 | .In termios.h | |
49 | .Ft speed_t | |
50 | .Fn cfgetispeed "const struct termios *t" | |
51 | .Ft int | |
52 | .Fn cfsetispeed "struct termios *t" "speed_t speed" | |
53 | .Ft speed_t | |
54 | .Fn cfgetospeed "const struct termios *t" | |
55 | .Ft int | |
56 | .Fn cfsetospeed "struct termios *t" "speed_t speed" | |
57 | .Ft int | |
58 | .Fn cfsetspeed "struct termios *t" "speed_t speed" | |
59 | .Ft void | |
60 | .Fn cfmakeraw "struct termios *t" | |
81c399c9 SW |
61 | .Ft void |
62 | .Fn cfmakesane "struct termios *t" | |
984263bc MD |
63 | .Ft int |
64 | .Fn tcgetattr "int fd" "struct termios *t" | |
65 | .Ft int | |
66 | .Fn tcsetattr "int fd" "int action" "const struct termios *t" | |
67 | .Sh DESCRIPTION | |
68 | The | |
69 | .Fn cfmakeraw , | |
81c399c9 | 70 | .Fn cfmakesane , |
984263bc MD |
71 | .Fn tcgetattr |
72 | and | |
73 | .Fn tcsetattr | |
74 | functions are provided for getting and setting the termios structure. | |
75 | .Pp | |
76 | The | |
77 | .Fn cfgetispeed , | |
78 | .Fn cfsetispeed , | |
79 | .Fn cfgetospeed , | |
80 | .Fn cfsetospeed | |
81 | and | |
82 | .Fn cfsetspeed | |
83 | functions are provided for getting and setting the baud rate values in | |
84 | the termios structure. | |
85 | The effects of the functions on the terminal as described below | |
86 | do not become effective, nor are all errors detected, until the | |
87 | .Fn tcsetattr | |
88 | function is called. | |
89 | Certain values for baud rates set in the termios structure and passed to | |
90 | .Fn tcsetattr | |
91 | have special meanings. | |
92 | These are discussed in the portion of the manual page that describes the | |
93 | .Fn tcsetattr | |
94 | function. | |
95 | .Sh GETTING AND SETTING THE BAUD RATE | |
96 | The input and output baud rates are found in the termios structure. | |
97 | The unsigned integer | |
98 | .Li speed_t | |
99 | is typedef'd in the include file | |
44cb301e | 100 | .In termios.h . |
984263bc MD |
101 | The value of the integer corresponds directly to the baud rate being |
102 | represented, however, the following symbolic values are defined. | |
103 | .Bd -literal | |
104 | #define B0 0 | |
105 | #define B50 50 | |
106 | #define B75 75 | |
107 | #define B110 110 | |
108 | #define B134 134 | |
109 | #define B150 150 | |
110 | #define B200 200 | |
111 | #define B300 300 | |
112 | #define B600 600 | |
113 | #define B1200 1200 | |
602f6c36 | 114 | #define B1800 1800 |
984263bc MD |
115 | #define B2400 2400 |
116 | #define B4800 4800 | |
117 | #define B9600 9600 | |
118 | #define B19200 19200 | |
119 | #define B38400 38400 | |
602f6c36 SW |
120 | #if __BSD_VISIBLE |
121 | #define B7200 7200 | |
122 | #define B14400 14400 | |
123 | #define B28800 28800 | |
124 | #define B57600 57600 | |
125 | #define B76800 76800 | |
126 | #define B115200 115200 | |
127 | #define B230400 230400 | |
984263bc MD |
128 | #define EXTA 19200 |
129 | #define EXTB 38400 | |
602f6c36 | 130 | #endif /* __BSD_VISIBLE */ |
984263bc MD |
131 | .Ed |
132 | .Pp | |
133 | The | |
134 | .Fn cfgetispeed | |
135 | function returns the input baud rate in the termios structure referenced by | |
136 | .Fa tp . | |
137 | .Pp | |
138 | The | |
139 | .Fn cfsetispeed | |
140 | function sets the input baud rate in the termios structure referenced by | |
141 | .Fa tp | |
142 | to | |
143 | .Fa speed . | |
144 | .Pp | |
145 | The | |
146 | .Fn cfgetospeed | |
147 | function returns the output baud rate in the termios structure referenced by | |
148 | .Fa tp . | |
149 | .Pp | |
150 | The | |
151 | .Fn cfsetospeed | |
152 | function sets the output baud rate in the termios structure referenced by | |
153 | .Fa tp | |
154 | to | |
155 | .Fa speed . | |
156 | .Pp | |
157 | The | |
158 | .Fn cfsetspeed | |
159 | function sets both the input and output baud rate in the termios structure | |
160 | referenced by | |
161 | .Fa tp | |
162 | to | |
163 | .Fa speed . | |
164 | .Pp | |
165 | Upon successful completion, the functions | |
166 | .Fn cfsetispeed , | |
167 | .Fn cfsetospeed , | |
168 | and | |
169 | .Fn cfsetspeed | |
170 | return a value of 0. | |
171 | Otherwise, a value of -1 is returned and the global variable | |
172 | .Va errno | |
173 | is set to indicate the error. | |
174 | .Sh GETTING AND SETTING THE TERMIOS STATE | |
175 | This section describes the functions that are used to control the general | |
176 | terminal interface. | |
177 | Unless otherwise noted for a specific command, these functions are restricted | |
178 | from use by background processes. | |
179 | Attempts to perform these operations shall cause the process group to be sent | |
632f95cb SW |
180 | a |
181 | .Dv SIGTTOU | |
182 | signal. | |
183 | If the calling process is blocking or ignoring | |
184 | .Dv SIGTTOU | |
185 | signals, the process is allowed to perform the operation and the | |
186 | .Dv SIGTTOU | |
187 | signal is not sent. | |
984263bc MD |
188 | .Pp |
189 | In all the functions, although | |
190 | .Fa fd | |
191 | is an open file descriptor, the functions affect the underlying terminal | |
192 | file, not just the open file description associated with the particular | |
193 | file descriptor. | |
194 | .Pp | |
195 | The | |
196 | .Fn cfmakeraw | |
197 | function sets the flags stored in the termios structure to a state disabling | |
198 | all input and output processing, giving a | |
81c399c9 SW |
199 | .Dq raw I/O path , |
200 | while the | |
201 | .Fn cfmakesane | |
202 | function sets them to a state similar to those of a newly created | |
203 | terminal device. | |
984263bc MD |
204 | It should be noted that there is no function to reverse this effect. |
205 | This is because there are a variety of processing options that could be | |
206 | re-enabled and the correct method is for an application to snapshot the | |
207 | current terminal state using the function | |
208 | .Fn tcgetattr , | |
81c399c9 | 209 | setting raw or sane mode with |
984263bc | 210 | .Fn cfmakeraw |
81c399c9 SW |
211 | or |
212 | .Fn cfmakesane | |
984263bc MD |
213 | and the subsequent |
214 | .Fn tcsetattr , | |
215 | and then using another | |
216 | .Fn tcsetattr | |
217 | with the saved state to revert to the previous terminal state. | |
218 | .Pp | |
219 | The | |
220 | .Fn tcgetattr | |
221 | function copies the parameters associated with the terminal referenced | |
222 | by | |
223 | .Fa fd | |
224 | in the termios structure referenced by | |
225 | .Fa tp . | |
226 | This function is allowed from a background process, however, the terminal | |
227 | attributes may be subsequently changed by a foreground process. | |
228 | .Pp | |
229 | The | |
230 | .Fn tcsetattr | |
231 | function sets the parameters associated with the terminal from the | |
232 | termios structure referenced by | |
233 | .Fa tp . | |
234 | The | |
235 | .Fa action | |
236 | field is created by | |
237 | .Em or Ns 'ing | |
238 | the following values, as specified in the include file | |
44cb301e | 239 | .In termios.h . |
632f95cb SW |
240 | .Bl -tag -width ".Dv TCSADRAIN" |
241 | .It Dv TCSANOW | |
984263bc | 242 | The change occurs immediately. |
632f95cb | 243 | .It Dv TCSADRAIN |
984263bc MD |
244 | The change occurs after all output written to |
245 | .Fa fd | |
246 | has been transmitted to the terminal. | |
247 | This value of | |
248 | .Fa action | |
249 | should be used when changing parameters that affect output. | |
632f95cb | 250 | .It Dv TCSAFLUSH |
984263bc MD |
251 | The change occurs after all output written to |
252 | .Fa fd | |
253 | has been transmitted to the terminal. | |
254 | Additionally, any input that has been received but not read is discarded. | |
632f95cb | 255 | .It Dv TCSASOFT |
984263bc MD |
256 | If this value is |
257 | .Em or Ns 'ed | |
258 | into the | |
259 | .Fa action | |
260 | value, the values of the | |
261 | .Em c_cflag , | |
262 | .Em c_ispeed , | |
263 | and | |
264 | .Em c_ospeed | |
265 | fields are ignored. | |
266 | .El | |
267 | .Pp | |
268 | The 0 baud rate is used to terminate the connection. | |
269 | If 0 is specified as the output speed to the function | |
270 | .Fn tcsetattr , | |
271 | modem control will no longer be asserted on the terminal, disconnecting | |
272 | the terminal. | |
273 | .Pp | |
274 | If zero is specified as the input speed to the function | |
275 | .Fn tcsetattr , | |
276 | the input baud rate will be set to the same value as that specified by | |
277 | the output baud rate. | |
278 | .Pp | |
279 | If | |
280 | .Fn tcsetattr | |
281 | is unable to make any of the requested changes, it returns -1 and | |
0f09e575 SW |
282 | sets |
283 | .Va errno . | |
984263bc MD |
284 | Otherwise, it makes all of the requested changes it can. |
285 | If the specified input and output baud rates differ and are a combination | |
286 | that is not supported, neither baud rate is changed. | |
287 | .Pp | |
288 | Upon successful completion, the functions | |
289 | .Fn tcgetattr | |
290 | and | |
291 | .Fn tcsetattr | |
292 | return a value of 0. | |
293 | Otherwise, they | |
294 | return -1 and the global variable | |
295 | .Va errno | |
296 | is set to indicate the error, as follows: | |
297 | .Bl -tag -width Er | |
298 | .It Bq Er EBADF | |
299 | The | |
300 | .Fa fd | |
301 | argument to | |
302 | .Fn tcgetattr | |
303 | or | |
304 | .Fn tcsetattr | |
305 | was not a valid file descriptor. | |
306 | .It Bq Er EINTR | |
307 | The | |
308 | .Fn tcsetattr | |
309 | function was interrupted by a signal. | |
310 | .It Bq Er EINVAL | |
311 | The | |
312 | .Fa action | |
313 | argument to the | |
314 | .Fn tcsetattr | |
315 | function was not valid, or an attempt was made to change an attribute | |
316 | represented in the termios structure to an unsupported value. | |
317 | .It Bq Er ENOTTY | |
318 | The file associated with the | |
319 | .Fa fd | |
320 | argument to | |
321 | .Fn tcgetattr | |
322 | or | |
323 | .Fn tcsetattr | |
324 | is not a terminal. | |
325 | .El | |
326 | .Sh SEE ALSO | |
327 | .Xr tcsendbreak 3 , | |
328 | .Xr termios 4 | |
329 | .Sh STANDARDS | |
330 | The | |
331 | .Fn cfgetispeed , | |
332 | .Fn cfsetispeed , | |
333 | .Fn cfgetospeed , | |
334 | .Fn cfsetospeed , | |
335 | .Fn tcgetattr | |
336 | and | |
337 | .Fn tcsetattr | |
338 | functions are expected to be compliant with the | |
339 | .St -p1003.1-88 | |
340 | specification. | |
341 | The | |
81c399c9 SW |
342 | .Fn cfmakeraw , |
343 | .Fn cfmakesane | |
984263bc MD |
344 | and |
345 | .Fn cfsetspeed | |
346 | functions, | |
347 | as well as the | |
632f95cb | 348 | .Dv TCSASOFT |
984263bc MD |
349 | option to the |
350 | .Fn tcsetattr | |
351 | function are extensions to the | |
352 | .St -p1003.1-88 | |
353 | specification. |