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