xref: /csrg-svn/lib/libc/gen/tcsetattr.3 (revision 51199)
1*51199Smarc.\" Copyright (c) 1991 The Regents of the University of California.
2*51199Smarc.\" All rights reserved.
3*51199Smarc.\"
4*51199Smarc.\" %sccs.include.redist.roff%
5*51199Smarc.\"
6*51199Smarc.\"	@(#)tcsetattr.3	1.1 (Berkeley) 09/26/91
7*51199Smarc.\"
8*51199Smarc.Dd Jun 11, 1991
9*51199Smarc.Dt TCSETATTR 3
10*51199Smarc.Os
11*51199Smarc.Sh NAME
12*51199Smarc.Nm cfgetospeed,
13*51199Smarc.Nm cfsetospeed,
14*51199Smarc.Nm cfgetispeed,
15*51199Smarc.Nm cfsetospeed,
16*51199Smarc.Nm cfsetspeed,
17*51199Smarc.Nm cfmakeraw,
18*51199Smarc.Nm tcgetattr,
19*51199Smarc.Nm tcsetattr
20*51199Smarc.LP
21*51199Smarc.B "Baud Rate Functions"
22*51199Smarc.LP
23*51199SmarcFunctions:  cfgetispeed(), cfgetospeed(), cfsetispeed(), cfsetospeed(),
24*51199Smarccfsetspeed()
25*51199Smarc.LP
26*51199Smarc.B "Synopsis"
27*51199Smarc.LP
28*51199Smarc.nf
29*51199Smarc#include <termios.h>
30*51199Smarc
31*51199Smarcspeed_t cfgetospeed(const struct termios *termios_p);
32*51199Smarcint cfsetospeed(struct termios *termios_p, speed_t speed);
33*51199Smarc
34*51199Smarcspeed_t cfgetispeed(const struct termios *termios_p);
35*51199Smarcint cfsetispeed(struct termios *termios_p, speed_t speed);
36*51199Smarc
37*51199Smarcvoid cfsetspeed(struct termios *termios_p, speed_t speed);
38*51199Smarc
39*51199Smarcvoid cfmakeraw(struct termios *termios_p);
40*51199Smarc.fi
41*51199Smarc.LP
42*51199Smarc.B "Description"
43*51199Smarc.LP
44*51199SmarcThe following interfaces are provided for getting and setting the values
45*51199Smarcof the input and output baud rates in the termios structure.  The effects
46*51199Smarcon the terminal device described below do not become effective until the
47*51199Smarctcsetattr() function is successfully called, and not all errors are
48*51199Smarcdetected until tcsetattr() is called as well.
49*51199Smarc.PP
50*51199SmarcThe input and output baud rates are represented in the termios structure.
51*51199SmarcThe type speed_t is an unsigned integer.  The value of the integer
52*51199Smarccorresponds directly to the baud rate being represented, however,
53*51199Smarcthe following symbolic values are defined.
54*51199Smarc.nf
55*51199Smarc	/*
56*51199Smarc	 * Standard speeds
57*51199Smarc	 */
58*51199Smarc	#define B0	0
59*51199Smarc	#define B50	50
60*51199Smarc	#define B75	75
61*51199Smarc	#define B110	110
62*51199Smarc	#define B134	134
63*51199Smarc	#define B150	150
64*51199Smarc	#define B200	200
65*51199Smarc	#define B300	300
66*51199Smarc	#define B600	600
67*51199Smarc	#define B1200	1200
68*51199Smarc	#define	B1800	1800
69*51199Smarc	#define B2400	2400
70*51199Smarc	#define B4800	4800
71*51199Smarc	#define B9600	9600
72*51199Smarc	#define B19200	19200
73*51199Smarc	#define B38400	38400
74*51199Smarc	#ifndef _POSIX_SOURCE
75*51199Smarc	#define EXTA	19200
76*51199Smarc	#define EXTB	38400
77*51199Smarc	#endif  /*_POSIX_SOURCE */
78*51199Smarc.fi
79*51199Smarc.PP
80*51199SmarcThe termios_p argument is a pointer to a termios structure.
81*51199Smarc.PP
82*51199SmarcThe cfgetospeed() function shall return the output baud rate stored in
83*51199Smarcthe termios structure to which termios_p points.
84*51199Smarc.PP
85*51199SmarcThe cfgetispeed() function shall return the input baud rate stored in the
86*51199Smarctermios structure to which termios_p points.
87*51199Smarc.PP
88*51199SmarcThe cfsetospeed() function shall set the output baud rate stored in the
89*51199Smarctermios structure to which termios_p points.
90*51199Smarc.PP
91*51199SmarcThe cfsetispeed() function shall set the input baud rate stored in the
92*51199Smarctermios structure to which termios_p points.
93*51199Smarc.PP
94*51199SmarcThe cfsetspeed() function shall set the input and output baud rate
95*51199Smarcstored in the termios structure to which termios_p points.
96*51199Smarc.PP
97*51199SmarcCertain values for speeds that are set in the termios structure and
98*51199Smarcpassed to tcsetattr() have special meanings.  These are discussed under
99*51199Smarctcsetattr().
100*51199Smarc.PP
101*51199SmarcBoth cfsetispeed() and cfsetospeed() return a value of zero if successful
102*51199Smarcand -1 to indicate an error.
103*51199Smarc.PP
104*51199SmarcThe cfmakeraw() function shall set the flags stored in the termios
105*51199Smarcstructure in a state that disables all input and output processing,
106*51199Smarcgiving a "raw" i/o path.  Note that there is no "unraw" function.  This
107*51199Smarcis because there are a variety of processing options that could
108*51199Smarcbe re-enabled and the correct method is for an application to
109*51199Smarcsnapshot the current terminal state using tcgetattr(), setting
110*51199Smarcraw mode with cfmakeraw() and the subsequent tcsetattr(), and then
111*51199Smarcto revert to the previous terminal state with another tcsetattr()
112*51199Smarcusing the saved terminal state.
113*51199Smarc.LP
114*51199Smarc.B "General Terminal Interface Control Functions"
115*51199Smarc.LP
116*51199SmarcThe functions that are used to control the general terminal function are
117*51199Smarcdescribed in this section.
118*51199SmarcUnless otherwise noted for a specific command, these functions are
119*51199Smarcrestricted from use by background processes.  Attempts to perform these
120*51199Smarcoperations shall cause the process group to be sent a SIGTTOU signal.  If
121*51199Smarcthe calling process is blocking or ignoring SIGTTOU signals, the process
122*51199Smarcis allowed to perform the operation and the SIGTTOU signal is not sent.
123*51199Smarc.LP
124*51199Smarc.B "General Terminal Interface Control Functions"
125*51199Smarc.LP
126*51199SmarcIn all the functions, fildes is an open file descriptor.  However, the
127*51199Smarcfunctions affect the underlying terminal file, and not just the open file
128*51199Smarcdescription associated with the file descriptor.
129*51199Smarc.LP
130*51199Smarc.B "Get and Set State"
131*51199Smarc.LP
132*51199Smarc.B "Functions:  tcgetattr(), tcsetattr()"
133*51199Smarc.LP
134*51199Smarc.B "Synopsis"
135*51199Smarc.LP
136*51199Smarc.nf
137*51199Smarc#include <termios.h>
138*51199Smarcint tcgetattr(int fildes, struct termios *termios_p);
139*51199Smarc
140*51199Smarcint tcsetattr(int fildes, int optional_actions,
141*51199Smarc        const struct termios * termios_p);
142*51199Smarc.fi
143*51199Smarc.LP
144*51199Smarc.B "Description"
145*51199Smarc.LP
146*51199SmarcThe tcgetattr() function shall get the parameters associated with the
147*51199Smarcobject referred to by fildes and store them in the termios structure
148*51199Smarcreferenced by termios_p.  This function is allowed from a background
149*51199Smarcprocess; however, the terminal attributes may be subsequently changed by
150*51199Smarca foreground process.  If the terminal device supports different input
151*51199Smarcand output baud rates, the baud rates stored in the termios structure
152*51199Smarcreturned by tcgetattr() shall reflect the actual baud rates, even if they
153*51199Smarcare equal.  If differing baud rates are not supported, the rate returned
154*51199Smarcas the output baud rate shall be the actual baud rate.  The rate returned
155*51199Smarcas the input baud rate shall be either the number zero or the output rate.
156*51199Smarc.PP
157*51199SmarcThe tcsetattr() function shall set the parameters associated with the
158*51199Smarcterminal (unless support is required from the underlying hardware that is
159*51199Smarcnot available) from the termios structure referenced by termios_p as
160*51199Smarcfollows:
161*51199Smarc.nf
162*51199Smarc    (1)  If optional_actions is TCSANOW, the change shall occur
163*51199Smarc         immediately.
164*51199Smarc
165*51199Smarc    (2)  If optional_actions is TCSADRAIN, the change shall occur after
166*51199Smarc         all output written to fildes has been transmitted.  This
167*51199Smarc         function should be used when changing parameters that affect
168*51199Smarc         output.
169*51199Smarc
170*51199Smarc    (3)  If optional_actions is TCSAFLUSH, the change shall occur after
171*51199Smarc         all output written to the object referred to by fildes has been
172*51199Smarc         transmitted, and all input that has been received but not read
173*51199Smarc         shall be discarded before the change is made.
174*51199Smarc
175*51199Smarc    (4)  If TCSASOFT is or'ed in with the optional_actions, then the
176*51199Smarc	  value of the c_cflag and the speed will be ignored.
177*51199Smarc.fi
178*51199Smarc.PP
179*51199SmarcThe symbolic constants for the values of optional_actions are defined in
180*51199Smarc<termios.h>.
181*51199Smarc.PP
182*51199SmarcThe zero baud rate, B0, is used to terminate the connection.  If B0 is
183*51199Smarcspecified as the output speed when tcsetattr() is called, the modem
184*51199Smarccontrol lines shall no longer be asserted.  Normally, this will
185*51199Smarcdisconnect the line.
186*51199Smarc.PP
187*51199SmarcIf the input baud rate is equal to zero (the number) in the termios
188*51199Smarcstructure when tcsetattr() is called, the input baud rate will be changed
189*51199Smarcby tcsetattr() to the same value as that specified by the value of the
190*51199Smarcoutput baud rate, exactly as if the input rate had been set to the output
191*51199Smarcrate by cfsetispeed().  This usage of zero is obsolescent.
192*51199Smarc.PP
193*51199SmarcIf an attempt is made using tcsetattr() to set an unsupported baud rate,
194*51199Smarcbaud rates where the input and output baud rates differ and the hardware
195*51199Smarcdoes not support that combination, or other features not supported by the
196*51199Smarchardware, but if tcsetattr() was able to perform some of the requested
197*51199Smarcactions, it shall return success.  It shall set all the attributes that
198*51199Smarcthe implementation does support as requested and leave all the attributes
199*51199Smarcnot supported by the hardware unchanged.  If no part of the request can
200*51199Smarcbe honored, it shall return -1 and set errno to [EINVAL].  If the input
201*51199Smarcand output baud rates differ and are a combination that is not supported,
202*51199Smarcneither baud rate is changed.  A subsequent call to tcgetattr() shall
203*51199Smarcreturn the actual state of the terminal device [reflecting both the
204*51199Smarcchanges made and not made in the previous tcsetattr() call].  The
205*51199Smarctcsetattr() function shall not change the values in the termios structure
206*51199Smarcwhether or not it actually accepts them.
207*51199Smarc.PP
208*51199SmarcThe termios structure may have additional fields not defined by this
209*51199Smarcstandard.  The effect of the tcsetattr() function is undefined if the
210*51199Smarcvalue of the termios structure pointed to by termios_p was not derived
211*51199Smarcfrom the result of a call to tcgetattr() on fildes; a Strictly Conforming
212*51199SmarcPOSIX.1 Application shall modify only fields and flags defined by this
213*51199Smarcstandard between the call to tcgetattr() and tcsetattr(), leaving all
214*51199Smarcother fields and flags unmodified.
215*51199Smarc.PP
216*51199Smarc.B "Returns"
217*51199Smarc.LP
218*51199SmarcUpon successful completion, a value of zero is returned.  Otherwise, a
219*51199Smarcvalue of -1 is returned and errno is set to indicate the error.
220*51199Smarc.LP
221*51199Smarc.B "Errors"
222*51199Smarc.LP
223*51199SmarcIf any of the following conditions occur, the tcgetattr() function shall
224*51199Smarcreturn -1 and set errno to the corresponding value:
225*51199Smarc.nf
226*51199Smarc   [EBADF]       The fildes argument is not a valid file descriptor.
227*51199Smarc
228*51199Smarc   [ENOTTY]      The file associated with fildes is not a terminal.
229*51199Smarc.fi
230*51199Smarc.PP
231*51199SmarcIf any of the following conditions occur, the tcsetattr() function shall
232*51199Smarcreturn -1 and set errno to the corresponding value:
233*51199Smarc.nf
234*51199Smarc   [EBADF]       The fildes argument is not a valid file descriptor.
235*51199Smarc
236*51199Smarc   [EINTR]       A signal interrupted the tcsetattr() function.
237*51199Smarc
238*51199Smarc   [EINVAL]      The optional_actions argument is not a proper value, or
239*51199Smarc                 an attempt was made to change an attribute represented
240*51199Smarc                 in the termios structure to an unsupported value.
241*51199Smarc
242*51199Smarc   [ENOTTY]      The file associated with fildes is not a terminal.
243*51199Smarc.fi
244