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