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

FreeBSD Manual Pages


home | help
PTY(4)		       FreeBSD Kernel Interfaces Manual			PTY(4)

     pty, ptm -- pseudo	terminal driver

     pseudo-device pty [count]

     The pty driver provides support for a device-pair termed a	pseudo
     terminal.	A pseudo terminal is a pair of character devices, a master de-
     vice and a	slave device.  The slave device	provides to a process an in-
     terface identical to that described in tty(4).  However, whereas all
     other devices which provide the interface described in tty(4) have	a
     hardware device of	some sort behind them, the slave device	has, instead,
     another process manipulating it through the master	half of	the pseudo
     terminal.	That is, anything written on the master	device is given	to the
     slave device as input and anything	written	on the slave device is pre-
     sented as input on	the master device.

     In	configuring, if	an optional count is given in the specification, space
     for that number of	pseudo terminal	pairs is preallocated.	If the count
     is	missing	or is less than	2, a default count of 8	is used.  This is not
     a hard limit--space for additional	pseudo terminal	pairs is allocated on
     demand up to the limit of 992.

     The following ioctl(2) calls apply	only to	pseudo terminals and may only
     be	applied	to the pty master:

     TIOCEXT int *on
		 If on points to a non-zero integer, enable external process-
		 ing.  Otherwise, disable external processing.

		 While external	processing is enabled, input line editing,
		 character echo, and mapping of	control	characters to signals
		 are disabled regardless of the	terminal's termios(4) set-

     TIOCSTOP void
		 Stops output to a terminal (e.g., like	typing `^S').

     TIOCSTART void
		 Restarts output (stopped by TIOCSTOP or by typing `^S').

     TIOCPKT int *on
		 If on points to a non-zero integer, enable packet mode.  Oth-
		 erwise, disable packet	mode.

		 While packet mode is enabled, each subsequent read(2) from
		 the pty master	will either return data	written	to the pty
		 slave preceded	by a zero byte (symbolically defined as
		 TIOCPKT_DATA),	or a single byte reflecting control status in-
		 formation.  In	the latter case, the byte is an	inclusive-or
		 of zero or more of the	bits:

		 TIOCPKT_FLUSHREAD   whenever the read queue for the terminal
				     is	flushed.

		 TIOCPKT_FLUSHWRITE  whenever the write	queue for the terminal
				     is	flushed.

		 TIOCPKT_STOP	     whenever output to	the terminal is
				     stopped a la `^S'.

		 TIOCPKT_START	     whenever output to	the terminal is

		 TIOCPKT_DOSTOP	     whenever t_stopc is `^S' and t_startc is

		 TIOCPKT_NOSTOP	     whenever the start	and stop characters
				     are not `^S/^Q'.

		 TIOCPKT_IOCTL	     whenever the terminal's termios(4)	set-
				     tings change while	external processing is

				     Additionally, when	the TIOCPKT_IOCTL bit
				     is	set, the remainder of the data read
				     from the pty master is a copy of the new
				     termios(4)	structure.

		 While this mode is in use, the	presence of control status in-
		 formation to be read from the master side may be detected by
		 a select(2) for exceptional conditions.

     TIOCUCNTL int *on
		 If on points to a non-zero integer, enable a mode that	allows
		 a small number	of simple user ioctl(2)	commands to be passed
		 through the pseudo terminal, using a protocol similar to that
		 of TIOCPKT.  The TIOCUCNTL and	TIOCPKT	modes are mutually ex-
		 clusive.  This	mode is	enabled	from the master	side of	a
		 pseudo	terminal.  Each	subsequent read(2) from	the master
		 side will return data written on the slave part of the	pseudo
		 terminal preceded by a	zero byte, or a	single byte reflecting
		 a user	control	operation on the slave side.  A	user control
		 command consists of a special ioctl(2)	operation with no
		 data; the command is given as UIOCCMD(n), where n is a	number
		 in the	range 1-255.  The operation value n will be received
		 as a single byte on the next read(2) from the master side.
		 The ioctl(2) UIOCCMD(0) is a no-op that may be	used to	probe
		 for the existence of this facility.

		 While this mode is in use, any	of the TIOCSBRK	and TIOCCBRK
		 ioctl requests	issued on the slave part of the	pseudo termi-
		 nal will be translated	to a TIOCUCNTL_SBRK or TIOCUCNTL_CBRK
		 user command on the master side.

		 As with TIOCPKT mode, command operations may be detected with
		 a select(2) for exceptional conditions.

     TIOCREMOTE	int *on
		 If on points to a non-zero integer, enable a mode for the
		 master	half of	a pseudo terminal, independent of TIOCPKT.
		 This mode causes input	to the pseudo terminal to be flow con-
		 trolled and not input edited (regardless of the terminal
		 mode).	 Each write to the control terminal produces a record
		 boundary for the process reading the terminal.	 In normal us-
		 age, a	write of data is like the data typed as	a line on the
		 terminal; a write of 0	bytes is like typing an	end-of-file
		 character.  TIOCREMOTE	can be used when doing remote line
		 editing in a window manager, or whenever flow controlled in-
		 put is	required.

     The standard way to allocate pty devices is through openpty(3), a func-
     tion which	internally uses	a PTMGET ioctl(2) call on the /dev/ptm device.
     The PTMGET	command	allocates a free pseudo	terminal, changes its owner-
     ship to the caller, revokes the access privileges for all previous	users,
     opens the file descriptors	for the	master and slave devices and returns
     them to the caller	in struct ptmget.

	   struct ptmget {
		   int	   cfd;
		   int	   sfd;
		   char	   cn[16];
		   char	   sn[16];

     The cfd and sfd fields are	the file descriptors for the controlling and
     slave terminals.  The cn and sn fields are	the file names of the control-
     ling and slave devices.

     /dev/pty[p-zP-T][0-9a-zA-Z]   master pseudo terminals
     /dev/tty[p-zP-T][0-9a-zA-Z]   slave pseudo	terminals
     /dev/ptm			   pseudo terminal management device

     openpty(3), tty(4)

     The pty driver appeared in	4.2BSD.	 The /dev/ptm device was added in
     OpenBSD 3.5.

     The ptm device will only work on systems where the	/dev directory has
     been properly populated with pty device nodes following the naming	con-
     vention used in OpenBSD.  Since ptm impersonates the super	user for some
     operations	it needs to perform to complete	the allocation of a pseudo
     terminal, the /dev	directory must also be writeable by the	super user.

FreeBSD	13.0			 June 5, 2018			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help