xref: /csrg-svn/lib/libc/gen/tcsetattr.3 (revision 52295)
151199Smarc.\" Copyright (c) 1991 The Regents of the University of California.
251199Smarc.\" All rights reserved.
351199Smarc.\"
451199Smarc.\" %sccs.include.redist.roff%
551199Smarc.\"
6*52295Sbostic.\"	@(#)tcsetattr.3	5.1 (Berkeley) 02/03/92
751199Smarc.\"
8*52295Sbostic.Dd ""
951199Smarc.Dt TCSETATTR 3
1051199Smarc.Os
1151199Smarc.Sh NAME
12*52295Sbostic.Nm cfgetispeed ,
13*52295Sbostic.Nm cfsetispeed ,
14*52295Sbostic.Nm cfgetospeed ,
15*52295Sbostic.Nm cfsetospeed ,
16*52295Sbostic.Nm cfsetspeed ,
17*52295Sbostic.Nm cfmakeraw ,
18*52295Sbostic.Nm tcgetattr ,
1951199Smarc.Nm tcsetattr
20*52295Sbostic.Nd manipulating the termios structure
21*52295Sbostic.Sh SYNOPSIS
22*52295Sbostic.Fd #include <termios.h>
23*52295Sbostic.Ft speed_t
24*52295Sbostic.Fn cfgetispeed "struct termios *t"
25*52295Sbostic.Ft int
26*52295Sbostic.Fn cfsetispeed "struct termios *t" "speed_t speed"
27*52295Sbostic.Ft speed_t
28*52295Sbostic.Fn cfgetospeed "struct termios *t"
29*52295Sbostic.Ft int
30*52295Sbostic.Fn cfsetospeed "struct termios *t" "speed_t speed"
31*52295Sbostic.Ft void
32*52295Sbostic.Fn cfsetspeed "struct termios *t" "speed_t speed"
33*52295Sbostic.Ft void
34*52295Sbostic.Fn cfmakeraw "struct termios *t"
35*52295Sbostic.Ft int
36*52295Sbostic.Fn tcgetattr "int fd" "struct termios *t"
37*52295Sbostic.Ft int
38*52295Sbostic.Fn tcsetattr "int fd" "int action" "struct termios *t"
39*52295Sbostic.Sh DESCRIPTION
40*52295SbosticThe
41*52295Sbostic.Nm cfmakeraw ,
42*52295Sbostic.Nm tcgetattr
43*52295Sbosticand
44*52295Sbostic.Nm tcsetattr
45*52295Sbosticfunctions are provided for getting and setting the termios structure.
46*52295Sbostic.Pp
47*52295SbosticThe
48*52295Sbostic.Nm cfgetispeed ,
49*52295Sbostic.Nm cfsetispeed ,
50*52295Sbostic.Nm cfgetospeed ,
51*52295Sbostic.Nm cfsetospeed
52*52295Sbosticand
53*52295Sbostic.Nm cfsetspeed
54*52295Sbosticfunctions are provided for getting and setting the baud rate values in
55*52295Sbosticthe termios structure.
56*52295SbosticThe effects of the functions on the terminal as described below
57*52295Sbosticdo not become effective, nor are all errors detected, until the
58*52295Sbostic.Nm tcsetattr
59*52295Sbosticfunction is called.
60*52295SbosticCertain values for baud rates set in the termios structure and passed to
61*52295Sbostic.Nm tcsetattr
62*52295Sbostichave special meanings.
63*52295SbosticThese are discussed in the portion of the manual page that describes the
64*52295Sbostic.Nm tcsetattr
65*52295Sbosticfunction.
66*52295Sbostic.Sh GETTING AND SETTING THE BAUD RATE
67*52295SbosticThe input and output baud rates are found in the termios structure.
68*52295SbosticThe unsigned integer
69*52295Sbostic.Li speed_t
70*52295Sbosticis typdef'd in the include file
71*52295Sbostic.Aq Pa termios.h .
72*52295SbosticThe value of the integer corresponds directly to the baud rate being
73*52295Sbosticrepresented, however, the following symbolic values are defined.
74*52295Sbostic.Bd -literal
75*52295Sbostic#define B0	0
76*52295Sbostic#define B50	50
77*52295Sbostic#define B75	75
78*52295Sbostic#define B110	110
79*52295Sbostic#define B134	134
80*52295Sbostic#define B150	150
81*52295Sbostic#define B200	200
82*52295Sbostic#define B300	300
83*52295Sbostic#define B600	600
84*52295Sbostic#define B1200	1200
85*52295Sbostic#define	B1800	1800
86*52295Sbostic#define B2400	2400
87*52295Sbostic#define B4800	4800
88*52295Sbostic#define B9600	9600
89*52295Sbostic#define B19200	19200
90*52295Sbostic#define B38400	38400
91*52295Sbostic#ifndef _POSIX_SOURCE
92*52295Sbostic#define EXTA	19200
93*52295Sbostic#define EXTB	38400
94*52295Sbostic#endif  /*_POSIX_SOURCE */
95*52295Sbostic.Ed
96*52295Sbostic.Pp
97*52295SbosticThe
98*52295Sbostic.Nm cfgetispeed
99*52295Sbosticfunction returns the input baud rate in the termios structure referenced by
100*52295Sbostic.Fa tp .
101*52295Sbostic.Pp
102*52295SbosticThe
103*52295Sbostic.Nm cfsetispeed
104*52295Sbosticfunction sets the input baud rate in the termios structure referenced by
105*52295Sbostic.Fa tp
106*52295Sbosticto
107*52295Sbostic.Fa speed .
108*52295Sbostic.Pp
109*52295SbosticThe
110*52295Sbostic.Nm cfgetospeed
111*52295Sbosticfunction returns the output baud rate in the termios structure referenced by
112*52295Sbostic.Fa tp .
113*52295Sbostic.Pp
114*52295SbosticThe
115*52295Sbostic.Nm cfsetospeed
116*52295Sbosticfunction sets the output baud rate in the termios structure referenced by
117*52295Sbostic.Fa tp
118*52295Sbosticto
119*52295Sbostic.Fa speed .
120*52295Sbostic.Pp
121*52295SbosticThe
122*52295Sbostic.Nm cfsetspeed
123*52295Sbosticfunction sets both the input and output baud rate in the termios structure
124*52295Sbosticreferenced by
125*52295Sbostic.Fa tp
126*52295Sbosticto
127*52295Sbostic.Fa speed .
128*52295Sbostic.Pp
129*52295SbosticUpon successful completion, the functions
130*52295Sbostic.Nm cfsetispeed ,
131*52295Sbostic.Nm cfsetospeed ,
132*52295Sbosticand
133*52295Sbostic.Nm cfsetspeed
134*52295Sbosticreturn a value of 0.
135*52295SbosticOtherwise, a value of -1 is returned and the global variable
136*52295Sbostic.Va errno
137*52295Sbosticis set to indicate the error.
138*52295Sbostic.Sh GETTING AND SETTING THE TERMIOS STATE
139*52295SbosticThis section describes the functions that are used to control the general
140*52295Sbosticterminal interface.
141*52295SbosticUnless otherwise noted for a specific command, these functions are restricted
142*52295Sbosticfrom use by background processes.
143*52295SbosticAttempts to perform these operations shall cause the process group to be sent
144*52295Sbostica SIGTTOU signal.
145*52295SbosticIf the calling process is blocking or ignoring SIGTTOU signals, the process
14651199Smarcis allowed to perform the operation and the SIGTTOU signal is not sent.
147*52295Sbostic.Pp
148*52295SbosticIn all the functions, although
149*52295Sbostic.Fa fd
150*52295Sbosticis an open file descriptor, the functions affect the underlying terminal
151*52295Sbosticfile, not just the open file description associated with the particular
152*52295Sbosticfile descriptor.
153*52295Sbostic.Pp
154*52295SbosticThe
155*52295Sbostic.Nm cfmakeraw
156*52295Sbosticfunction sets the flags stored in the termios structure to a state disabling
157*52295Sbosticall input and output processing, giving a
158*52295Sbostic.Dq raw I/O path.
159*52295SbosticIt should be noted that there is no function to reverse this effect.
160*52295SbosticThis is because there are a variety of processing options that could be
161*52295Sbosticre-enabled and the correct method is for an application to snapshot the
162*52295Sbosticcurrent terminal state using the function
163*52295Sbostic.Nm tcgetattr ,
164*52295Sbosticsetting raw mode with
165*52295Sbostic.Nm cfmakeraw
166*52295Sbosticand the subsequent
167*52295Sbostic.Nm tcsetattr ,
168*52295Sbosticand then using another
169*52295Sbostic.Nm tcsetattr
170*52295Sbosticwith the saved state to revert to the previous terminal state.
171*52295Sbostic.Pp
172*52295SbosticThe
173*52295Sbostic.Nm tcgetattr
174*52295Sbosticfunction copies the parameters associated with the terminal referenced
175*52295Sbosticby
176*52295Sbostic.Fa fd
177*52295Sbosticin the termios structure referenced by
178*52295Sbostic.Fa tp .
179*52295SbosticThis function is allowed from a background process, however, the terminal
180*52295Sbosticattributes may be subsequently changed by a foreground process.
181*52295Sbostic.Pp
182*52295SbosticThe
183*52295Sbostic.Nm tcsetattr
184*52295Sbosticfunction sets the parameters associated with the terminal from the
185*52295Sbostictermios structure referenced by
186*52295Sbostic.Fa tp .
187*52295SbosticThe
188*52295Sbostic.Fa action
189*52295Sbosticfield is created by
190*52295Sbostic.Em or Ns 'ing
191*52295Sbosticthe following values, as specified in the include file
192*52295Sbostic.Aq Pa termios.h .
193*52295Sbostic.Bl -tag -width "TCSADRAIN"
194*52295Sbostic.It Fa TCSANOW
195*52295SbosticThe change occurs immediately.
196*52295Sbostic.It Fa TCSADRAIN
197*52295SbosticThe change occurs after all output written to
198*52295Sbostic.Fa fd
199*52295Sbostichas been transmitted to the terminal.
200*52295SbosticThis value of
201*52295Sbostic.Fa action
202*52295Sbosticshould be used when changing parameters that affect output.
203*52295Sbostic.It Fa TCSAFLUSH
204*52295SbosticThe change occurs after all output written to
205*52295Sbostic.Fa fd
206*52295Sbostichas been transmitted to the terminal
207*52295SbosticAdditionally, any input that has been received but not read is discarded.
208*52295Sbostic.It Fa TCSASOFT
209*52295SbosticIf this value is
210*52295Sbostic.Em or Ns 'ed
211*52295Sbosticinto the
212*52295Sbostic.Fa action
213*52295Sbosticvalue, the values of the
214*52295Sbostic.Em c_cflag ,
215*52295Sbostic.Em c_ispeed ,
216*52295Sbosticand
217*52295Sbostic.Em c_ospeed
218*52295Sbosticfields are ignored.
219*52295Sbostic.El
220*52295Sbostic.Pp
221*52295SbosticThe 0 baud rate is used to terminate the connection.
222*52295SbosticIf 0 is specified as the output speed to the function
223*52295Sbostic.Nm tcsetattr ,
224*52295Sbosticmodem control will no longer be asserted on the terminal, disconnecting
225*52295Sbosticthe terminal.
226*52295Sbostic.Pp
227*52295SbosticIf zero is specified as the input speed to the function
228*52295Sbostic.Nm tcsetattr ,
229*52295Sbosticthe input baud rate will be set to the same value as that specified by
230*52295Sbosticthe output baud rate.
231*52295Sbostic.Pp
232*52295SbosticIf
233*52295Sbostic.Nm tcsetattr
234*52295Sbosticis unable able to make any of the requested changes, it returns -1 and
235*52295Sbosticsets errno.
236*52295SbosticOtherwise, it makes all of the requested changes it can.
237*52295SbosticIf the specified input and output baud rates differ and are a combination
238*52295Sbosticthat is not supported, neither baud rate is changed.
239*52295Sbostic.Pp
240*52295SbosticUpon successful completion, the functions
241*52295Sbostic.Nm tcgetattr
242*52295Sbosticand
243*52295Sbostic.Nm tcsetattr
244*52295Sbosticreturn a value of 0.
245*52295SbosticOtherwise, they
246*52295Sbosticreturn -1 and the global variable
247*52295Sbostic.Va errno
248*52295Sbosticis set to indicate the error, as follows:
249*52295Sbostic.Bl -tag -width Er
250*52295Sbostic.It Bq Er EBADF
251*52295SbosticThe
252*52295Sbostic.Fa fd
253*52295Sbosticargument to
254*52295Sbostic.Nm tcgetattr
255*52295Sbosticor
256*52295Sbostic.Nm tcsetattr
257*52295Sbosticwas not a valid file descriptor.
258*52295Sbostic.It Bq Er EINTR
259*52295SbosticThe
260*52295Sbostic.Nm tcsetattr
261*52295Sbosticfunction was interrupted by a signal.
262*52295Sbostic.It Bq Er EINVAL
263*52295SbosticThe
264*52295Sbostic.Fa action
265*52295Sbosticargument to the
266*52295Sbostic.Nm tcsetattr
267*52295Sbosticfunction was not valid, or an attempt was made to change an attribute
268*52295Sbosticrepresented in the termios structure to an unsupported value.
269*52295Sbostic.It Bq Er ENOTTY
270*52295SbosticThe file associated with the
271*52295Sbostic.Fa fd
272*52295Sbosticargument to
273*52295Sbostic.Nm tcgetattr
274*52295Sbosticor
275*52295Sbostic.Nm tcsetattr
276*52295Sbosticis not a terminal.
277*52295Sbostic.El
278*52295Sbostic.Sh SEE ALSO
279*52295Sbostic.Xr line 3 ,
280*52295Sbostic.Xr termios 4
281*52295Sbostic.Sh STANDARDS
282*52295SbosticThe
283*52295Sbostic.Nm cfgetispeed ,
284*52295Sbostic.Nm cfsetispeed ,
285*52295Sbostic.Nm cfgetospeed ,
286*52295Sbostic.Nm cfsetospeed ,
287*52295Sbostic.Nm tcgetattr
288*52295Sbosticand
289*52295Sbostic.Nm tcsetattr
290*52295Sbosticfunctions are expected to be compliant with the
291*52295Sbostic.St -p1003.1-88
292*52295Sbosticspecification.
293*52295SbosticThe
294*52295Sbostic.Nm cfmakeraw
295*52295Sbosticand
296*52295Sbostic.Nm cfsetspeed
297*52295Sbosticfunctions,
298*52295Sbosticas well as the
299*52295Sbostic.Li TCSASOFT
300*52295Sbosticoption to the
301*52295Sbostic.Nm tcsetattr
302*52295Sbosticfunction are extensions to the
303*52295Sbostic.St -p1003.1-88
304*52295Sbosticspecification.
305