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