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 December 10, 2017
  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 cfmakesane ,
  42 .Nm tcgetattr ,
  43 .Nm tcsetattr
  44 .Nd manipulating the termios structure
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In termios.h
  49 .Ft speed_t
  50 .Fn cfgetispeed "const struct termios *t"
  51 .Ft int
  52 .Fn cfsetispeed "struct termios *t" "speed_t speed"
  53 .Ft speed_t
  54 .Fn cfgetospeed "const struct termios *t"
  55 .Ft int
  56 .Fn cfsetospeed "struct termios *t" "speed_t speed"
  57 .Ft int
  58 .Fn cfsetspeed "struct termios *t" "speed_t speed"
  59 .Ft void
  60 .Fn cfmakeraw "struct termios *t"
  61 .Ft void
  62 .Fn cfmakesane "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
  68 The
  69 .Fn cfmakeraw ,
  70 .Fn cfmakesane ,
  71 .Fn tcgetattr
  72 and
  73 .Fn tcsetattr
  74 functions are provided for getting and setting the termios structure.
  75 .Pp
  76 The
  77 .Fn cfgetispeed ,
  78 .Fn cfsetispeed ,
  79 .Fn cfgetospeed ,
  80 .Fn cfsetospeed
  81 and
  82 .Fn cfsetspeed
  83 functions are provided for getting and setting the baud rate values in
  84 the termios structure.
  85 The effects of the functions on the terminal as described below
  86 do not become effective, nor are all errors detected, until the
  87 .Fn tcsetattr
  88 function is called.
  89 Certain values for baud rates set in the termios structure and passed to
  90 .Fn tcsetattr
  91 have special meanings.
  92 These are discussed in the portion of the manual page that describes the
  93 .Fn tcsetattr
  94 function.
  95 .Sh GETTING AND SETTING THE BAUD RATE
  96 The input and output baud rates are found in the termios structure.
  97 The unsigned integer
  98 .Li speed_t
  99 is typedef'd in the include file
 100 .In termios.h .
 101 The value of the integer corresponds directly to the baud rate being
 102 represented, however, the following symbolic values are defined.
 103 .Bd -literal
 104 #define B0      0
 105 #define B50     50
 106 #define B75     75
 107 #define B110    110
 108 #define B134    134
 109 #define B150    150
 110 #define B200    200
 111 #define B300    300
 112 #define B600    600
 113 #define B1200   1200
 114 #define B1800   1800
 115 #define B2400   2400
 116 #define B4800   4800
 117 #define B9600   9600
 118 #define B19200  19200
 119 #define B38400  38400
 120 #if __BSD_VISIBLE
 121 #define B7200   7200
 122 #define B14400  14400
 123 #define B28800  28800
 124 #define B57600  57600
 125 #define B76800  76800
 126 #define B115200 115200
 127 #define B230400 230400
 128 #define EXTA    19200
 129 #define EXTB    38400
 130 #endif  /* __BSD_VISIBLE */
 131 .Ed
 132 .Pp
 133 The
 134 .Fn cfgetispeed
 135 function returns the input baud rate in the termios structure referenced by
 136 .Fa tp .
 137 .Pp
 138 The
 139 .Fn cfsetispeed
 140 function sets the input baud rate in the termios structure referenced by
 141 .Fa tp
 142 to
 143 .Fa speed .
 144 .Pp
 145 The
 146 .Fn cfgetospeed
 147 function returns the output baud rate in the termios structure referenced by
 148 .Fa tp .
 149 .Pp
 150 The
 151 .Fn cfsetospeed
 152 function sets the output baud rate in the termios structure referenced by
 153 .Fa tp
 154 to
 155 .Fa speed .
 156 .Pp
 157 The
 158 .Fn cfsetspeed
 159 function sets both the input and output baud rate in the termios structure
 160 referenced by
 161 .Fa tp
 162 to
 163 .Fa speed .
 164 .Pp
 165 Upon successful completion, the functions
 166 .Fn cfsetispeed ,
 167 .Fn cfsetospeed ,
 168 and
 169 .Fn cfsetspeed
 170 return a value of 0.
 171 Otherwise, a value of -1 is returned and the global variable
 172 .Va errno
 173 is set to indicate the error.
 174 .Sh GETTING AND SETTING THE TERMIOS STATE
 175 This section describes the functions that are used to control the general
 176 terminal interface.
 177 Unless otherwise noted for a specific command, these functions are restricted
 178 from use by background processes.
 179 Attempts to perform these operations shall cause the process group to be sent
 180 a
 181 .Dv SIGTTOU
 182 signal.
 183 If the calling process is blocking or ignoring
 184 .Dv SIGTTOU
 185 signals, the process is allowed to perform the operation and the
 186 .Dv SIGTTOU
 187 signal is not sent.
 188 .Pp
 189 In all the functions, although
 190 .Fa fd
 191 is an open file descriptor, the functions affect the underlying terminal
 192 file, not just the open file description associated with the particular
 193 file descriptor.
 194 .Pp
 195 The
 196 .Fn cfmakeraw
 197 function sets the flags stored in the termios structure to a state disabling
 198 all input and output processing, giving a
 199 .Dq raw I/O path ,
 200 while the
 201 .Fn cfmakesane
 202 function sets them to a state similar to those of a newly created
 203 terminal device.
 204 It should be noted that there is no function to reverse this effect.
 205 This is because there are a variety of processing options that could be
 206 re-enabled and the correct method is for an application to snapshot the
 207 current terminal state using the function
 208 .Fn tcgetattr ,
 209 setting raw or sane mode with
 210 .Fn cfmakeraw
 211 or
 212 .Fn cfmakesane
 213 and the subsequent
 214 .Fn tcsetattr ,
 215 and then using another
 216 .Fn tcsetattr
 217 with the saved state to revert to the previous terminal state.
 218 .Pp
 219 The
 220 .Fn tcgetattr
 221 function copies the parameters associated with the terminal referenced
 222 by
 223 .Fa fd
 224 in the termios structure referenced by
 225 .Fa tp .
 226 This function is allowed from a background process, however, the terminal
 227 attributes may be subsequently changed by a foreground process.
 228 .Pp
 229 The
 230 .Fn tcsetattr
 231 function sets the parameters associated with the terminal from the
 232 termios structure referenced by
 233 .Fa tp .
 234 The
 235 .Fa action
 236 field is created by
 237 .Em or Ns 'ing
 238 the following values, as specified in the include file
 239 .In termios.h .
 240 .Bl -tag -width ".Dv TCSADRAIN"
 241 .It Dv TCSANOW
 242 The change occurs immediately.
 243 .It Dv TCSADRAIN
 244 The change occurs after all output written to
 245 .Fa fd
 246 has been transmitted to the terminal.
 247 This value of
 248 .Fa action
 249 should be used when changing parameters that affect output.
 250 .It Dv TCSAFLUSH
 251 The change occurs after all output written to
 252 .Fa fd
 253 has been transmitted to the terminal.
 254 Additionally, any input that has been received but not read is discarded.
 255 .It Dv TCSASOFT
 256 If this value is
 257 .Em or Ns 'ed
 258 into the
 259 .Fa action
 260 value, the values of the
 261 .Em c_cflag ,
 262 .Em c_ispeed ,
 263 and
 264 .Em c_ospeed
 265 fields are ignored.
 266 .El
 267 .Pp
 268 The 0 baud rate is used to terminate the connection.
 269 If 0 is specified as the output speed to the function
 270 .Fn tcsetattr ,
 271 modem control will no longer be asserted on the terminal, disconnecting
 272 the terminal.
 273 .Pp
 274 If zero is specified as the input speed to the function
 275 .Fn tcsetattr ,
 276 the input baud rate will be set to the same value as that specified by
 277 the output baud rate.
 278 .Pp
 279 If
 280 .Fn tcsetattr
 281 is unable to make any of the requested changes, it returns -1 and
 282 sets
 283 .Va errno .
 284 Otherwise, it makes all of the requested changes it can.
 285 If the specified input and output baud rates differ and are a combination
 286 that is not supported, neither baud rate is changed.
 287 .Pp
 288 Upon successful completion, the functions
 289 .Fn tcgetattr
 290 and
 291 .Fn tcsetattr
 292 return a value of 0.
 293 Otherwise, they
 294 return -1 and the global variable
 295 .Va errno
 296 is set to indicate the error, as follows:
 297 .Bl -tag -width Er
 298 .It Bq Er EBADF
 299 The
 300 .Fa fd
 301 argument to
 302 .Fn tcgetattr
 303 or
 304 .Fn tcsetattr
 305 was not a valid file descriptor.
 306 .It Bq Er EINTR
 307 The
 308 .Fn tcsetattr
 309 function was interrupted by a signal.
 310 .It Bq Er EINVAL
 311 The
 312 .Fa action
 313 argument to the
 314 .Fn tcsetattr
 315 function was not valid, or an attempt was made to change an attribute
 316 represented in the termios structure to an unsupported value.
 317 .It Bq Er ENOTTY
 318 The file associated with the
 319 .Fa fd
 320 argument to
 321 .Fn tcgetattr
 322 or
 323 .Fn tcsetattr
 324 is not a terminal.
 325 .El
 326 .Sh SEE ALSO
 327 .Xr tcsendbreak 3 ,
 328 .Xr termios 4
 329 .Sh STANDARDS
 330 The
 331 .Fn cfgetispeed ,
 332 .Fn cfsetispeed ,
 333 .Fn cfgetospeed ,
 334 .Fn cfsetospeed ,
 335 .Fn tcgetattr
 336 and
 337 .Fn tcsetattr
 338 functions are expected to be compliant with the
 339 .St -p1003.1-88
 340 specification.
 341 The
 342 .Fn cfmakeraw ,
 343 .Fn cfmakesane
 344 and
 345 .Fn cfsetspeed
 346 functions,
 347 as well as the
 348 .Dv TCSASOFT
 349 option to the
 350 .Fn tcsetattr
 351 function are extensions to the
 352 .St -p1003.1-88
 353 specification.