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