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