Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TERMIO(4)		   Kernel Interfaces Manual		     TERMIO(4)

NAME
       termio -	general	terminal interface

SYNOPSIS
       #include	<sys/termios.h>

DESCRIPTION
       Asynchronous  communications  ports,  pseudo-terminals, and the special
       interface accessed by /dev/tty all use the same general	interface,  no
       matter  what hardware (if any) is involved.  The	remainder of this sec-
       tion discusses the common features of this interface.

   Opening a Terminal Device File
       When a terminal file is opened, the process normally waits until	a con-
       nection is established.	In practice, users' programs seldom open these
       files; they are opened by getty(8) and become a user's standard	input,
       output,	and  error files.  The state of	the software carrier flag will
       effect the ability to open a line.

   Sessions
       Processes are now grouped by session, then process group, then  process
       id.  Each session is associated with one	"login"	session	(windows count
       as logins). A process creates a session by  calling  setsid(2V),	 which
       will  put  the  process	in a new session as its	only member and	as the
       session leader of that session.

   Process Groups
       A terminal may have a distinguished process group associated  with  it.
       This  distinguished process group plays a special role in handling sig-
       nal-generating input characters,	as  discussed  below  in  the  Special
       Characters  section below.  The terminal's process group	can can	be set
       only to process groups that are members of the terminal's session.

       A command interpreter, such as csh(1), that supports "job control"  can
       allocate	 the terminal to different jobs, or process groups, by placing
       related processes in  a	single	process	 group	and  associating  this
       process group with the terminal.	 A terminal's associated process group
       may be set or examined by a process with	 sufficient  privileges.   The
       terminal	interface aids in this allocation by restricting access	to the
       terminal	by processes that are not in the current  process  group;  see
       Job Access Control below.

   Orphaned Process Groups
       An  orphaned  process group is a	process	group that has no parent, in a
       different process group,	and in the  same  session.   In	 other	words,
       there is	no process that	can handle job control signals for the process
       group.

   The Controlling Terminal
       A terminal may belong to	a process as its controlling terminal.	 If  a
       process	that is	a session leader, and that does	not have a controlling
       terminal, opens a terminal file not already associated with a  session,
       the terminal associated with that terminal file becomes the controlling
       terminal	for that process, and  the  terminal's	distinguished  process
       group  is  set  to the process group of that process.  (Currently, this
       also happens if a process that does not have a controlling terminal and
       is  not a member	of a process group opens a terminal.  In this case, if
       the terminal is not associated with a session, a	new session is created
       with a process group ID equal to	the process ID of the process in ques-
       tion, and the terminal is assigned to that  session.   The  process  is
       made a member of	the terminal's process group.)

       If  a  process  does  not wish to acquire the terminal as a controlling
       terminal	(as is the case	with many daemons that open /dev/console), the
       process should or O_NOCTTY into the second argument to open(2V).

       The  controlling	 terminal  is  inherited  by  a	child process during a
       fork(2V).  A process relinquishes its control terminal when it  changes
       its  process  group  using  setsid(2V),	when it	trys to	change back to
       process group 0 via a setpgrp(2V) with arguments	(mypid,	0), or when it
       issues  a TIOCNOTTY ioctl(2) call on a file descriptor created by open-
       ing the file /dev/tty.  Both of the last	two cases cause	 a  setsid(2V)
       to  be  called on the process' behalf.  This is an attempt to allow old
       binaries	(that couldn't have known about	setsid(2V)) to	still  acquire
       controlling  terminals.	 It  doesn't always work, see setsid(8V) for a
       workaround for those cases.

       When a session leader that has a	controlling terminal  terminates,  the
       distinguished  process group of the controlling terminal	is set to zero
       (indicating no distinguished process group).  This allows the  terminal
       to be acquired as a controlling terminal	by a new session leader.

   Closing a Terminal Device File
       When  a	terminal  device  file is closed, the process closing the file
       waits until all output is drained; all pending input is	then  flushed,
       and  finally  a disconnect is performed.	 If HUPCL is set, the existing
       connection is severed (by hanging up the	phone line, if appropriate).

   Job Access Control
       If a process is in the (non-zero) distinguished process	group  of  its
       controlling  terminal  (if  this	 is  true, the process is said to be a
       foreground process), then read(2V) operations are allowed as  described
       below  in Input Processing and Reading Characters.  If a	process	is not
       in the (non-zero) distinguished process group of	its controlling	termi-
       nal  (if	this is	true, the process is said to be	a background process),
       then any	attempts to read from that terminal will typically  send  that
       process'	 process  group	 a SIGTTIN signal.  If the process is ignoring
       SIGTTIN,	has SIGTTIN blocked, is	a member of an orphaned	process	group,
       or  is  in the middle of	process	creation using vfork(2), the read will
       return -1 and set errno to EIO, and the	SIGTTIN	 signal	 will  not  be
       sent.   The  SIGTTIN  signal  will  normally  stop  the members of that
       process group.

       When the	TOSTOP bit is set in the c_lflag field,	attempts  by  a	 back-
       ground process to write to its controlling terminal will	typically send
       that process' process group a SIGTTOU signal.  If the process is	ignor-
       ing  SIGTTOU,  has SIGTTOU blocked, or is in the	middle of process cre-
       ation using vfork(), the	process	will be	allowed	to write to the	termi-
       nal  and	 the  SIGTTOU  signal will not be sent.	 If the	process	is or-
       phaned, the write will return -1	and set	errno to EIO, and the  SIGTTOU
       signal will not be sent.	 SIGTTOU signal	will normally stop the members
       of that process group.  Certain ioctl( calls that set terminal  parame-
       ters  are  treated  in  this  same  fashion,  except that TOSTOP	is not
       checked;	the effect is identical	to that	of terminal writes when	TOSTOP
       is set.	See IOCTLS.

   Input Processing and	Reading	Characters
       A  terminal  associated	with one of these files	ordinarily operates in
       full-duplex mode.  Characters may be typed at any time, even while out-
       put  is	occurring, and are only	lost when the system's character input
       buffers become completely full, which is	rare, or when the user has ac-
       cumulated  the maximum allowed number of	input characters that have not
       yet been	read by	some program.  This limit is available is  {MAX_CANON}
       characters  (see	 pathconf(2V)).	  If the IMAXBEL mode has not been se-
       lected, all the saved characters	are thrown away	 without  notice  when
       the  input limit	is reached; if the IMAXBEL mode	has been selected, the
       driver refuses to accept	any further input, and echoes  a  bell	(ASCII
       BEL).

       Two  general  kinds  of	input  processing are available, determined by
       whether the terminal device file	is in canonical	mode or	 non-canonical
       mode (see ICANON	in the Local Modes section).

       The  style of input processing can also be very different when the ter-
       minal is	put in non-blocking I/O	mode; see  read(2V).   In  this	 case,
       reads from the terminal will never block.

       It  is  possible	 to  simulate terminal input using the TIOCSTI ioctl()
       call, which takes, as its third argument, the address of	 a  character.
       The  system pretends that this character	was typed on the argument ter-
       minal, which must be  the  process'  controlling	 terminal  unless  the
       process'	effective user ID is super-user.

   Canonical Mode Input	Processing
       In  canonical  mode  input  processing,	terminal input is processed in
       units of	lines.	A line is delimited by a NEWLINE (ASCII	LF) character,
       an  EOF (by default, an ASCII EOT) character, or	one of two user-speci-
       fied end-of-line	characters, EOL	and EOL2.  This	means  that  a	read()
       will  not  complete until an entire line	has been typed or a signal has
       been received.  Also, no	matter how many	characters  are	 requested  in
       the  read call, at most one line	will be	returned.  It is not, however,
       necessary to read a whole line at once; any number of characters	may be
       requested in a read, even one, without losing information.

       Erase and kill processing occurs	during input.  The ERASE character (by
       default,	the character DEL) erases the last character typed in the cur-
       rent input line.	 The WERASE character (by default, the character CTRL-
       W) erases the last "word" typed in the current input line (but not  any
       preceding  SPACE	or TAB characters).  A "word" is defined as a sequence
       of non-blank characters,	with TAB characters counted as	blanks.	  Nei-
       ther ERASE nor WERASE will erase	beyond the beginning of	the line.  The
       KILL character (by default, the character CTRL-U) kills	(deletes)  the
       entire  current input line, and optionally outputs a NEWLINE character.
       All these characters operate on a key-stroke  basis,  independently  of
       any backspacing or tabbing that may have	been done.

       The  REPRINT character (the character CTRL-R) prints a NEWLINE followed
       by all characters that have not been read.  Reprinting also occurs  au-
       tomatically if characters that would normally be	erased from the	screen
       are fouled by program output.  The characters are reprinted as if  they
       were  being  echoed; as a consequence, if ECHO is not set, they are not
       printed.

       The ERASE and KILL characters may be  entered  literally	 by  preceding
       them  with the escape character (\).  In	this case the escape character
       is not read.  The ERASE and KILL	characters may be changed.

   Non-Canonical Mode Input Processing
       In non-canonical	mode input processing, input characters	are not	assem-
       bled into lines,	and erase and kill processing does not occur.  The MIN
       and TIME	values are used	to determine how to process the	characters re-
       ceived.

       MIN represents the minimum number of characters that should be received
       when the	read is	satisfied (when	the characters	are  returned  to  the
       user).	TIME  is  a  timer  of 0.10 second granularity that is used to
       timeout bursty and short	term data transmissions.   The	four  possible
       values for MIN and TIME and their interactions are described below.

   Case	A: MIN > 0, TIME > 0
       In  this	 case  TIME serves as an intercharacter	timer and is activated
       after the first character is received. Since it	is  an	intercharacter
       timer,  it is reset after a character is	received.  The interaction be-
       tween MIN and TIME is as	follows: as soon as one	character is received,
       the  intercharacter  timer  is started.	If MIN characters are received
       before the intercharacter timer expires (remember that the timer	is re-
       set  upon  receipt  of  each character),	the read is satisfied.	If the
       timer expires before MIN	characters are received,  the  characters  re-
       ceived to that point are	returned to the	user.  Note: if	MIN expires at
       least one character will	be returned because the	timer would  not  have
       been  enabled  unless a character was received.	In this	case (MIN > 0,
       TIME > 0) the read will sleep until the MIN and TIME mechanisms are ac-
       tivated by the receipt of the first character.

   Case	B: MIN > 0, TIME = 0
       In  this	case, since the	value of TIME is zero, the timer plays no role
       and only	MIN is significant.  A pending read is not satisfied until MIN
       characters  are received	(the pending read will sleep until MIN charac-
       ters are	received).  A program that uses	this case to read record-based
       terminal	I/O may	block indefinitely in the read operation.

   Case	C: MIN = 0, TIME > 0
       In  this	case, since MIN	= 0, TIME no longer represents an intercharac-
       ter timer.  It now serves as a read timer that is activated as soon  as
       a read()	is done.  A read is satisfied as soon as a single character is
       received	or the read timer expires.  Note: in this case	if  the	 timer
       expires,	 no character will be returned.	 If the	timer does not expire,
       the only	way the	read can be satisfied is if a character	 is  received.
       In this case the	read will not block indefinitely waiting for a charac-
       ter - if	no character is	received within	 TIME*.10  seconds  after  the
       read is initiated, the read will	return with zero characters.

   Case	D: MIN = 0, TIME = 0
       In  this	case return is immediate.  The minimum of either the number of
       characters requested or the number of  characters  currently  available
       will be returned	without	waiting	for more characters to be input.

   Comparison of the Different Cases of	MIN, TIME Interaction
       Some points to note about MIN and TIME:

       o      In  the  following explanations one may notice that the interac-
	      tions of MIN and TIME are	not symmetric.	For example, when  MIN
	      >	 0 and TIME = 0, TIME has no effect.  However, in the opposite
	      case where MIN = 0 and TIME > 0, both MIN	and TIME play  a  role
	      in that MIN is satisfied with the	receipt	of a single character.

       o      Also note	that in	case A (MIN > 0, TIME >	0), TIME represents an
	      intercharacter timer while in case C (TIME = 0, TIME >  0)  TIME
	      represents a read	timer.

       These  two  points  highlight the dual purpose of the MIN/TIME feature.
       Cases A and B, where MIN	> 0, exist to handle burst mode	activity  (for
       example,	 file transfer programs) where a program would like to process
       at least	MIN characters at a time.  In case A, the intercharacter timer
       is  activated  by  a  user  as a	safety measure;	while in case B, it is
       turned off.

       Cases C and D exist to handle single character timed transfers.	 These
       cases  are  readily adaptable to	screen-based applications that need to
       know if a character is present in the input queue before	refreshing the
       screen. In case C the read is timed; while in case D, it	is not.

       Another	important  note	is that	MIN is always just a minimum.  It does
       not denote a record length.  That is, if	a program does a  read	of  20
       bytes,  MIN is 10, and 25 characters are	present, 20 characters will be
       returned	to the user.

   Writing Characters
       When one	or more	characters are written,	they are  transmitted  to  the
       terminal	as soon	as previously-written characters have finished typing.
       Input characters	are echoed as they are typed if	echoing	has  been  en-
       abled.	If a process produces characters more rapidly than they	can be
       typed, it will be suspended when	its output queue exceeds  some	limit.
       When  the  queue	has drained down to some threshold, the	program	is re-
       sumed.

   Special Characters
       Certain characters have	special	 functions  on	input  and/or  output.
       These  functions	 and  their default character values are summarized as
       follows:

       INTR	 (CTRL-C or ASCII ETX) generates a  SIGINT  signal,  which  is
		 sent  to all processes	in the distinguished process group as-
		 sociated with the terminal.  Normally,	each such  process  is
		 forced	 to  terminate,	but arrangements may be	made either to
		 ignore	the signal or to receive a trap	to an agreed-upon  lo-
		 cation; see sigvec(2).

       QUIT	 (CTRL-|  or  ASCII  FS)  generates a SIGQUIT signal, which is
		 sent to all processes in the distinguished process group  as-
		 sociated  with	 the  terminal.	 Its treatment is identical to
		 the interrupt signal except that, unless a receiving  process
		 has  made  other arrangements,	it will	not only be terminated
		 but a core image file (called core) will be  created  in  the
		 current working directory.

       ERASE	 (Rubout  or  ASCII  DEL)  erases the preceding	character.  It
		 will not erase	beyond the start of a line, as delimited by  a
		 NL, EOF, EOL, or EOL2 character.

       WERASE	 (CTRL-W  or  ASCII ETB) erases	the preceding "word".  It will
		 not erase beyond the start of a line, as delimited by	a  NL,
		 EOF, EOL, or EOL2 character.

       KILL	 (CTRL-U  or  ASCII NAK) deletes the entire line, as delimited
		 by a NL, EOF, EOL, or EOL2 character.

       REPRINT	 (CTRL-R or ASCII DC2) reprints	all characters that  have  not
		 been read, preceded by	a NEWLINE.

       EOF	 (CTRL-D  or ASCII EOT)	may be used to generate	an end-of-file
		 from a	terminal.  When	received, all the  characters  waiting
		 to  be	 read  are  immediately	passed to the program, without
		 waiting for a NEWLINE,	and the	EOF is	discarded.   Thus,  if
		 there	are no characters waiting, which is to say the EOF oc-
		 curred	at the beginning of a line, zero  characters  will  be
		 passed	back, which is the standard end-of-file	indication.

       NL	 (ASCII	 LF)  is  the  normal  line  delimiter.	 It can	not be
		 changed; it can, however, be escaped by the LNEXT character.

       EOL
       EOL2	 (ASCII	NUL) are additional line delimiters,  like  NL.	  They
		 are not normally used.

       SUSP	 (CTRL-Z  or  ASCII EM)	is used	by the job control facility to
		 change	the current job	to return to the controlling job.   It
		 generates  a SIGTSTP signal, which stops all processes	in the
		 terminal's process group.

       STOP	 (CTRL-S or ASCII DC3) can be used to temporarily suspend out-
		 put.	It is useful with CRT terminals	to prevent output from
		 disappearing before it	can be read.   While  output  is  sus-
		 pended, STOP characters are ignored and not read.

       START	 (CTRL-Q  or ASCII DC1)	is used	to resume output that has been
		 suspended by a	STOP character.	  While	 output	 is  not  sus-
		 pended, START characters are ignored and not read.

       DISCARD	 (CTRL-O or ASCII SI) causes subsequent	output to be discarded
		 until another DISCARD character is typed, more	input arrives,
		 or the	condition is cleared by	a program.

       LNEXT	 (CTRL-V  or ASCII SYN)	causes the special meaning of the next
		 character to be ignored; this works for all the special char-
		 acters	 mentioned  above.  This allows	characters to be input
		 that would otherwise get interpreted by the system (for exam-
		 ple, KILL, QUIT.)

       The character values for	INTR, QUIT, ERASE, WERASE, KILL, REPRINT, EOF,
       EOL, EOL2, SUSP,	STOP, START, DISCARD, and LNEXT	may be changed to suit
       individual  tastes.   If	the value of a special control character is 0,
       the function of that special control character will be  disabled.   The
       ERASE, KILL, and	EOF characters may be escaped by a preceding \ charac-
       ter, in which case no special function is done.	 Any  of  the  special
       characters  may	be  preceded  by the LNEXT character, in which case no
       special function	is done.

       If IEXTEN is added to the local modes (this is the default),  then  all
       of the special characters are in	effect.	 If IEXTEN is cleared from the
       local modes, then only the following POSIX.1  compatible	 specials  are
       seen  as	 specials:  INTR, QUIT,	ERASE, KILL, EOF, NL, EOL, SUSP, STOP,
       START, and CR.

   Software Carrier Mode
       The software carrier mode can be	enabled	or disabled  using  the	 TIOC-
       SSOFTCAR	 ioctl().  If the software carrier flag	for a line is off, the
       line pays attention to the hardware carrier detect (DCD)	 signal.   The
       tty  device associated with the line can	not be opened until DCD	is as-
       serted.	If the software	carrier	flag is	on, the	line behaves as	if DCD
       is always asserted.

       The  software  carrier  flag is usually turned on for locally connected
       terminals or other devices, and is off for lines	with modems.

       To be able to issue the TIOCGSOFTCAR and	 TIOCSSOFTCAR  ioctl()	calls,
       the  tty	 line should be	opened with O_NDELAY so	that the open(2V) will
       not wait	for the	carrier.

   Modem Disconnect
       If a modem disconnect is	detected, and the CLOCAL flag is  not  set  in
       the c_cflag field, a SIGHUP signal is sent to all processes in the dis-
       tinguished process group	associated with	this terminal.	 Unless	 other
       arrangements  have been made, this signal terminates the	processes.  If
       SIGHUP is ignored or caught, any	subsequent read() returns with an end-
       of-file	indication  until the terminal is closed.  Thus, programs that
       read a terminal and test	for end-of-file	 can  terminate	 appropriately
       after  a	disconnect.  Any subsequent write() will return	-1 and set er-
       rno to EIO until	the terminal is	closed.

       A SIGHUP	signal is sent to the tty if the software carrier flag is  off
       and the hardware	carrier	detect drops.

   Terminal Parameters
       The parameters that control the behavior	of devices and modules provid-
       ing the termios interface are specified by the termios  structure,  de-
       fined  by  <sys/termios.h>.  Several ioctl() system calls that fetch or
       change these parameters use this	structure:

	      #define	   NCCS	17
	      struct	   termios {
		    unsigned	long	c_iflag;/* input modes */
		    unsigned	long	c_oflag;/* output modes	*/
		    unsigned	long	c_cflag;/* control modes */
		    unsigned	long	c_lflag;/* local modes */
		    unsigned	char	c_line;/* line discipline */
		    unsigned	char	c_cc[NCCS];/* control chars */
	      };

       The special control characters are defined by the array c_cc.  The rel-
       ative positions and initial values for each function are	as follows:
	      0	  VINTR	   ETX
	      1	  VQUIT	   FS
	      2	  VERASE   DEL
	      3	  VKILL	   NAK
	      4	  VEOF	   EOT
	      5	  VEOL	   NUL
	      6	  VEOL2	   NUL
	      7	  VSWTCH   NUL
	      8	  VSTART   DC1
	      9	  VSTOP	   DC3
	      10  VSUSP	   EM
	      12  VREPRINT DC2
	      13  VDISCARD SI
	      14  VWERASE  ETB
	      15  VLNEXT   SYN

       The  MIN	value is stored	in the VMIN element of the c_cc	array, and the
       TIME value is stored in the VTIME element of the	c_cc array.  The  VMIN
       element	is the same element as the VEOF	element, and the VTIME element
       is the same element as the VEOL element.

   Input Modes
       The c_iflag field describes the basic terminal input control:

	      IGNBRK  0000001  Ignore break condition.
	      BRKINT  0000002  Signal interrupt	on break.
	      IGNPAR  0000004  Ignore characters with parity errors.
	      PARMRK  0000010  Mark parity errors.
	      INPCK   0000020  Enable input parity check.
	      ISTRIP  0000040  Strip character.
	      INLCR   0000100  Map NL to CR on input.
	      IGNCR   0000200  Ignore CR.
	      ICRNL   0000400  Map CR to NL on input.
	      IUCLC   0001000  Map upper-case to lower-case on input.
	      IXON    0002000  Enable start/stop output	control.
	      IXANY   0004000  Enable any character to restart output.
	      IXOFF   0010000  Enable start/stop input control.
	      IMAXBEL 0020000  Echo BEL	on input line too long.

       If IGNBRK is set, a break condition (a  character  framing  error  with
       data  all  zeros) detected on input is ignored, that is,	not put	on the
       input queue and therefore not  read  by	any  process.	Otherwise,  if
       BRKINT  is set, a break condition will generate a SIGINT	and flush both
       the input and output queues.  If	neither	IGNBRK nor BRKINT  is  set,  a
       break condition is read as a single ASCII NUL character ('\0').

       If  IGNPAR is set, characters with framing or parity errors (other than
       break) are ignored.  Otherwise, if PARMRK is set, a  character  with  a
       framing	or parity error	that is	not ignored is read as the three-char-
       acter sequence: '\377', '\0', X,	where X	is the data of	the  character
       received	 in  error.  To	avoid ambiguity	in this	case, if ISTRIP	is not
       set, a valid character of '\377'	is read	as '\377', '\377'.  If neither
       IGNPAR  nor PARMRK is set, a framing or parity error (other than	break)
       is read as a single ASCII NUL character ('\0').

       If INPCK	is set,	input parity checking is enabled.   If	INPCK  is  not
       set, input parity checking is disabled.	This allows output parity gen-
       eration without input parity errors.

       If ISTRIP is set, valid input characters	are first stripped to 7	 bits,
       otherwise all 8 bits are	processed.

       If  INLCR is set, a received NL character is translated into a CR char-
       acter.  If IGNCR	is set,	a received CR character	is ignored (not	read).
       Otherwise if ICRNL is set, a received CR	character is translated	into a
       NL character.

       If IUCLC	is set,	a received upper-case alphabetic character  is	trans-
       lated into the corresponding lower-case character.

       If  IXON	is set,	start/stop output control is enabled.  A received STOP
       character will suspend output  and  a  received	START  character  will
       restart	output.	  The  STOP and	START characters will not be read, but
       will merely perform flow	control	functions.  If IXANY is	set, any input
       character will restart output that has been suspended.

       If IXOFF	is set,	the system will	transmit a STOP	character when the in-
       put queue is nearly full, and a START character when enough  input  has
       been read that the input	queue is nearly	empty again.

       If  IMAXBEL  is	set,  the  ASCII  BEL character	is echoed if the input
       stream overflows.  Further input	will not be stored, but	any input  al-
       ready present in	the input stream will not be disturbed.	 If IMAXBEL is
       not set,	no BEL character is echoed, and	all input present in the input
       queue is	discarded if the input stream overflows.

       The initial input control value is BRKINT, ICRNL, IXON, ISTRIP.

   Output modes
       The c_oflag field specifies the system treatment	of output:

	      OPOST   0000001  Postprocess output.
	      OLCUC   0000002  Map lower case to upper on output.
	      ONLCR   0000004  Map NL to CR-NL on output.
	      OCRNL   0000010  Map CR to NL on output.
	      ONOCR   0000020  No CR output at column 0.
	      ONLRET  0000040  NL performs CR function.
	      OFILL   0000100  Use fill	characters for delay.
	      OFDEL   0000200  Fill is DEL, else NUL.
	      NLDLY   0000400  Select new-line delays:
		NL0   0
		NL1   0000400
	      CRDLY   0003000  Select carriage-return delays:
		CR0   0
		CR1   0001000
		CR2   0002000
		CR3   0003000
	      TABDLY  0014000  Select horizontal-tab delays:
		TAB0  0		or tab expansion:
		TAB1  0004000
		TAB2  0010000
		XTABS 0014000  Expand tabs to spaces.
	      BSDLY   0020000  Select backspace	delays:
		BS0   0
		BS1   0020000
	      VTDLY   0040000  Select vertical-tab delays:
		VT0   0
		VT1   0040000
	      FFDLY   0100000  Select form-feed	delays:
		FF0   0
		FF1   0100000

       If  OPOST  is set, output characters are	post-processed as indicated by
       the remaining  flags,  otherwise	 characters  are  transmitted  without
       change.

       If  OLCUC  is  set, a lower-case	alphabetic character is	transmitted as
       the corresponding upper-case character.	This function is often used in
       conjunction with	IUCLC.

       If ONLCR	is set,	the NL character is transmitted	as the CR-NL character
       pair.  If OCRNL is set, the CR character	is transmitted as the NL char-
       acter.	If ONOCR is set, no CR character is transmitted	when at	column
       0 (first	position).  If ONLRET is set, the NL character is  assumed  to
       do  the	carriage-return	 function; the column pointer will be set to 0
       and the delays specified	for CR will be used.  Otherwise	the NL charac-
       ter  is	assumed	 to do just the	line-feed function; the	column pointer
       will remain unchanged.  The column pointer is also set to 0 if  the  CR
       character is actually transmitted.

       The delay bits specify how long transmission stops to allow for mechan-
       ical or other movement when certain characters are sent to  the	termi-
       nal.   In  all cases a value of 0 indicates no delay.  If OFILL is set,
       fill characters will be transmitted for delay instead of	a timed	delay.
       This  is	 useful	 for high baud rate terminals that need	only a minimal
       delay.  If OFDEL	is set,	the fill character is DEL, otherwise NUL.

       If a form-feed or vertical-tab delay is specified, it lasts for about 2
       seconds.

       New-line	 delay lasts about 0.10	seconds.  If ONLRET is set, the	RETURN
       delays are used instead of the NEWLINE delays.  If OFILL	 is  set,  two
       fill characters will be transmitted.

       Carriage-return	delay  type 1 is dependent on the current column posi-
       tion, type 2 is about 0.10 seconds, and type 3 is about	0.15  seconds.
       If  OFILL  is set, delay	type 1 transmits two fill characters, and type
       2, four fill characters.

       Horizontal-tab delay type 1 is dependent	on the	current	 column	 posi-
       tion.   Type  2	is  about  0.10	seconds.  Type 3, specified by TAB3 or
       XTABS, specifies	that TAB characters are	 to  be	 expanded  into	 SPACE
       characters.   If	 OFILL is set, two fill	characters will	be transmitted
       for any delay.

       Backspace delay lasts about 0.05	seconds.  If OFILL is  set,  one  fill
       character will be transmitted.

       The actual delays depend	on line	speed and system load.

       The initial output control value	is OPOST, ONLCR, XTABS.

       The c_cflag field describes the hardware	control	of the terminal:

	      CBAUD   0000017	    Baud rate:
		B0    0		    Hang up
		B50   0000001	    50 baud
		B75   0000002	    75 baud
		B110  0000003	    110	baud
		B134  0000004	    134.5 baud
		B150  0000005	    150	baud
		B200  0000006	    200	baud
		B300  0000007	    300	baud
		B600  0000010	    600	baud
		B1200 0000011	    1200 baud
		B1800 0000012	    1800 baud
		B2400 0000013	    2400 baud
		B4800 0000014	    4800 baud
		B9600 0000015	    9600 baud
		B19200		    000001619200 baud
		B38400		    000001738400 baud
	      CSIZE   0000060	    Character size:
		CS5   0		    5 bits
		CS6   0000020	    6 bits
		CS7   0000040	    7 bits
		CS8   0000060	    8 bits
	      CSTOPB  0000100	    Send two stop bits,	else one.
	      CREAD   0000200	    Enable receiver.
	      PARENB  0000400	    Parity enable.
	      PARODD  0001000	    Odd	parity,	else even.
	      HUPCL   0002000	    Hang up on last close.
	      CLOCAL  0004000	    Local line,	else dial-up.
	      CIBAUD  03600000	    Input baud rate, if	different from output rate.
	      CRTSCTS 020000000000  Enable RTS/CTS flow	control.

       The  CBAUD bits specify the baud	rate.  The zero	baud rate, B0, is used
       to hang up the connection.  If B0 is specified, the modem control lines
       will  cease  to	be asserted.  Normally,	this will disconnect the line.
       If the CIBAUD bits are not zero,	they specify the input baud rate, with
       the  CBAUD  bits	specifying the output baud rate; otherwise, the	output
       and input baud rates are	both specified by the CBAUD bits.  The	values
       for  the	 CIBAUD	 bits  are  the	same as	the values for the CBAUD bits,
       shifted left IBSHIFT bits.  For	any  particular	 hardware,  impossible
       speed changes are ignored.

       The CSIZE bits specify the character size in bits for both transmission
       and reception.  This size does not include the parity bit, if any.   If
       CSTOPB is set, two stop bits are	used, otherwise	one stop bit.  For ex-
       ample, at 110 baud, two stop bits are required.

       If PARENB is set, parity	generation and detection is enabled and	a par-
       ity  bit	 is added to each character.  If parity	is enabled, the	PARODD
       flag specifies odd parity if set, otherwise even	parity is used.

       If CREAD	is set,	the receiver is	enabled.  Otherwise no characters will
       be received.

       If  HUPCL  is set, the modem control lines for the port will be discon-
       nected when the last process with the line open	closes	it  or	termi-
       nates.

       If  CLOCAL is set, a connection does not	depend on the state of the mo-
       dem status lines.  Otherwise modem control is assumed.

       If CRTSCTS is set, and the terminal has modem control lines  associated
       with  it,  the Request To Send (RTS) modem control line will be raised,
       and output will occur only if the Clear To Send (CTS) modem status line
       is  raised.   If	 the  CTS modem	status line is lowered,	output is sus-
       pended until CTS	is raised.  Some hardware may not support  this	 func-
       tion, and other hardware	may not	permit it to be	disabled; in either of
       these cases, the	state of the CRTSCTS flag is ignored.

       The initial hardware control value after	open  is  B9600,  CS7,	CREAD,
       PARENB.

   Local Modes
       The  c_lflag field of the argument structure is used by the line	disci-
       pline to	control	terminal functions.  The basic	line  discipline  pro-
       vides the following:

	      ISIG    0000001	Enable signals.
	      ICANON  0000002	Canonical input	(erase and kill	processing).
	      XCASE   0000004	Canonical upper/lower presentation.
	      ECHO    0000010	Enable echo.
	      ECHOE   0000020	Echo erase character as	BS-SP-BS.
	      ECHOK   0000040	Echo NL	after kill character.
	      ECHONL  0000100	Echo NL.
	      NOFLSH  0000200	Disable	flush after interrupt or quit.
	      TOSTOP  0000400	Send SIGTTOU for background output.
	      ECHOCTL 0001000	Echo control characters	as ^char, delete as ^?.
	      ECHOPRT 0002000	Echo erase character as	character erased.
	      ECHOKE  0004000	BS-SP-BS erase entire line on line kill.
	      FLUSHO  0020000	Output is being	flushed.
	      PENDIN  0040000	Retype pending input at	next read or input character.
	      IEXTEN  0100000	Recognize all specials (if clear, POSIX	only).

       If  ISIG	 is  set,  each	input character	is checked against the special
       control characters INTR,	QUIT, and SUSP.	 If an input character matches
       one  of	these  control	characters,  the function associated with that
       character is performed.	If ISIG	is not set, no checking	is done.  Thus
       these special input functions are possible only if ISIG is set.

       If ICANON is set, canonical processing is enabled.  This	is affected by
       the IEXTEN bit (see Special Characters above).  This enables the	erase,
       word erase, kill, and reprint edit functions, and the assembly of input
       characters into lines delimited by NL, EOF, EOL,	and EOL2.   If	ICANON
       is  not set, read requests are satisfied	directly from the input	queue.
       A read will not be satisfied until at least MIN	characters  have  been
       received	 or  the  timeout  value  TIME has expired between characters.
       This allows fast	bursts of input	to be read efficiently while still al-
       lowing  single  character  input.   The time value represents tenths of
       seconds.	 See the Non-canonical Mode Input Processing section for  more
       details.

       If XCASE	is set,	and if ICANON is set, an upper-case letter is accepted
       on input	by preceding it	with a \ character, and	is output preceded  by
       a \ character.  In this mode, the following escape sequences are	gener-
       ated on output and accepted on input:

	      for:   use:
	      `	     \'
	      |	     \!
	      ~	     \^
	      {	     \(
	      }	     \)
	      \	     \\

       For example, A is input as \a, \n as \\n, and \N	as \\\n.

       If ECHO is set, characters are echoed as	received.  If ECHO is not set,
       input characters	are not	echoed.

       If  ECHOCTL  is	not set, all control characters	(characters with codes
       between 0 and 37	octal) are echoed as themselves.  If ECHOCTL  is  set,
       all  control characters other than ASCII	TAB, ASCII NL, the START char-
       acter, and the STOP character, are echoed as ^X,	where X	is the charac-
       ter  given by adding 100	octal to the control character's code (so that
       the character with octal	code 1 is echoed as `^A'), and the  ASCII  DEL
       character, with code 177	octal, is echoed as `^?'.

       When ICANON is set, the following echo functions	are possible:

       o      If ECHO and ECHOE	are set, and ECHOPRT is	not set, the ERASE and
	      WERASE characters	are echoed as one or  more  ASCII  BS  SP  BS,
	      which will clear the last	character(s) from a CRT	screen.

       o      If  ECHO and ECHOPRT are set, the	first ERASE and	WERASE charac-
	      ter in a sequence	echoes as a  backslash	(\)  followed  by  the
	      characters being erased.	Subsequent ERASE and WERASE characters
	      echo the characters being	erased,	in reverse  order.   The  next
	      non-erase	character types	a slash	(/) before it is echoed.

       o      If  ECHOKE  is set, the kill character is	echoed by erasing each
	      character	on the line from the screen (using the	mechanism  se-
	      lected by	ECHOE and ECHOPRT).

       o      If ECHOK is set, and ECHOKE is not set, the NL character will be
	      echoed after the kill character to emphasize that	the line  will
	      be deleted.  Note: an escape character (\) or an LNEXT character
	      preceding	the erase or kill character removes any	special	 func-
	      tion.

       o      If  ECHONL  is set, the NL character will	be echoed even if ECHO
	      is not set.  This	is useful for terminals	set to local echo (so-
	      called half duplex).

       o      If  ECHOCTL  is not set, the EOF character is not	echoed,	unless
	      it is escaped.  Because EOT is the default EOF  character,  this
	      prevents	terminals  that	 respond  to  EOT from hanging up.  If
	      ECHOCTL is set, the EOF character	is echoed; if it  is  not  es-
	      caped,  after it is echoed, one backspace	character is output if
	      it is echoed as itself, and two backspace	characters are	echoed
	      if it is echoed as ^X.

       If NOFLSH is set, the normal flush of the input and output queues asso-
       ciated with the INTR, QUIT, and SUSP characters will not	be done.

       If TOSTOP is set, the signal SIGTTOU is sent to a process that tries to
       write  to  its  controlling  terminal if	it is not in the distinguished
       process group for  that	terminal.   This  signal  normally  stops  the
       process.	  Otherwise, the output	generated by that process is output to
       the current output stream.  Processes that  are	blocking  or  ignoring
       SIGTTOU signals are excepted and	allowed	to produce output.

       If FLUSHO is set, data written to the terminal will be discarded.  This
       bit is set when the FLUSH character is typed.  A	program	can cancel the
       effect of typing	the FLUSH character by clearing	FLUSHO.

       If  PENDIN  is  set,  any  input	that has not yet been read will	be re-
       printed when the	next character arrives as input.

       The initial line-discipline control value is ISIG, ICANON, ECHO.

   Minimum and Timeout
       The MIN and TIME	values are described above  under  Non-canonical  Mode
       Input Processing.  The initial value of MIN is 1, and the initial value
       of TIME is 0.

   Termio Structure
       The System V termio structure is	used by	other ioctl() calls; it	is de-
       fined by	<sys/termio.h> as:

	      #define	   NCC	8
	      struct	   termio {
		    unsigned	short	c_iflag;/* input modes */
		    unsigned	short	c_oflag;/* output modes	*/
		    unsigned	short	c_cflag;/* control modes */
		    unsigned	short	c_lflag;/* local modes */
		    char	c_line;	/* line	discipline */
		    unsigned	char	c_cc[NCC];/* control chars */
	      };

       The special control characters are defined by the array c_cc.  The rel-
       ative positions for each	function are as	follows:
	      0	  VINTR
	      1	  VQUIT
	      2	  VERASE
	      3	  VKILL
	      4	  VEOF
	      5	  VEOL
	      6	  VEOL2
	      7	  reserved

       The calls that use the termio structure only affect the flags and  con-
       trol  characters	 that can be stored in the termio structure; all other
       flags and control characters are	unaffected.

   Terminal Size
       The number of lines and columns on the terminal's display (or page,  in
       the  case of printing terminals)	is specified in	the winsize structure,
       defined by <sys/termios.h>.  Several ioctl() system calls that fetch or
       change these parameters use this	structure:

	      struct winsize {
		    unsigned short	ws_row;/* rows,	in characters */
		    unsigned short	ws_col;/* columns, in characters */
		    unsigned short	ws_xpixel;/* horizontal	size, pixels - not used	*/
		    unsigned short	ws_ypixel;/* vertical size, pixels - not used */
	      };

   Modem Lines
       On  special  files  representing	 serial	ports, the modem control lines
       supported by the	hardware can be	read and the modem status  lines  sup-
       ported by the hardware can be changed.  The following modem control and
       status lines may	 be  supported	by  a  device;	they  are  defined  by
       <sys/termios.h>:

	      TIOCM_LE	 0001	    line enable
	      TIOCM_DTR	 0002	    data terminal ready
	      TIOCM_RTS	 0004	    request to send
	      TIOCM_ST	 0010	    secondary transmit
	      TIOCM_SR	 0020	    secondary receive
	      TIOCM_CTS	 0040	    clear to send
	      TIOCM_CAR	 0100	    carrier detect
	      TIOCM_RNG	 0200	    ring
	      TIOCM_DSR	 0400	    data set ready

       TIOCM_CD	 is a synonym for TIOCM_CAR, and TIOCM_RI is a synonym for TI-
       OCM_RNG.

       Not all of these	will necessarily be supported by  any  particular  de-
       vice; check the manual page for the device in question.

IOCTLS
       The  ioctl()  calls  supported by devices and STREAMS modules providing
       the termios interface are listed	below.	Some calls  may	 not  be  sup-
       ported by all devices or	modules.

       Unless otherwise	noted for a specific ioctl() call, these functions are
       restricted from use by background processes.  Attempts to perform these
       calls  will  cause the process group of the process performing the call
       to be sent a SIGTTOU signal.  If	the process is ignoring	 SIGTTOU,  has
       SIGTTOU blocked,	or is in the middle of process creation	using vfork(),
       the process will	be allowed to perform the call and the SIGTTOU	signal
       will not	be sent.

       TCGETS		 The  argument	is  a  pointer to a termios structure.
			 The  current  terminal	 parameters  are  fetched  and
			 stored	 into  that  structure.	  This call is allowed
			 from a	background process; however,  the  information
			 may subsequently be changed by	a foreground process.

       TCSETS		 The  argument	is  a  pointer to a termios structure.
			 The current terminal parameters are set from the val-
			 ues  stored in	that structure.	 The change is immedi-
			 ate.

       TCSETSW		 The argument is a pointer  to	a  termios  structure.
			 The current terminal parameters are set from the val-
			 ues stored in that structure.	The change occurs  af-
			 ter all characters queued for output have been	trans-
			 mitted.  This form should be used when	 changing  pa-
			 rameters that will affect output.

       TCSETSF		 The  argument	is  a  pointer to a termios structure.
			 The current terminal parameters are set from the val-
			 ues  stored in	that structure.	 The change occurs af-
			 ter all characters queued for output have been	trans-
			 mitted; all characters	queued for input are discarded
			 and then the change occurs.

       TCGETA		 The argument is a pointer to a	termio structure.  The
			 current  terminal  parameters	are fetched, and those
			 parameters that can be	stored in a  termio  structure
			 are stored into that structure.  This call is allowed
			 from a	background process; however,  the  information
			 may subsequently be changed by	a foreground process.

       TCSETA		 The  argument	is  a  pointer	to a termio structure.
			 Those terminal	parameters that	can  be	 stored	 in  a
			 termio	 structure  are	 set from the values stored in
			 that structure.  The change is	immediate.

       TCSETAW		 The argument is a  pointer  to	 a  termio  structure.
			 Those	terminal  parameters  that  can	be stored in a
			 termio	structure are set from the  values  stored  in
			 that  structure.  The change occurs after all charac-
			 ters queued for output	have been  transmitted.	  This
			 form  should  be  used	 when changing parameters that
			 will affect output.

       TCSETAF		 The argument is a  pointer  to	 a  termio  structure.
			 Those	terminal  parameters  that  can	be stored in a
			 termio	structure are set from the  values  stored  in
			 that  structure.  The change occurs after all charac-
			 ters queued for output	 have  been  transmitted;  all
			 characters  queued  for  input	are discarded and then
			 the change occurs.

       TCSBRK		 The argument is an int	value.	Wait for the output to
			 drain.	  If  the  argument  is	 0,  then send a break
			 (zero-valued bits for 0.25 seconds). This  define  is
			 available by #include <sys/termio.h>

       TCXONC		 Start/stop  control.	The  argument is an int	value.
			 If the	argument is TCOOFF  (0),  suspend  output;  if
			 TCOON	(1),  restart suspended	output;	if TCIOFF (2),
			 suspend input;	if TCION (3), restart suspended	input.

       TCFLSH		 The argument is an int	value.	 If  the  argument  is
			 TCIFLUSH (0), flush the input queue; if TCOFLUSH (1),
			 flush the output queue; if TCIOFLUSH (2), flush  both
			 the input and output queues.

       TIOCEXCL		 The  argument	is  ignored.   Exclusive-use  mode  is
			 turned	on; no further opens are permitted  until  the
			 file  has  been closed, or a TIOCNXCL is issued.  The
			 default on open of a terminal file is that  exclusive
			 use  mode  is off.  This ioctl() is only available by
			 #include <sys/ttold.h>	.

       TIOCNXCL		 The  argument	is  ignored.   Exclusive-use  mode  is
			 turned	 off.	This ioctl() is	only available by #in-
			 clude <sys/ttold.h>.

       TIOCSCTTY	 The argument is an int.  The system will  attempt  to
			 assign	 the terminal as the caller's controlling ter-
			 minal (see The	Controlling Terminal above).   If  the
			 caller	 is  not the super-user	and/or the argument is
			 not 1,	all of the normal permission checks apply.  If
			 the  caller  is  the super-user and the argument is 1
			 the terminal will be assigned as the controlling ter-
			 minal	even if	the terminal was currently in use as a
			 controlling terminal by  another  session.   getty(8)
			 uses this method to acquire controlling terminals for
			 login(1) because there	exists a  possibility  that  a
			 daemon	  process   may	  obtain  the  console	before
			 getty(8).

       TIOCGPGRP	 The argument is a pointer to an int.  Set  the	 value
			 of  that  int	to the process group ID	of the distin-
			 guished process group associated with	the  terminal.
			 This  call is allowed from a background process; how-
			 ever, the information may subsequently	be changed  by
			 a  foreground	process.  This ioctl() exists only for
			 backward compatibility, use tcgetpgrp(3V).

       TIOCSPGRP	 The argument is a pointer to an int.	Associate  the
			 process  group	whose process group ID is specified by
			 the value of that int with  the  terminal.   The  new
			 process  group	 value	must  be in the	range of valid
			 process group ID values, or  it  must	be  zero  ("no
			 process  group").  Otherwise, the error EINVAL	is re-
			 turned.  If any processes exist with a	process	ID  or
			 process  group	ID that	is the same as the new process
			 group value, then those processes must	have the  same
			 real  or  saved user ID as the	real or	effective user
			 ID of the calling process or be  descendants  of  the
			 calling process, or the effective user	ID of the cur-
			 rent process must be super-user.  Otherwise, the  er-
			 ror  EPERM is returned.  This ioctl() exists only for
			 backward compatibility, use tcsetpgrp(), see  tcgetp-
			 grp(3V).

       TIOCOUTQ		 The  argument	is a pointer to	an int.	 Set the value
			 of that int to	the number of characters in the	output
			 stream	 that  have not	yet been sent to the terminal.
			 This call is allowed from a background	process.

       TIOCSTI		 The argument is a pointer to a	 char.	 Pretend  that
			 character had been received as	input.

       TIOCGWINSZ	 The  argument	is  a  pointer to a winsize structure.
			 The terminal driver's notion of the terminal size  is
			 stored	 into  that  structure.	  This call is allowed
			 from a	background process.

       TIOCSWINSZ	 The argument is a pointer  to	a  winsize  structure.
			 The  terminal driver's	notion of the terminal size is
			 set from the values specified in that structure.   If
			 the  new  sizes  are  different from the old sizes, a
			 SIGWINCH signal is sent to the	process	group  of  the
			 terminal.

       TIOCMGET		 The  argument	is  a  pointer to an int.  The current
			 state of the modem status lines is fetched and	stored
			 in  the int pointed to	by the argument.  This call is
			 allowed from a	background process.

       TIOCMBIS		 The argument is a pointer to an int whose value is  a
			 mask  containing modem	control	lines to be turned on.
			 The control lines whose bits are set in the  argument
			 are turned on;	no other control lines are affected.

       TIOCMBIC		 The  argument is a pointer to an int whose value is a
			 mask containing modem control lines to	be turned off.
			 The  control lines whose bits are set in the argument
			 are turned off; no other control lines	are affected.

       TIOCMSET		 The argument is a pointer to an int containing	a  new
			 set  of modem control lines.  The modem control lines
			 are turned on or off, depending on  whether  the  bit
			 for that mode is set or clear.

       TIOCGSOFTCAR	 The  argument is a pointer to an int whose value is 1
			 or 0, depending on whether the	software  carrier  de-
			 tect is turned	on or off.

       TIOCSSOFTCAR	 The  argument is a pointer to an int whose value is 1
			 or 0.	The value of the integer should	be 0  to  turn
			 off software carrier, or 1 to turn it on.

SEE ALSO
       csh(1),	login(1), stty(1V), fork(2V), getpgrp(2V), ioctl(2), open(2V),
       read(2V),  sigvec(2),  vfork(2),	 tcgetpgrp(3V),	  tty(4),   ttytab(5),
       getty(8), init(8), ttysoftcar(8)

				15 January 1990			     TERMIO(4)

NAME | SYNOPSIS | DESCRIPTION | IOCTLS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=termio&sektion=4&manpath=SunOS+4.1.3>

home | help