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