1.\" $OpenBSD: tcsetattr.3,v 1.17 2014/01/21 03:15:45 schwarze Exp $ 2.\" 3.\" Copyright (c) 1991 The Regents of the University of California. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd $Mdocdate: January 21 2014 $ 31.Dt TCSETATTR 3 32.Os 33.Sh NAME 34.Nm cfgetispeed , 35.Nm cfsetispeed , 36.Nm cfgetospeed , 37.Nm cfsetospeed , 38.Nm cfsetspeed , 39.Nm cfmakeraw , 40.Nm tcgetattr , 41.Nm tcsetattr 42.Nd manipulating the termios structure 43.Sh SYNOPSIS 44.In termios.h 45.Ft speed_t 46.Fn cfgetispeed "const struct termios *tp" 47.Ft int 48.Fn cfsetispeed "struct termios *tp" "speed_t speed" 49.Ft speed_t 50.Fn cfgetospeed "const struct termios *tp" 51.Ft int 52.Fn cfsetospeed "struct termios *tp" "speed_t speed" 53.Ft int 54.Fn cfsetspeed "struct termios *tp" "speed_t speed" 55.Ft void 56.Fn cfmakeraw "struct termios *tp" 57.Ft int 58.Fn tcgetattr "int fd" "struct termios *tp" 59.Ft int 60.Fn tcsetattr "int fd" "int action" "const struct termios *tp" 61.Sh DESCRIPTION 62The 63.Fn cfmakeraw , 64.Fn tcgetattr , 65and 66.Fn tcsetattr 67functions are provided for getting and setting the 68.Li termios 69structure. 70.Pp 71The 72.Fn cfgetispeed , 73.Fn cfsetispeed , 74.Fn cfgetospeed , 75.Fn cfsetospeed , 76and 77.Fn cfsetspeed 78functions are provided for getting and setting the baud rate values in 79the 80.Li termios 81structure. 82The effects of the functions on the terminal as described below 83do not become effective, nor are all errors detected, until the 84.Fn tcsetattr 85function is called. 86Certain values for baud rates set in the 87.Li termios 88structure and passed to 89.Fn tcsetattr 90have special meanings. 91These are discussed in the portion of the manual page that describes the 92.Fn tcsetattr 93function. 94.Sh GETTING AND SETTING THE BAUD RATE 95The input and output baud rates are found in the 96.Li termios 97structure. 98The unsigned integer 99.Li speed_t 100is typedef'd in the include file 101.In termios.h . 102On 103.Ox , 104the value of the integer corresponds directly to the baud rate being 105represented. 106However, this is not true of all systems and new code should use the 107symbolic value for maximum portability. 108.Bd -literal -offset indent 109#define B0 0 110#define B50 50 111#define B75 75 112#define B110 110 113#define B134 134 114#define B150 150 115#define B200 200 116#define B300 300 117#define B600 600 118#define B1200 1200 119#define B1800 1800 120#define B2400 2400 121#define B4800 4800 122#define B9600 9600 123#define B19200 19200 124#define B38400 38400 125#ifndef _POSIX_SOURCE 126#define EXTA 19200 127#define EXTB 38400 128#endif /*_POSIX_SOURCE */ 129.Ed 130.Pp 131The 132.Fn cfgetispeed 133function returns the input baud rate in the 134.Li termios 135structure referenced by 136.Fa tp . 137.Pp 138The 139.Fn cfsetispeed 140function sets the input baud rate in the 141.Li termios 142structure referenced by 143.Fa tp 144to 145.Fa speed . 146.Pp 147The 148.Fn cfgetospeed 149function returns the output baud rate in the 150.Li termios 151structure referenced by 152.Fa tp . 153.Pp 154The 155.Fn cfsetospeed 156function sets the output baud rate in the 157.Li termios 158structure referenced by 159.Fa tp 160to 161.Fa speed . 162.Pp 163The 164.Fn cfsetspeed 165function sets both the input and output baud rate in the 166.Li termios 167structure referenced by 168.Fa tp 169to 170.Fa speed . 171.Pp 172Upon successful completion, the functions 173.Fn cfsetispeed , 174.Fn cfsetospeed , 175and 176.Fn cfsetspeed 177return a value of 0. 178Otherwise, a value of \-1 is returned and the global variable 179.Va errno 180is set to indicate the error. 181.Sh GETTING AND SETTING THE TERMIOS STATE 182This section describes the functions that are used to control the general 183terminal interface. 184Unless otherwise noted for a specific command, these functions are restricted 185from use by background processes. 186Attempts to perform these operations shall cause the process group to be sent 187a 188.Dv SIGTTOU 189signal. 190If the calling process is blocking or ignoring 191.Dv SIGTTOU 192signals, the process 193is allowed to perform the operation and the 194.Dv SIGTTOU 195signal is not sent. 196.Pp 197In all the functions, although 198.Fa fd 199is an open file descriptor, the functions affect the underlying terminal 200file, not just the open file description associated with the particular 201file descriptor. 202.Pp 203The 204.Fn cfmakeraw 205function sets the flags stored in the 206.Li termios 207structure to a state disabling 208all input and output processing, giving a 209.Dq raw I/O path . 210It should be noted that there is no function to reverse this effect. 211This is because there are a variety of processing options that could be 212re-enabled and the correct method is for an application to snapshot the 213current terminal state using the function 214.Fn tcgetattr , 215setting raw mode with 216.Fn cfmakeraw 217and the subsequent 218.Fn tcsetattr , 219and then using another 220.Fn tcsetattr 221with the saved state to revert to the previous terminal state. 222.Pp 223The 224.Fn tcgetattr 225function copies the parameters associated with the terminal referenced 226by 227.Fa fd 228in the 229.Li termios 230structure referenced by 231.Fa tp . 232This function is allowed from a background process, although the terminal 233attributes may be subsequently changed by a foreground process. 234.Pp 235The 236.Fn tcsetattr 237function sets the parameters associated with the terminal from the 238.Li termios 239structure referenced by 240.Fa tp . 241The 242.Fa action 243field is created by 244.Tn OR Ns 'ing 245the following values, as specified in the include file 246.In termios.h . 247.Bl -tag -width "TCSADRAIN" 248.It Dv TCSANOW 249The change occurs immediately. 250.It Dv TCSADRAIN 251The change occurs after all output written to 252.Fa fd 253has been transmitted to the terminal. 254This value of 255.Fa action 256should be used when changing parameters that affect output. 257.It Dv TCSAFLUSH 258The change occurs after all output written to 259.Fa fd 260has been transmitted to the terminal. 261Additionally, any input that has been received but not read is discarded. 262.It Dv TCSASOFT 263If this value is 264.Tn OR Ns 'ed 265into the 266.Fa action 267value, the values of the 268.Fa c_cflag , 269.Fa c_ispeed , 270and 271.Fa c_ospeed 272fields are ignored. 273.El 274.Pp 275The 0 baud rate is used to terminate the connection. 276If 0 is specified as the output speed to the function 277.Fn tcsetattr , 278modem control will no longer be asserted on the terminal, disconnecting 279the terminal. 280.Pp 281If zero is specified as the input speed to the function 282.Fn tcsetattr , 283the input baud rate will be set to the same value as that specified by 284the output baud rate. 285.Sh RETURN VALUES 286If 287.Fn tcsetattr 288is unable to make any of the requested changes, it returns \-1 and 289sets 290.Va errno . 291Otherwise, it makes all of the requested changes it can. 292If the specified input and output baud rates differ and are a combination 293that is not supported, neither baud rate is changed. 294.Sh ERRORS 295Upon successful completion, the functions 296.Fn tcgetattr 297and 298.Fn tcsetattr 299return a value of 0. 300Otherwise, they 301return \-1 and the global variable 302.Va errno 303is set to indicate the error, as follows: 304.Bl -tag -width Er 305.It Bq Er EBADF 306The 307.Fa fd 308argument to 309.Fn tcgetattr 310or 311.Fn tcsetattr 312was not a valid file descriptor. 313.It Bq Er EINTR 314The 315.Fn tcsetattr 316function was interrupted by a signal. 317.It Bq Er EINVAL 318The 319.Fa action 320argument to the 321.Fn tcsetattr 322function was not valid, or an attempt was made to change an attribute 323represented in the 324.Li termios 325structure to an unsupported value. 326.It Bq Er ENOTTY 327The file associated with the 328.Fa fd 329argument to 330.Fn tcgetattr 331or 332.Fn tcsetattr 333is not a terminal. 334.El 335.Sh SEE ALSO 336.Xr tcsendbreak 3 , 337.Xr termios 4 338.Sh STANDARDS 339The 340.Fn cfgetispeed , 341.Fn cfsetispeed , 342.Fn cfgetospeed , 343.Fn cfsetospeed , 344.Fn tcgetattr , 345and 346.Fn tcsetattr 347functions are expected to be compliant with the 348.St -p1003.1-88 349specification. 350The 351.Fn cfmakeraw 352and 353.Fn cfsetspeed 354functions, 355as well as the 356.Dv TCSASOFT 357option to the 358.Fn tcsetattr 359function are extensions to the 360.St -p1003.1-88 361specification. 362