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