lib/libc/gen/tcsetattr.3

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