]>
Commit | Line | Data |
---|---|---|
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. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)tcsetattr.3 8.3 (Berkeley) 1/2/94 | |
33 | .\" $FreeBSD: src/lib/libc/gen/tcsetattr.3,v 1.9 2001/10/01 16:08:51 ru Exp $ | |
34 | .\" | |
35 | .Dd January 2, 1994 | |
36 | .Dt TCSETATTR 3 | |
37 | .Os | |
38 | .Sh NAME | |
39 | .Nm cfgetispeed , | |
40 | .Nm cfsetispeed , | |
41 | .Nm cfgetospeed , | |
42 | .Nm cfsetospeed , | |
43 | .Nm cfsetspeed , | |
44 | .Nm cfmakeraw , | |
45 | .Nm tcgetattr , | |
46 | .Nm tcsetattr | |
47 | .Nd manipulating the termios structure | |
48 | .Sh LIBRARY | |
49 | .Lb libc | |
50 | .Sh SYNOPSIS | |
51 | .In termios.h | |
52 | .Ft speed_t | |
53 | .Fn cfgetispeed "const struct termios *t" | |
54 | .Ft int | |
55 | .Fn cfsetispeed "struct termios *t" "speed_t speed" | |
56 | .Ft speed_t | |
57 | .Fn cfgetospeed "const struct termios *t" | |
58 | .Ft int | |
59 | .Fn cfsetospeed "struct termios *t" "speed_t speed" | |
60 | .Ft int | |
61 | .Fn cfsetspeed "struct termios *t" "speed_t speed" | |
62 | .Ft void | |
63 | .Fn cfmakeraw "struct termios *t" | |
64 | .Ft int | |
65 | .Fn tcgetattr "int fd" "struct termios *t" | |
66 | .Ft int | |
67 | .Fn tcsetattr "int fd" "int action" "const struct termios *t" | |
68 | .Sh DESCRIPTION | |
69 | The | |
70 | .Fn cfmakeraw , | |
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 typdef'd in the include file | |
100 | .Aq Pa termios.h . | |
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 | |
114 | #define B1800 1800 | |
115 | #define B2400 2400 | |
116 | #define B4800 4800 | |
117 | #define B9600 9600 | |
118 | #define B19200 19200 | |
119 | #define B38400 38400 | |
120 | #ifndef _POSIX_SOURCE | |
121 | #define EXTA 19200 | |
122 | #define EXTB 38400 | |
123 | #endif /*_POSIX_SOURCE */ | |
124 | .Ed | |
125 | .Pp | |
126 | The | |
127 | .Fn cfgetispeed | |
128 | function returns the input baud rate in the termios structure referenced by | |
129 | .Fa tp . | |
130 | .Pp | |
131 | The | |
132 | .Fn cfsetispeed | |
133 | function sets the input baud rate in the termios structure referenced by | |
134 | .Fa tp | |
135 | to | |
136 | .Fa speed . | |
137 | .Pp | |
138 | The | |
139 | .Fn cfgetospeed | |
140 | function returns the output baud rate in the termios structure referenced by | |
141 | .Fa tp . | |
142 | .Pp | |
143 | The | |
144 | .Fn cfsetospeed | |
145 | function sets the output baud rate in the termios structure referenced by | |
146 | .Fa tp | |
147 | to | |
148 | .Fa speed . | |
149 | .Pp | |
150 | The | |
151 | .Fn cfsetspeed | |
152 | function sets both the input and output baud rate in the termios structure | |
153 | referenced by | |
154 | .Fa tp | |
155 | to | |
156 | .Fa speed . | |
157 | .Pp | |
158 | Upon successful completion, the functions | |
159 | .Fn cfsetispeed , | |
160 | .Fn cfsetospeed , | |
161 | and | |
162 | .Fn cfsetspeed | |
163 | return a value of 0. | |
164 | Otherwise, a value of -1 is returned and the global variable | |
165 | .Va errno | |
166 | is set to indicate the error. | |
167 | .Sh GETTING AND SETTING THE TERMIOS STATE | |
168 | This section describes the functions that are used to control the general | |
169 | terminal interface. | |
170 | Unless otherwise noted for a specific command, these functions are restricted | |
171 | from use by background processes. | |
172 | Attempts to perform these operations shall cause the process group to be sent | |
173 | a SIGTTOU signal. | |
174 | If the calling process is blocking or ignoring SIGTTOU signals, the process | |
175 | is allowed to perform the operation and the SIGTTOU signal is not sent. | |
176 | .Pp | |
177 | In all the functions, although | |
178 | .Fa fd | |
179 | is an open file descriptor, the functions affect the underlying terminal | |
180 | file, not just the open file description associated with the particular | |
181 | file descriptor. | |
182 | .Pp | |
183 | The | |
184 | .Fn cfmakeraw | |
185 | function sets the flags stored in the termios structure to a state disabling | |
186 | all input and output processing, giving a | |
187 | .Dq raw I/O path . | |
188 | It should be noted that there is no function to reverse this effect. | |
189 | This is because there are a variety of processing options that could be | |
190 | re-enabled and the correct method is for an application to snapshot the | |
191 | current terminal state using the function | |
192 | .Fn tcgetattr , | |
193 | setting raw mode with | |
194 | .Fn cfmakeraw | |
195 | and the subsequent | |
196 | .Fn tcsetattr , | |
197 | and then using another | |
198 | .Fn tcsetattr | |
199 | with the saved state to revert to the previous terminal state. | |
200 | .Pp | |
201 | The | |
202 | .Fn tcgetattr | |
203 | function copies the parameters associated with the terminal referenced | |
204 | by | |
205 | .Fa fd | |
206 | in the termios structure referenced by | |
207 | .Fa tp . | |
208 | This function is allowed from a background process, however, the terminal | |
209 | attributes may be subsequently changed by a foreground process. | |
210 | .Pp | |
211 | The | |
212 | .Fn tcsetattr | |
213 | function sets the parameters associated with the terminal from the | |
214 | termios structure referenced by | |
215 | .Fa tp . | |
216 | The | |
217 | .Fa action | |
218 | field is created by | |
219 | .Em or Ns 'ing | |
220 | the following values, as specified in the include file | |
221 | .Aq Pa termios.h . | |
222 | .Bl -tag -width "TCSADRAIN" | |
223 | .It Fa TCSANOW | |
224 | The change occurs immediately. | |
225 | .It Fa TCSADRAIN | |
226 | The change occurs after all output written to | |
227 | .Fa fd | |
228 | has been transmitted to the terminal. | |
229 | This value of | |
230 | .Fa action | |
231 | should be used when changing parameters that affect output. | |
232 | .It Fa TCSAFLUSH | |
233 | The change occurs after all output written to | |
234 | .Fa fd | |
235 | has been transmitted to the terminal. | |
236 | Additionally, any input that has been received but not read is discarded. | |
237 | .It Fa TCSASOFT | |
238 | If this value is | |
239 | .Em or Ns 'ed | |
240 | into the | |
241 | .Fa action | |
242 | value, the values of the | |
243 | .Em c_cflag , | |
244 | .Em c_ispeed , | |
245 | and | |
246 | .Em c_ospeed | |
247 | fields are ignored. | |
248 | .El | |
249 | .Pp | |
250 | The 0 baud rate is used to terminate the connection. | |
251 | If 0 is specified as the output speed to the function | |
252 | .Fn tcsetattr , | |
253 | modem control will no longer be asserted on the terminal, disconnecting | |
254 | the terminal. | |
255 | .Pp | |
256 | If zero is specified as the input speed to the function | |
257 | .Fn tcsetattr , | |
258 | the input baud rate will be set to the same value as that specified by | |
259 | the output baud rate. | |
260 | .Pp | |
261 | If | |
262 | .Fn tcsetattr | |
263 | is unable to make any of the requested changes, it returns -1 and | |
264 | sets errno. | |
265 | Otherwise, it makes all of the requested changes it can. | |
266 | If the specified input and output baud rates differ and are a combination | |
267 | that is not supported, neither baud rate is changed. | |
268 | .Pp | |
269 | Upon successful completion, the functions | |
270 | .Fn tcgetattr | |
271 | and | |
272 | .Fn tcsetattr | |
273 | return a value of 0. | |
274 | Otherwise, they | |
275 | return -1 and the global variable | |
276 | .Va errno | |
277 | is set to indicate the error, as follows: | |
278 | .Bl -tag -width Er | |
279 | .It Bq Er EBADF | |
280 | The | |
281 | .Fa fd | |
282 | argument to | |
283 | .Fn tcgetattr | |
284 | or | |
285 | .Fn tcsetattr | |
286 | was not a valid file descriptor. | |
287 | .It Bq Er EINTR | |
288 | The | |
289 | .Fn tcsetattr | |
290 | function was interrupted by a signal. | |
291 | .It Bq Er EINVAL | |
292 | The | |
293 | .Fa action | |
294 | argument to the | |
295 | .Fn tcsetattr | |
296 | function was not valid, or an attempt was made to change an attribute | |
297 | represented in the termios structure to an unsupported value. | |
298 | .It Bq Er ENOTTY | |
299 | The file associated with the | |
300 | .Fa fd | |
301 | argument to | |
302 | .Fn tcgetattr | |
303 | or | |
304 | .Fn tcsetattr | |
305 | is not a terminal. | |
306 | .El | |
307 | .Sh SEE ALSO | |
308 | .Xr tcsendbreak 3 , | |
309 | .Xr termios 4 | |
310 | .Sh STANDARDS | |
311 | The | |
312 | .Fn cfgetispeed , | |
313 | .Fn cfsetispeed , | |
314 | .Fn cfgetospeed , | |
315 | .Fn cfsetospeed , | |
316 | .Fn tcgetattr | |
317 | and | |
318 | .Fn tcsetattr | |
319 | functions are expected to be compliant with the | |
320 | .St -p1003.1-88 | |
321 | specification. | |
322 | The | |
323 | .Fn cfmakeraw | |
324 | and | |
325 | .Fn cfsetspeed | |
326 | functions, | |
327 | as well as the | |
328 | .Li TCSASOFT | |
329 | option to the | |
330 | .Fn tcsetattr | |
331 | function are extensions to the | |
332 | .St -p1003.1-88 | |
333 | specification. |