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 .\" 4. 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$
  30 .\"
  31 .Dd January 2, 1994
  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 #ifndef _POSIX_SOURCE
 117 #define EXTA    19200
 118 #define EXTB    38400
 119 #endif  /*_POSIX_SOURCE */
 120 .Ed
 121 .Pp
 122 The
 123 .Fn cfgetispeed
 124 function returns the input baud rate in the termios structure referenced by
 125 .Fa tp .
 126 .Pp
 127 The
 128 .Fn cfsetispeed
 129 function sets the input baud rate in the termios structure referenced by
 130 .Fa tp
 131 to
 132 .Fa speed .
 133 .Pp
 134 The
 135 .Fn cfgetospeed
 136 function returns the output baud rate in the termios structure referenced by
 137 .Fa tp .
 138 .Pp
 139 The
 140 .Fn cfsetospeed
 141 function sets the output baud rate in the termios structure referenced by
 142 .Fa tp
 143 to
 144 .Fa speed .
 145 .Pp
 146 The
 147 .Fn cfsetspeed
 148 function sets both the input and output baud rate in the termios structure
 149 referenced by
 150 .Fa tp
 151 to
 152 .Fa speed .
 153 .Pp
 154 Upon successful completion, the functions
 155 .Fn cfsetispeed ,
 156 .Fn cfsetospeed ,
 157 and
 158 .Fn cfsetspeed
 159 return a value of 0.
 160 Otherwise, a value of -1 is returned and the global variable
 161 .Va errno
 162 is set to indicate the error.
 163 .Sh GETTING AND SETTING THE TERMIOS STATE
 164 This section describes the functions that are used to control the general
 165 terminal interface.
 166 Unless otherwise noted for a specific command, these functions are restricted
 167 from use by background processes.
 168 Attempts to perform these operations shall cause the process group to be sent
 169 a SIGTTOU signal.
 170 If the calling process is blocking or ignoring SIGTTOU signals, the process
 171 is allowed to perform the operation and the SIGTTOU signal is not sent.
 172 .Pp
 173 In all the functions, although
 174 .Fa fd
 175 is an open file descriptor, the functions affect the underlying terminal
 176 file, not just the open file description associated with the particular
 177 file descriptor.
 178 .Pp
 179 The
 180 .Fn cfmakeraw
 181 function sets the flags stored in the termios structure to a state disabling
 182 all input and output processing, giving a
 183 .Dq raw I/O path .
 184 It should be noted that there is no function to reverse this effect.
 185 This is because there are a variety of processing options that could be
 186 re-enabled and the correct method is for an application to snapshot the
 187 current terminal state using the function
 188 .Fn tcgetattr ,
 189 setting raw mode with
 190 .Fn cfmakeraw
 191 and the subsequent
 192 .Fn tcsetattr ,
 193 and then using another
 194 .Fn tcsetattr
 195 with the saved state to revert to the previous terminal state.
 196 .Pp
 197 The
 198 .Fn tcgetattr
 199 function copies the parameters associated with the terminal referenced
 200 by
 201 .Fa fd
 202 in the termios structure referenced by
 203 .Fa tp .
 204 This function is allowed from a background process, however, the terminal
 205 attributes may be subsequently changed by a foreground process.
 206 .Pp
 207 The
 208 .Fn tcsetattr
 209 function sets the parameters associated with the terminal from the
 210 termios structure referenced by
 211 .Fa tp .
 212 The
 213 .Fa action
 214 argument is created by
 215 .Em or Ns 'ing
 216 the following values, as specified in the include file
 217 .In termios.h .
 218 .Bl -tag -width "TCSADRAIN"
 219 .It Fa TCSANOW
 220 The change occurs immediately.
 221 .It Fa TCSADRAIN
 222 The change occurs after all output written to
 223 .Fa fd
 224 has been transmitted to the terminal.
 225 This value of
 226 .Fa action
 227 should be used when changing parameters that affect output.
 228 .It Fa TCSAFLUSH
 229 The change occurs after all output written to
 230 .Fa fd
 231 has been transmitted to the terminal.
 232 Additionally, any input that has been received but not read is discarded.
 233 .It Fa TCSASOFT
 234 If this value is
 235 .Em or Ns 'ed
 236 into the
 237 .Fa action
 238 value, the values of the
 239 .Va c_cflag ,
 240 .Va c_ispeed ,
 241 and
 242 .Va c_ospeed
 243 fields are ignored.
 244 .El
 245 .Pp
 246 The 0 baud rate is used to terminate the connection.
 247 If 0 is specified as the output speed to the function
 248 .Fn tcsetattr ,
 249 modem control will no longer be asserted on the terminal, disconnecting
 250 the terminal.
 251 .Pp
 252 If zero is specified as the input speed to the function
 253 .Fn tcsetattr ,
 254 the input baud rate will be set to the same value as that specified by
 255 the output baud rate.
 256 .Pp
 257 If
 258 .Fn tcsetattr
 259 is unable to make any of the requested changes, it returns -1 and
 260 sets errno.
 261 Otherwise, it makes all of the requested changes it can.
 262 If the specified input and output baud rates differ and are a combination
 263 that is not supported, neither baud rate is changed.
 264 .Pp
 265 Upon successful completion, the functions
 266 .Fn tcgetattr
 267 and
 268 .Fn tcsetattr
 269 return a value of 0.
 270 Otherwise, they
 271 return -1 and the global variable
 272 .Va errno
 273 is set to indicate the error, as follows:
 274 .Bl -tag -width Er
 275 .It Bq Er EBADF
 276 The
 277 .Fa fd
 278 argument to
 279 .Fn tcgetattr
 280 or
 281 .Fn tcsetattr
 282 was not a valid file descriptor.
 283 .It Bq Er EINTR
 284 The
 285 .Fn tcsetattr
 286 function was interrupted by a signal.
 287 .It Bq Er EINVAL
 288 The
 289 .Fa action
 290 argument to the
 291 .Fn tcsetattr
 292 function was not valid, or an attempt was made to change an attribute
 293 represented in the termios structure to an unsupported value.
 294 .It Bq Er ENOTTY
 295 The file associated with the
 296 .Fa fd
 297 argument to
 298 .Fn tcgetattr
 299 or
 300 .Fn tcsetattr
 301 is not a terminal.
 302 .El
 303 .Sh SEE ALSO
 304 .Xr tcsendbreak 3 ,
 305 .Xr termios 4
 306 .Sh STANDARDS
 307 The
 308 .Fn cfgetispeed ,
 309 .Fn cfsetispeed ,
 310 .Fn cfgetospeed ,
 311 .Fn cfsetospeed ,
 312 .Fn tcgetattr
 313 and
 314 .Fn tcsetattr
 315 functions are expected to be compliant with the
 316 .St -p1003.1-88
 317 specification.
 318 The
 319 .Fn cfmakeraw
 320 and
 321 .Fn cfsetspeed
 322 functions,
 323 as well as the
 324 .Li TCSASOFT
 325 option to the
 326 .Fn tcsetattr
 327 function are extensions to the
 328 .St -p1003.1-88
 329 specification.