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