diff options
Diffstat (limited to 'usr/src/man/man7d')
| -rw-r--r-- | usr/src/man/man7d/Makefile | 6 | ||||
| -rw-r--r-- | usr/src/man/man7d/ptm.7d | 338 | ||||
| -rw-r--r-- | usr/src/man/man7d/pts.7d | 107 | ||||
| -rw-r--r-- | usr/src/man/man7d/pty.7d | 495 | ||||
| -rw-r--r-- | usr/src/man/man7d/zcons.7d | 129 |
5 files changed, 572 insertions, 503 deletions
diff --git a/usr/src/man/man7d/Makefile b/usr/src/man/man7d/Makefile index af38c7a9bd..78b9601e29 100644 --- a/usr/src/man/man7d/Makefile +++ b/usr/src/man/man7d/Makefile @@ -16,7 +16,7 @@ # Copyright 2016 Hans Rosenfeld <rosenfeld@grumpf.hope-2000.org> # Copyright 2018 Nexenta Systems, Inc. # Copyright 2020 Peter Tribble -# Copyright 2021 Oxide Computer Company +# Copyright 2022 Oxide Computer Company # include $(SRC)/Makefile.master @@ -105,7 +105,6 @@ _MANFILES= aac.7d \ poll.7d \ profile.7d \ ptm.7d \ - pts.7d \ pty.7d \ qlc.7d \ ramdisk.7d \ @@ -256,6 +255,7 @@ _MANLINKS= 1394.7d \ firewire.7d \ kmem.7d \ lo0.7d \ + pts.7d \ ticots.7d \ ticotsord.7d \ urandom.7d \ @@ -279,6 +279,8 @@ firewire.7d := LINKSRC = ieee1394.7d lo0.7d := LINKSRC = ipnet.7d +pts.7d := LINKSRC = ptm.7d + allkmem.7d := LINKSRC = mem.7d kmem.7d := LINKSRC = mem.7d diff --git a/usr/src/man/man7d/ptm.7d b/usr/src/man/man7d/ptm.7d index 83c7830293..adf66469bc 100644 --- a/usr/src/man/man7d/ptm.7d +++ b/usr/src/man/man7d/ptm.7d @@ -4,89 +4,255 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH PTM 7D "Feb 5, 1997" -.SH NAME -ptm \- STREAMS pseudo-tty master driver -.SH DESCRIPTION -.sp -.LP -The pseudo-tty subsystem simulates a terminal connection, where the master side -represents the terminal and the slave represents the user process's special -device end point. In order to use the pseudo-tty subsystem, a node for the -master side driver \fB/dev/ptmx\fR and \fBN\fR number of nodes for the slave -driver must be installed. See \fBpts\fR(7D). The master device is set up as a -cloned device where its major device number is the major for the clone device -and its minor device number is the major for the \fBptm\fR driver. There are no -nodes in the file system for master devices. The master pseudo driver is opened -using the \fBopen\fR(2) system call with \fB/dev/ptmx\fR as the device -parameter. The clone open finds the next available minor device for the -\fBptm\fR major device. -.sp -.LP -A master device is available only if it and its corresponding slave device are -not already open. When the master device is opened, the corresponding slave -device is automatically locked out. Only one open is allowed on a master -device. Multiple opens are allowed on the slave device. After both the master -and slave have been opened, the user has two file descriptors which are the end -points of a full duplex connection composed of two streams which are -automatically connected at the master and slave drivers. The user may then push -modules onto either side of the stream pair. -.sp -.LP -The master and slave drivers pass all messages to their adjacent queues. Only -the \fBM_FLUSH\fR needs some processing. Because the read queue of one side is -connected to the write queue of the other, the \fBFLUSHR\fR flag is changed to -the \fBFLUSHW\fR flag and vice versa. When the master device is closed an -\fBM_HANGUP\fR message is sent to the slave device which will render the device -unusable. The process on the slave side gets the errno \fBEIO\fR when -attempting to write on that stream but it will be able to read any data -remaining on the stream head read queue. When all the data has been read, -\fBread()\fR returns 0 indicating that the stream can no longer be used. On the -last close of the slave device, a 0-length message is sent to the master -device. When the application on the master side issues a \fBread()\fR or -\fBgetmsg()\fR and 0 is returned, the user of the master device decides whether -to issue a \fBclose()\fR that dismantles the pseudo-terminal subsystem. If the -master device is not closed, the pseudo-tty subsystem will be available to -another user to open the slave device. -.sp -.LP -If \fBO_NONBLOCK\fR or \fBO_NDELAY\fR is set, read on the master side returns -\(mi1 with errno set to \fBEAGAIN\fR if no data is available, and write returns -\(mi1 with errno set to \fBEAGAIN\fR if there is internal flow control. -.SH IOCTLS -.sp -.LP -The master driver supports the \fBISPTM\fR and \fBUNLKPT\fR ioctls that are -used by the functions \fBgrantpt\fR(3C), \fBunlockpt\fR(3C) and -\fBptsname\fR(3C). The ioctl \fBISPTM\fR determines whether the file descriptor -is that of an open master device. On success, it returns the 0. The ioctl -\fBUNLKPT\fR unlocks the master and slave devices. It returns 0 on success. On -failure, the errno is set to \fBEINVAL\fR indicating that the master device is -not open. -.SH FILES -.sp -.ne 2 -.na -\fB\fB/dev/ptmx\fR\fR -.ad -.RS 14n -master clone device -.RE - -.sp -.ne 2 -.na -\fB\fB/dev/pts/M\fR\fR -.ad -.RS 14n -slave devices (M = 0 -> N-1) -.RE - -.SH SEE ALSO -.sp -.LP -\fBgrantpt\fR(3C), \fBptsname\fR(3C), \fBunlockpt\fR(3C), \fBpckt\fR(7M), -\fBpts\fR(7D) -.sp -.LP -\fISTREAMS Programming Guide\fR +.\" Copyright 2022 Oxide Computer Company +.Dd February 5, 2022 +.Dt PTM 7D +.Os +.Sh NAME +.Nm ptm , +.Nm pts +.Nd STREAMS pseudo-terminal manager and subsidiary drivers +.Sh SYNOPSIS +.Pa /dev/ptmx +.Pp +.Pa /dev/pts/* +.Sh DESCRIPTION +The pseudo-terminal subsystem simulates a terminal connection, where the +manager side represents the terminal and the subsidiary represents the user +process's special device end point. +The manager device is set up as a cloned device where its major device number +is the major for the clone device and its minor device number is the major for +the +.Nm ptm +driver; see +.Dv CLONE_DEV +in +.Xr ddi_create_minor_node 9F . +.Pp +There are no nodes in the file system for manager devices. +The manager pseudo driver is opened using the +.Xr open 2 +system call with +.Pa /dev/ptmx +as the device parameter. +The clone open finds the next available minor device for the +.Nm ptm +major device. +.Pp +A manager device is only available if it and its corresponding subsidiary +device are not already open. +Only one open is allowed on a manager device. +Multiple opens are allowed on the subsidiary device. +.Pp +When the manager device is opened, the corresponding subsidiary device is +automatically locked out. +No user may open the subsidiary device until its permissions are adjusted and +the device is unlocked by calling the functions +.Xr grantpt 3C +and +.Xr unlockpt 3C . +The user can then invoke the +.Xr open 2 +system call with the device name returned by the +.Xr ptsname 3C +function. +.Pp +After both the manager and subsidiary have been opened, the user has two file +descriptors which are the end points of a full duplex connection composed of +two streams which are automatically connected at the manager and subsidiary +drivers. +The user may then push modules onto either side of the stream pair. +Unless compiled in XPG4v2 mode +.Po +see +.Sx "XPG4v2 MODE" +.Pc , +the consumer needs to push the +.Xr ptem 7M +and +.Xr ldterm 7M +modules onto the subsidiary device to get terminal semantics. +.Pp +The manager and subsidiary drivers pass all messages to their adjacent queues. +Only the +.Dv M_FLUSH +needs some processing. +Because the read queue of one side is connected to the write queue of the +other, the +.Dv FLUSHR +flag is changed to the +.Dv FLUSHW +flag and vice versa. +.Pp +When the manager device is closed, an +.Dv M_HANGUP +message is sent to the subsidiary device which will render the device unusable. +The process on the subsidiary side gets an +.Er EIO +error when attempting to write on that stream, but it will be able to read +any data remaining on the stream head read queue. +When all the data has been read, +.Xr read 2 +returns +.Sy 0 +indicating that the stream can no longer be used. +.Pp +On the last close of the subsidiary device, a 0-length message is sent to the +manager device. +When the application on the manager side issues a +.Xr read 2 +or +.Xr getmsg 2 +and +.Sy 0 +is returned, the user of the manager device decides whether to issue a +.Xr close 2 +that dismantles the entire pseudo-terminal. +If the manager device is not closed, the pseudo-terminal will be available to +another user to open the subsidiary device. +.Pp +Since 0-length messages are used to indicate that the process on the +subsidiary side has closed, and should be interpreted that way by the process +on the manager side, applications on the subsidiary side should not write +0-length messages. +Unless the application is compiled in XPG4v2 mode +.Po +see +.Sx "XPG4v2 MODE" +.Pc , +then any 0-length messages written to the subsidiary device will be discarded +by the +.Xr ptem 7M +module. +.Pp +If +.Dv O_NONBLOCK +or +.Dv O_NDELAY +is set on the manager side: +.Bl -bullet +.It +Read on the manager side returns +.Sy -1 +with +.Va errno +set to +.Er EAGAIN +if no data is available +.It +Write returns +.Sy -1 +with +.Va errno +set to +.Er EAGAIN +if there is internal flow control +.El +.Pp +Standard STREAMS system calls can access pseudo-terminal devices. +The subsidiary devices support the +.Dv O_NDELAY +and +.Dv O_NONBLOCK +flags. +.Sh XPG4v2 MODE +.Em XPG4v2 +requires that subsidiary pseudo-terminal devices provide the process with an +interface that is identical to the terminal interface, without needing to +explicitly push any modules to achieve this. +It also requires that 0-length messages written on the subsidiary device will +be propagated to the manager device. +.Pp +Experience has shown that most software does not expect subsidiary +pseudo-terminal devices to operate in this manner. +This XPG4v2-compliant behaviour is only enabled in XPG4v2/SUS +.Po +see +.Xr standards 5 +.Pc +mode. +.Sh IOCTLS +The manager driver provides several ioctls to support the +.Xr grantpt 3C , +.Xr unlockpt 3C , +and +.Xr ptsname 3C +functions: +.Bl -tag -width Ds +.It Dv ISPTM +Determines whether the file descriptor is that of an open manager device. +On success, it returns the value +.Sy 0 . +.It Dv UNLKPT +Unlocks the manager and subsidiary devices. +It returns +.Sy 0 +on success. +On failure, +.Vt errno +is set to +.Vt EINVAL +indicating that the manager device is not open. +.El +.Sh FILES +.Bl -tag -width Pa +.It Pa /dev/ptmx +Pseudo-terminal manager clone device. +.It Pa /dev/pts/N +Pseudo-terminal subsidiary devices, where +.Sy N +is a non-negative integer. +Located via calls to +.Xr ptsname 3C . +.El +.Sh EXAMPLES +.Sy Example 1 +Opening the manager and subsidiary device for a pseudo-terminal. +.Bd -literal -offset Ds +#include <stdlib.h> +#include <sys/types.h> +#include <sys/stat.h> +#include <unistd.h> +#include <stropts.h> +#include <fcntl.h> +#include <err.h> +\&... +int fdm, fds; +char *subsidiaryname; +\&... +/* + * NOTE: Portable applications should use posix_openpt(3C) here: + */ +if ((fdm = open("/dev/ptmx", O_RDWR | O_NOCTTY)) < 0) { + err(1, "open manager"); +} +if (grantpt(fdm) != 0 || unlockpt(fdm) != 0 || + (subsidiaryname = ptsname(fdm)) == NULL) { + close(fdm); + err(1, "locate subsidiary"); +} +if ((fds = open(subsidiaryname, O_RDWR | O_NOCTTY)) < 0) { + close(fdm); + err(1, "open subsidiary"); +} +if (ioctl(fds, I_PUSH, "ptem") != 0 || + ioctl(fds, I_PUSH, "ldterm") != 0) { + close(fds); + close(fdm); + err(1, "push modules"); +} +.Ed +.Sh SEE ALSO +.Xr close 2 , +.Xr getmsg 2 , +.Xr open 2 , +.Xr read 2 , +.Xr grantpt 3C , +.Xr posix_openpt 3C , +.Xr ptsname 3C , +.Xr unlockpt 3C , +.Xr standards 5 , +.Xr ldterm 7M , +.Xr pckt 7M , +.Xr ptem 7M , +.Xr ddi_create_minor_node 9F diff --git a/usr/src/man/man7d/pts.7d b/usr/src/man/man7d/pts.7d deleted file mode 100644 index 6ac5bbcbd1..0000000000 --- a/usr/src/man/man7d/pts.7d +++ /dev/null @@ -1,107 +0,0 @@ -'\" te -.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association. -.\" Copyright 1992 Sun Microsystems -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH PTS 7D "Feb 29, 2020" -.SH NAME -pts \- STREAMS pseudo-tty slave driver -.SH DESCRIPTION -The pseudo-tty subsystem simulates a terminal connection, where the master side -represents the terminal and the slave represents the user process's special -device end point. In order to use the pseudo-tty subsystem, a node for the -master side driver \fB/dev/ptmx\fR and N nodes for the slave driver (N is -determined at installation time) must be installed. The names of the slave -devices are \fB/dev/pts/M\fR where \fBM\fR has the values 0 through N-1. When -the master device is opened, the corresponding slave device is automatically -locked out. No user may open that slave device until its permissions are -adjusted and the device unlocked by calling functions \fBgrantpt\fR(3C) and -\fBunlockpt\fR(3C). The user can then invoke the open system call with the name -that is returned by the \fBptsname\fR(3C) function. See the example below. -.sp -.LP -Only one open is allowed on a master device. Multiple opens are allowed on the -slave device. After both the master and slave have been opened, the user has -two file descriptors which are end points of a full duplex connection composed -of two streams automatically connected at the master and slave drivers. The -user may then push modules onto either side of the stream pair. Unless compiled -in XPG4v2 mode (see below), the consumer needs to push the \fBptem\fR(7M) and -\fBldterm\fR(7M) modules onto the slave side of the pseudo-terminal subsystem -to get terminal semantics. -.sp -.LP -The master and slave drivers pass all messages to their adjacent queues. Only -the \fBM_FLUSH\fR needs some processing. Because the read queue of one side is -connected to the write queue of the other, the \fBFLUSHR\fR flag is changed to -the \fBFLUSHW\fR flag and vice versa. When the master device is closed an -\fBM_HANGUP\fR message is sent to the slave device which will render the device -unusable. The process on the slave side gets the errno \fBEIO\fR when -attempting to write on that stream but it will be able to read any data -remaining on the stream head read queue. When all the data has been read, read -returns 0 indicating that the stream can no longer be used. On the last close -of the slave device, a 0-length message is sent to the master device. When the -application on the master side issues a \fBread()\fR or \fBgetmsg()\fR and 0 is -returned, the user of the master device decides whether to issue a -\fBclose()\fR that dismantles the pseudo-terminal subsystem. If the master -device is not closed, the pseudo-tty subsystem will be available to another -user to open the slave device. Since 0-length messages are used to indicate -that the process on the slave side has closed and should be interpreted that -way by the process on the master side, applications on the slave side should -not write 0-length messages. Unless the application is compiled in XPG4v2 mode -(see below) then any 0-length messages written on the slave side will be -discarded by the \fBptem\fR module. -.sp -.LP -The standard STREAMS system calls can access the pseudo-tty devices. The slave -devices support the \fBO_NDELAY\fR and \fBO_NONBLOCK\fR flags. -.SH XPG4v2 MODE -XPG4v2 requires that open of a slave pseudo terminal device provides the -process with an interface that is identical to the terminal interface (without -having to explicitly push any modules to achieve this). It also requires that -0-length messages written on the slave side will be propagated to the master. -.sp -Experience has shown, however, that most software does not expect slave pty -devices to operate in this manner and therefore this XPG4v2-compliant -behaviour is only enabled in XPG4v2/SUS (see \fBstandards\fR(5)) mode. -.SH EXAMPLES -.in +2 -.nf -int fdm fds; -char *slavename; -extern char *ptsname(); - -fdm = open("/dev/ptmx", O_RDWR); /* open master */ -grantpt(fdm); /* change permission of slave */ -unlockpt(fdm); /* unlock slave */ -slavename = ptsname(fdm); /* get name of slave */ -fds = open(slavename, O_RDWR); /* open slave */ -ioctl(fds, I_PUSH, "ptem"); /* push ptem */ -ioctl(fds, I_PUSH, "ldterm"); /* push ldterm*/ -.fi -.in -2 - -.SH FILES -.ne 2 -.na -\fB\fB/dev/ptmx\fR\fR -.ad -.RS 14n -master clone device -.RE - -.sp -.ne 2 -.na -\fB\fB/dev/pts/M\fR\fR -.ad -.RS 14n -slave devices (M = 0 -> N-1) -.RE - -.SH SEE ALSO -\fBgrantpt\fR(3C), \fBptsname\fR(3C), \fBunlockpt\fR(3C), \fBldterm\fR(7M), -\fBptm\fR(7D), \fBptem\fR(7M), \fBstandards\fR(5) -.sp -.LP -\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man7d/pty.7d b/usr/src/man/man7d/pty.7d index e2f85c3224..8e14dd3ea2 100644 --- a/usr/src/man/man7d/pty.7d +++ b/usr/src/man/man7d/pty.7d @@ -3,244 +3,263 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH PTY 7D "Aug 8, 1994" -.SH NAME -pty \- pseudo-terminal driver -.SH DESCRIPTION -.sp -.LP -The \fBpty\fR driver provides support for a pair of devices collectively known -as a \fIpseudo-terminal\fR. The two devices comprising a pseudo-terminal are -known as a \fIcontroller\fR and a \fIslave\fR. The slave device distinguishes -between the \fBB0\fR baud rate and other baud rates specified in the -\fBc_cflag\fR word of the \fBtermios\fR structure, and the \fBCLOCAL\fR flag in -that word. It does not support any of the other \fBtermio\fR(7I) device control -functions specified by flags in the \fBc_cflag\fR word of the \fBtermios\fR -structure and by the \fB\fR\fBIGNBRK\fR\fB, \fR \fB\fR\fBIGNPAR\fR\fB, \fR -\fB\fR\fBPARMRK\fR\fB, \fR or \fBINPCK\fR flags in the \fBc_iflag\fR word of -the \fBtermios\fR structure, as these functions apply only to asynchronous -serial ports. All other \fBtermio\fR(7I) functions must be performed by -\fBSTREAMS\fR modules pushed atop the driver; when a slave device is opened, -the \fBldterm\fR(7M) and \fBttcompat\fR(7M) \fBSTREAMS\fR modules are -automatically pushed on top of the stream, providing the standard -\fBtermio\fR(7I) interface. -.sp -.LP +.\" Copyright 2022 Oxide Computer Company +.Dd February 5, 2022 +.Dt PTY 7D +.Os +.Sh NAME +.Nm pty +.Nd legacy pseudo-terminal driver +.Sh SYNOPSIS +.Pa /dev/pty[p-r]* +.Pp +.Pa /dev/tty[p-r]* +.Sh DESCRIPTION +This driver provides support for legacy static pseudo-terminal devices. +Modern software does not use this driver, preferring instead the STREAMS-based +.Xr ptm 7D +and +.Xr pts 7D +pseudo-terminal drivers, consumed through the portable +.Xr posix_openpt 3C +interface. +.Pp +The +.Nm pty +driver provides support for a pair of devices collectively known +as a +.Em pseudo-terminal . +The two devices comprising a pseudo-terminal are known as a +.Em manager +and a +.Em subsidiary . +The subsidiary device distinguishes between the +.Dv B0 baud rate and other baud rates specified in +the +.Fa c_cflag +field of the +.Vt termios +structure, and the +.Dv CLOCAL +flag in that member. +It does not support any of the other +.Xr termio 7I +device control functions specified by flags in the +.Fa c_cflag +field of the +.Vt termios +structure and by the +.Dv IGNBRK , +.Dv IGNPAR , +.Dv PARMRK , +or +.Dv INPCK +flags in the +.Fa c_iflag +field of the +.Vt termios +structure, as these functions apply only to asynchronous serial ports. +All other +.Xr termio 7I +functions must be performed by STREAMS modules pushed atop the driver; when a +subsidiary device is opened, the +.Xr ldterm 7M +and +.Xr ttcompat 7M +STREAMS modules are automatically pushed on top of the stream, providing the +standard +.Xr termio 7I +interface. +.Pp Instead of having a hardware interface and associated hardware that supports the terminal functions, the functions are implemented by another process -manipulating the controller device of the pseudo-terminal. -.sp -.LP -The controller and the slave devices of the pseudo-terminal are tightly -connected. Any data written on the controller device is given to the slave -device as input, as though it had been received from a hardware interface. Any -data written on the slave terminal can be read from the controller device -(rather than being transmitted from a \fBUAR\fR). -.sp -.LP -By default, 48 pseudo-terminal pairs are configured as follows: -.sp -.in +2 -.nf -/dev/pty[p-r][0-9a-f] controller devices -/dev/tty[p-r][0-9a-f] slave devices -.fi -.in -2 - -.SH IOCTLS -.sp -.LP -The standard set of \fBtermio ioctl\fRs are supported by the slave device. -None of the bits in the \fBc_cflag\fR word have any effect on the -pseudo-terminal, except that if the baud rate is set to \fBB0\fR, it will -appear to the process on the controller device as if the last process on the -slave device had closed the line; thus, setting the baud rate to \fBB0\fR has -the effect of ``hanging up'' the pseudo-terminal, just as it has the effect of -``hanging up'' a real terminal. -.sp -.LP -There is no notion of ``parity'' on a pseudo-terminal, so none of the flags in -the \fBc_iflag\fR word that control the processing of parity errors have any -effect. Similarly, there is no notion of a ``break'', so none of the flags that -control the processing of breaks, and none of the \fBioctl\fRs that generate -breaks, have any effect. -.sp -.LP +manipulating the manager device of the pseudo-terminal. +.Pp +The manager and the subsidiary devices of the pseudo-terminal are tightly +connected. +Any data written on the manager device is given to the subsidiary device as +input, as though it had been received from a hardware interface. +Any data written on the subsidiary terminal can be read from the manager device +.Pq "rather than being transmitted from a UAR" . +.Pp +The driver is statically configured to provide 48 pseudo-terminal pairs. +Software that requires dynamic pseudo-terminal devices, or a greater number +of devices, must be converted to use +.Xr ptm 7D . +.Sh IOCTLS +The standard set of +.Xr termio 7I +ioctls are supported by the subsidiary device. +None of the bits in the +.Fa c_cflag +field have any effect on the pseudo-terminal, except that if the baud rate is +set to +.Dv B0 , +it will appear to the process on the manager device as if the last process on +the subsidiary device had closed the line; thus, setting the baud rate to +.Dv B0 +has the effect of +.Dq hanging up +the pseudo-terminal, just as it has the effect of +.Dq hanging up +a real terminal. +.Pp +There is no notion of +.Dq parity +on a pseudo-terminal, so none of the flags in the +.Fa c_iflag +field that control the processing of parity errors have any +effect. +Similarly, there is no notion of a +.Fa break , +so none of the flags that control the processing of breaks, and none of the +ioctls that generate breaks, have any effect. +.Pp Input flow control is automatically performed; a process that attempts to write -to the controller device will be blocked if too much unconsumed data is -buffered on the slave device. The input flow control provided by the -\fBIXOFF\fR flag in the \fBc_iflag\fR word is not supported. -.sp -.LP -The delays specified in the \fBc_oflag\fR word are not supported. -.sp -.LP -As there are no modems involved in a pseudo-terminal, the \fBioctl\fRs that -return or alter the state of modem control lines are silently ignored. -.sp -.LP -A few special \fBioctl\fRs are provided on the controller devices of -pseudo-terminals to provide the functionality needed by applications programs -to emulate real hardware interfaces: -.sp -.ne 2 -.na -\fB\fBTIOCSTOP\fR\fR -.ad -.RS 14n -The argument is ignored. Output to the pseudo-terminal is suspended, as if a -\fBSTOP\fR character had been typed. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCSTART\fR\fR -.ad -.RS 14n -The argument is ignored. Output to the pseudo-terminal is restarted, as if a -\fBSTART\fR character had been typed. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCPKT\fR\fR -.ad -.RS 14n -The argument is a pointer to an \fBint\fR. If the value of the \fBint\fR is -non-zero, \fIpacket\fR mode is enabled; if the value of the \fBint\fR is zero, -packet mode is disabled. When a pseudo-terminal is in packet mode, each -subsequent \fBread\fR(2) from the controller device will return data written on -the slave device preceded by a zero byte (symbolically defined as -\fB\fR\fBTIOCPKT_DATA\fR\fB), \fR or a single byte reflecting control status -information. In the latter case, the byte is an inclusive-or of zero or more -of the bits: -.sp -.ne 2 -.na -\fB\fBTIOCPKT_FLUSHREAD\fR\fR -.ad -.RS 22n -whenever the read queue for the terminal is flushed. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCPKT_FLUSHWRITE\fR\fR -.ad -.RS 22n -whenever the write queue for the terminal is flushed. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCPKT_STOP\fR\fR -.ad -.RS 22n -whenever output to the terminal is stopped using ^S. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCPKT_START\fR\fR -.ad -.RS 22n -whenever output to the terminal is restarted. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCPKT_DOSTOP\fR\fR -.ad -.RS 22n -whenever \fBXON/XOFF\fR flow control is enabled after being disabled; it is -considered ``enabled'' when the \fBIXON\fR flag in the \fBc_iflag\fR word is -set, the \fBVSTOP\fR member of the \fBc_cc\fR array is ^S and the \fBVSTART\fR -member of the \fBc_cc\fR array is ^Q. -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCPKT_NOSTOP\fR\fR -.ad -.RS 22n -whenever \fBXON/XOFF\fR flow control is disabled after being enabled. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fBTIOCREMOTE\fR\fR -.ad -.RS 14n -The argument is a pointer to an \fBint\fR. If the value of the \fBint\fR is -non-zero, \fIremote\fR mode is enabled; if the value of the \fBint\fR is zero, -remote mode is disabled. This mode can be enabled or disabled independently of -packet mode. When a pseudo-terminal is in remote mode, input to the slave -device of the pseudo-terminal is flow controlled and not input edited -(regardless of the mode the slave side of the pseudo-terminal). Each write to -the controller device produces a record boundary for the process reading the -slave device. In normal usage, a write of data is like the data typed as a -line on the terminal; a write of 0 bytes is like typing an \fBEOF\fR character. -Note: this means that a process writing to a pseudo-terminal controller in -\fIremote\fR mode must keep track of line boundaries, and write only one line -at a time to the controller. If, for example, it were to buffer up several -\fBNEWLINE\fR characters and write them to the controller with one -\fBwrite()\fR, it would appear to a process reading from the slave as if a -single line containing several \fBNEWLINE\fR characters had been typed (as if, -for example, a user had typed the \fBLNEXT\fR character before typing all but -the last of those \fBNEWLINE\fR characters). Remote mode can be used when doing -remote line editing in a window manager, or whenever flow controlled input is -required. -.RE - -.SH EXAMPLES -.sp -.in +2 -.nf -#include <fcntl.h> -#include <sys/termios.h> - -int fdm fds; -fdm = open("/dev/ptyp0, O_RDWR); /* open master */ -fds = open("/dev/ttyp0, O_RDWR); /* open slave */ -.fi -.in -2 - -.SH FILES -.sp -.ne 2 -.na -\fB\fB/dev/pty[p-z][0-9a-f]\fR\fR -.ad -.RS 25n -pseudo-terminal controller devices -.RE - -.sp -.ne 2 -.na -\fB\fB/dev/tty[p-z][0-9a-f]\fR\fR -.ad -.RS 25n -pseudo-terminal slave devices -.RE - -.SH SEE ALSO -.sp -.LP -\fBrlogin\fR(1), \fBrlogind\fR(1M), \fBldterm\fR(7M), \fBtermio\fR(7I), -\fBttcompat\fR(7M), -.SH NOTES -.sp -.LP -It is apparently not possible to send an \fBEOT\fR by writing zero bytes in -\fBTIOCREMOTE\fR mode. +to the manager device will be blocked if too much unconsumed data is buffered +on the subsidiary device. +The input flow control provided by the +.Dv IXOFF +flag in the +.Fa c_iflag +field is not supported. +.Pp +The delays specified in the +.Fa c_oflag +field are not supported. +.Pp +As there are no modems involved in a pseudo-terminal, the ioctls that return or +alter the state of modem control lines are silently ignored. +.Pp +A few special ioctls are provided on the manager devices of pseudo-terminals to +provide the functionality needed by applications programs to emulate real +hardware interfaces: +.Bl -tag -width Ds +.It Dv TIOCSTOP +The argument is ignored. +Output to the pseudo-terminal is suspended, as if a +.Sy STOP +character had been typed. +.It Dv TIOCSTART +The argument is ignored. +Output to the pseudo-terminal is restarted, as if a +.Sy START +character had been typed. +.It Dv TIOCPKT +The argument is a pointer to an +.Vt int . +If the value of the +.Vt int +is non-zero, +.Em packet +mode is enabled; if the value of the +.Vt int +is zero, packet mode is disabled. +When a pseudo-terminal is in packet mode, each subsequent +.Xr read 2 +from the manager device will return data written on the subsidiary device +preceded by a zero byte +.Po +symbolically defined as +.Dv TIOCPKT_DATA +.Pc , +or a single byte reflecting control status information. +In the latter case, the byte is an inclusive-or of zero or more of the bits: +.Bl -tag -width Ds +.It Dv TIOCPKT_FLUSHREAD +Whenever the read queue for the terminal is flushed. +.It Dv TIOCPKT_FLUSHWRITE +Whenever the write queue for the terminal is flushed. +.It Dv TIOCPKT_STOP +Whenever output to the terminal is stopped using +.Sy ^S . +.It Dv TIOCPKT_START +Whenever output to the terminal is restarted. +.It Dv TIOCPKT_DOSTOP +Whenever +.Em XON/XOFF +flow control is enabled after being disabled; it is +considered +.Dq enabled +when the +.Dv IXON +flag in the +.Fa c_iflag +field is set, the +.Dv VSTOP +member of the +.Fa c_cc +array is +.Sy ^S +and the +.Dv VSTART +member of the +.Fa c_cc +array is +.Sy ^Q. +.It Dv TIOCPKT_NOSTOP +Whenever +.Em XON/XOFF +flow control is disabled after being enabled. +.El +.It Dv TIOCREMOTE +The argument is a pointer to an +.Vt int . +If the value of the +.Vt int +is non-zero, +.Em remote +mode is enabled; if the value of the +.Vt int +is zero, remote mode is disabled. +This mode can be enabled or disabled independently of packet mode. +When a pseudo-terminal is in remote mode, input to the subsidiary device of the +pseudo-terminal is flow controlled and not input edited (regardless of the mode +the subsidiary side of the pseudo-terminal). +.Pp +Each write to the manager device produces a record boundary for the process +reading the subsidiary device. +In normal usage, a write of data is like the data typed as a line on the +terminal; a write of 0 bytes is like typing an +.Sy EOF +character. +Note: this means that a process writing to a pseudo-terminal manager in remote +mode must keep track of line boundaries, and write only one line at a time to +the manager. +.Pp +If, for example, it were to buffer up several newline characters and write them +to the manager with one +.Xr write 2 , +it would appear to a process reading from the subsidiary as if a single line +containing several newline characters had been typed +.Po +as if, for example, a user had typed the literal next +.Pq Sy LNEXT +character before typing all but the last of those newline characters +.Pc . +Remote mode can be used when doing remote line editing in a window manager, or +whenever flow controlled input is required. +.El +.Sh FILES +.Bl -tag -width Pa +.It Pa /dev/pty[p-r][0-9a-f] +Pseudo-terminal manager devices. +.It Pa /dev/tty[p-r][0-9a-f] +Pseudo-terminal subsidiary devices. +.El +.Sh SEE ALSO +.Xr rlogin 1 , +.Xr rlogind 1M , +.Xr posix_openpty 3C , +.Xr ptm 7D , +.Xr termio 7I , +.Xr ldterm 7M , +.Xr ttcompat 7M +.Sh NOTES +This is a legacy device and should not be used by new software. +.Pp +It is apparently not possible to send an +.Sy EOT +by writing zero bytes in +.Dv TIOCREMOTE +mode. diff --git a/usr/src/man/man7d/zcons.7d b/usr/src/man/man7d/zcons.7d index 433daddbcf..07df6b458e 100644 --- a/usr/src/man/man7d/zcons.7d +++ b/usr/src/man/man7d/zcons.7d @@ -3,73 +3,62 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH ZCONS 7D "Aug 24, 2003" -.SH NAME -zcons \- Zone console device driver -.SH DESCRIPTION -.sp -.LP -The \fBzcons\fR character driver exports the console for system zones. The -driver is comprised of two "sides:" a master side with which applications in -the global zone communicate, and a slave side, which receives I/O from the -master side. The slave side is available in the global zones. -.sp -.LP -Applications must not depend on the location of \fB/dev\fR or \fB/devices\fR -entries exported by \fBzcons\fR. Inside a zone, the \fBzcons\fR slave side is -fronted by \fB/dev/console\fR and other console-related symbolic links, which -are used by applications that expect to write to the system console. -.sp -.LP -The \fBzcons\fR driver is Sun Private, and may change in future releases. -.SH FILES -.sp -.ne 2 -.na -\fB\fB/dev/zcons/<\fIzonename\fR>/masterconsole\fR \fR -.ad -.sp .6 -.RS 4n -Global zone master side console for zone <\fIzonename\fR>. -.RE - -.sp -.ne 2 -.na -\fB\fB/dev/zcons/<\fIzonename\fR>/slaveconsole\fR \fR -.ad -.sp .6 -.RS 4n -Global zone slave side console for zone <\fIzonename\fR>. -.RE - -.sp -.ne 2 -.na -\fB\fB/dev/zconsole\fR \fR -.ad -.sp .6 -.RS 4n -Non-global zone console (slave side). -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(5) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ - Interface Stability Sun Private -.TE - -.SH SEE ALSO -.sp -.LP -\fBzoneadm\fR(1M), \fBzonecfg\fR(1M), \fBattributes\fR(5), \fBzones\fR(5) +.\" Copyright 2022 Oxide Computer Company +.Dd February 5, 2022 +.Dt ZCONS 7D +.Os +.Sh NAME +.Nm zcons +.Nd Zone console device driver +.Sh DESCRIPTION +The +.Nm zcons +character driver exports the console for system zones. +The driver is fundamentally similar to a pseudo-terminal device, and is thus +comprised of two sides: +.Bl -bullet +.It +a manager device, which applications in the global zone can open for +communication +.It +a subsidiary device, which processes in the non-global zone can write to, to +communicate with global zone management applications +.El +.Pp +Applications must not depend on the location of +.Pa /dev +or +.Pa /devices +entries exposed by +.Nm zcons +in the global zone. +Inside a non-global zone, the +.Nm zcons +subsidiary device is fronted by +.Pa /dev/console +and other console-related symbolic links, which are used by applications that +expect to write to the system console. +.Pp +The +.Nm +driver is not a +.Sy Committed +interface, and may change at any time. +.Sh FILES +.Bl -tag -width Pa +.It Pa /dev/zcons/ZONENAME/globalconsole +Global zone console manager device for zone +.Sy ZONENAME . +.It Pa /dev/zcons/ZONENAME/zoneconsole +Global zone console subsidiary device for zone +.Sy ZONENAME . +.It Pa /dev/zconsole +Non-global zone console (subsidiary device). +.El +.Sh INTERFACE STABILITY +.Sy Uncommitted +.Sh SEE ALSO +.Xr zoneadm 1M , +.Xr zonecfg 1M , +.Xr attributes 5 , +.Xr zones 5 |