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