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