Commit | Line | Data |
---|---|---|
cb5bca25 MT |
1 | .\" Copyright (c) 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" %sccs.include.redist.roff% | |
5 | .\" | |
d365c391 | 6 | .\" @(#)tcsetattr.3 5.1 (Berkeley) %G% |
cb5bca25 | 7 | .\" |
d365c391 | 8 | .Dd "" |
cb5bca25 MT |
9 | .Dt TCSETATTR 3 |
10 | .Os | |
11 | .Sh NAME | |
d365c391 KB |
12 | .Nm cfgetispeed , |
13 | .Nm cfsetispeed , | |
14 | .Nm cfgetospeed , | |
15 | .Nm cfsetospeed , | |
16 | .Nm cfsetspeed , | |
17 | .Nm cfmakeraw , | |
18 | .Nm tcgetattr , | |
cb5bca25 | 19 | .Nm tcsetattr |
d365c391 KB |
20 | .Nd manipulating the termios structure |
21 | .Sh SYNOPSIS | |
22 | .Fd #include <termios.h> | |
23 | .Ft speed_t | |
24 | .Fn cfgetispeed "struct termios *t" | |
25 | .Ft int | |
26 | .Fn cfsetispeed "struct termios *t" "speed_t speed" | |
27 | .Ft speed_t | |
28 | .Fn cfgetospeed "struct termios *t" | |
29 | .Ft int | |
30 | .Fn cfsetospeed "struct termios *t" "speed_t speed" | |
31 | .Ft void | |
32 | .Fn cfsetspeed "struct termios *t" "speed_t speed" | |
33 | .Ft void | |
34 | .Fn cfmakeraw "struct termios *t" | |
35 | .Ft int | |
36 | .Fn tcgetattr "int fd" "struct termios *t" | |
37 | .Ft int | |
38 | .Fn tcsetattr "int fd" "int action" "struct termios *t" | |
39 | .Sh DESCRIPTION | |
40 | The | |
41 | .Nm cfmakeraw , | |
42 | .Nm tcgetattr | |
43 | and | |
44 | .Nm tcsetattr | |
45 | functions are provided for getting and setting the termios structure. | |
46 | .Pp | |
47 | The | |
48 | .Nm cfgetispeed , | |
49 | .Nm cfsetispeed , | |
50 | .Nm cfgetospeed , | |
51 | .Nm cfsetospeed | |
52 | and | |
53 | .Nm cfsetspeed | |
54 | functions are provided for getting and setting the baud rate values in | |
55 | the termios structure. | |
56 | The effects of the functions on the terminal as described below | |
57 | do not become effective, nor are all errors detected, until the | |
58 | .Nm tcsetattr | |
59 | function is called. | |
60 | Certain values for baud rates set in the termios structure and passed to | |
61 | .Nm tcsetattr | |
62 | have special meanings. | |
63 | These are discussed in the portion of the manual page that describes the | |
64 | .Nm tcsetattr | |
65 | function. | |
66 | .Sh GETTING AND SETTING THE BAUD RATE | |
67 | The input and output baud rates are found in the termios structure. | |
68 | The unsigned integer | |
69 | .Li speed_t | |
70 | is typdef'd in the include file | |
71 | .Aq Pa termios.h . | |
72 | The value of the integer corresponds directly to the baud rate being | |
73 | represented, however, the following symbolic values are defined. | |
74 | .Bd -literal | |
75 | #define B0 0 | |
76 | #define B50 50 | |
77 | #define B75 75 | |
78 | #define B110 110 | |
79 | #define B134 134 | |
80 | #define B150 150 | |
81 | #define B200 200 | |
82 | #define B300 300 | |
83 | #define B600 600 | |
84 | #define B1200 1200 | |
85 | #define B1800 1800 | |
86 | #define B2400 2400 | |
87 | #define B4800 4800 | |
88 | #define B9600 9600 | |
89 | #define B19200 19200 | |
90 | #define B38400 38400 | |
91 | #ifndef _POSIX_SOURCE | |
92 | #define EXTA 19200 | |
93 | #define EXTB 38400 | |
94 | #endif /*_POSIX_SOURCE */ | |
95 | .Ed | |
96 | .Pp | |
97 | The | |
98 | .Nm cfgetispeed | |
99 | function returns the input baud rate in the termios structure referenced by | |
100 | .Fa tp . | |
101 | .Pp | |
102 | The | |
103 | .Nm cfsetispeed | |
104 | function sets the input baud rate in the termios structure referenced by | |
105 | .Fa tp | |
106 | to | |
107 | .Fa speed . | |
108 | .Pp | |
109 | The | |
110 | .Nm cfgetospeed | |
111 | function returns the output baud rate in the termios structure referenced by | |
112 | .Fa tp . | |
113 | .Pp | |
114 | The | |
115 | .Nm cfsetospeed | |
116 | function sets the output baud rate in the termios structure referenced by | |
117 | .Fa tp | |
118 | to | |
119 | .Fa speed . | |
120 | .Pp | |
121 | The | |
122 | .Nm cfsetspeed | |
123 | function sets both the input and output baud rate in the termios structure | |
124 | referenced by | |
125 | .Fa tp | |
126 | to | |
127 | .Fa speed . | |
128 | .Pp | |
129 | Upon successful completion, the functions | |
130 | .Nm cfsetispeed , | |
131 | .Nm cfsetospeed , | |
132 | and | |
133 | .Nm cfsetspeed | |
134 | return a value of 0. | |
135 | Otherwise, a value of -1 is returned and the global variable | |
136 | .Va errno | |
137 | is set to indicate the error. | |
138 | .Sh GETTING AND SETTING THE TERMIOS STATE | |
139 | This section describes the functions that are used to control the general | |
140 | terminal interface. | |
141 | Unless otherwise noted for a specific command, these functions are restricted | |
142 | from use by background processes. | |
143 | Attempts to perform these operations shall cause the process group to be sent | |
144 | a SIGTTOU signal. | |
145 | If the calling process is blocking or ignoring SIGTTOU signals, the process | |
cb5bca25 | 146 | is allowed to perform the operation and the SIGTTOU signal is not sent. |
d365c391 KB |
147 | .Pp |
148 | In all the functions, although | |
149 | .Fa fd | |
150 | is an open file descriptor, the functions affect the underlying terminal | |
151 | file, not just the open file description associated with the particular | |
152 | file descriptor. | |
153 | .Pp | |
154 | The | |
155 | .Nm cfmakeraw | |
156 | function sets the flags stored in the termios structure to a state disabling | |
157 | all input and output processing, giving a | |
158 | .Dq raw I/O path. | |
159 | It should be noted that there is no function to reverse this effect. | |
160 | This is because there are a variety of processing options that could be | |
161 | re-enabled and the correct method is for an application to snapshot the | |
162 | current terminal state using the function | |
163 | .Nm tcgetattr , | |
164 | setting raw mode with | |
165 | .Nm cfmakeraw | |
166 | and the subsequent | |
167 | .Nm tcsetattr , | |
168 | and then using another | |
169 | .Nm tcsetattr | |
170 | with the saved state to revert to the previous terminal state. | |
171 | .Pp | |
172 | The | |
173 | .Nm tcgetattr | |
174 | function copies the parameters associated with the terminal referenced | |
175 | by | |
176 | .Fa fd | |
177 | in the termios structure referenced by | |
178 | .Fa tp . | |
179 | This function is allowed from a background process, however, the terminal | |
180 | attributes may be subsequently changed by a foreground process. | |
181 | .Pp | |
182 | The | |
183 | .Nm tcsetattr | |
184 | function sets the parameters associated with the terminal from the | |
185 | termios structure referenced by | |
186 | .Fa tp . | |
187 | The | |
188 | .Fa action | |
189 | field is created by | |
190 | .Em or Ns 'ing | |
191 | the following values, as specified in the include file | |
192 | .Aq Pa termios.h . | |
193 | .Bl -tag -width "TCSADRAIN" | |
194 | .It Fa TCSANOW | |
195 | The change occurs immediately. | |
196 | .It Fa TCSADRAIN | |
197 | The change occurs after all output written to | |
198 | .Fa fd | |
199 | has been transmitted to the terminal. | |
200 | This value of | |
201 | .Fa action | |
202 | should be used when changing parameters that affect output. | |
203 | .It Fa TCSAFLUSH | |
204 | The change occurs after all output written to | |
205 | .Fa fd | |
206 | has been transmitted to the terminal | |
207 | Additionally, any input that has been received but not read is discarded. | |
208 | .It Fa TCSASOFT | |
209 | If this value is | |
210 | .Em or Ns 'ed | |
211 | into the | |
212 | .Fa action | |
213 | value, the values of the | |
214 | .Em c_cflag , | |
215 | .Em c_ispeed , | |
216 | and | |
217 | .Em c_ospeed | |
218 | fields are ignored. | |
219 | .El | |
220 | .Pp | |
221 | The 0 baud rate is used to terminate the connection. | |
222 | If 0 is specified as the output speed to the function | |
223 | .Nm tcsetattr , | |
224 | modem control will no longer be asserted on the terminal, disconnecting | |
225 | the terminal. | |
226 | .Pp | |
227 | If zero is specified as the input speed to the function | |
228 | .Nm tcsetattr , | |
229 | the input baud rate will be set to the same value as that specified by | |
230 | the output baud rate. | |
231 | .Pp | |
232 | If | |
233 | .Nm tcsetattr | |
234 | is unable able to make any of the requested changes, it returns -1 and | |
235 | sets errno. | |
236 | Otherwise, it makes all of the requested changes it can. | |
237 | If the specified input and output baud rates differ and are a combination | |
238 | that is not supported, neither baud rate is changed. | |
239 | .Pp | |
240 | Upon successful completion, the functions | |
241 | .Nm tcgetattr | |
242 | and | |
243 | .Nm tcsetattr | |
244 | return a value of 0. | |
245 | Otherwise, they | |
246 | return -1 and the global variable | |
247 | .Va errno | |
248 | is set to indicate the error, as follows: | |
249 | .Bl -tag -width Er | |
250 | .It Bq Er EBADF | |
251 | The | |
252 | .Fa fd | |
253 | argument to | |
254 | .Nm tcgetattr | |
255 | or | |
256 | .Nm tcsetattr | |
257 | was not a valid file descriptor. | |
258 | .It Bq Er EINTR | |
259 | The | |
260 | .Nm tcsetattr | |
261 | function was interrupted by a signal. | |
262 | .It Bq Er EINVAL | |
263 | The | |
264 | .Fa action | |
265 | argument to the | |
266 | .Nm tcsetattr | |
267 | function was not valid, or an attempt was made to change an attribute | |
268 | represented in the termios structure to an unsupported value. | |
269 | .It Bq Er ENOTTY | |
270 | The file associated with the | |
271 | .Fa fd | |
272 | argument to | |
273 | .Nm tcgetattr | |
274 | or | |
275 | .Nm tcsetattr | |
276 | is not a terminal. | |
277 | .El | |
278 | .Sh SEE ALSO | |
279 | .Xr line 3 , | |
280 | .Xr termios 4 | |
281 | .Sh STANDARDS | |
282 | The | |
283 | .Nm cfgetispeed , | |
284 | .Nm cfsetispeed , | |
285 | .Nm cfgetospeed , | |
286 | .Nm cfsetospeed , | |
287 | .Nm tcgetattr | |
288 | and | |
289 | .Nm tcsetattr | |
290 | functions are expected to be compliant with the | |
291 | .St -p1003.1-88 | |
292 | specification. | |
293 | The | |
294 | .Nm cfmakeraw | |
295 | and | |
296 | .Nm cfsetspeed | |
297 | functions, | |
298 | as well as the | |
299 | .Li TCSASOFT | |
300 | option to the | |
301 | .Nm tcsetattr | |
302 | function are extensions to the | |
303 | .St -p1003.1-88 | |
304 | specification. |