1 '\" te

   2 .\"  Copyright 1992 Sun Microsystems
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH PTS 7D "Aug 21, 1992"
   7 .SH NAME
   8 pts \- STREAMS pseudo-tty slave driver
   9 .SH DESCRIPTION
  10 .sp
  11 .LP
  12 The pseudo-tty subsystem simulates a terminal connection, where the master side
  13 represents the terminal and the slave represents the user process's special
  14 device end point. In order to use the pseudo-tty subsystem, a node for the
  15 master side driver \fB/dev/ptmx\fR and N nodes for the slave driver (N is
  16 determined at installation time) must be installed. The names of the slave
  17 devices are \fB/dev/pts/M\fR where \fBM\fR has the values 0 through N-1. When
  18 the master device is opened, the corresponding slave device is automatically
  19 locked out. No user may open that slave device until its permissions are
  20 adjusted and the device unlocked by calling functions \fBgrantpt\fR(3C) and
  21 \fBunlockpt\fR(3C). The user can then invoke the open system call with the name
  22 that is returned by the \fBptsname\fR(3C) function. See the example below.
  23 .sp
  24 .LP
  25 Only one open is allowed on a master device. Multiple opens are allowed on the
  26 slave device. After both the master and slave have been opened, the user has
  27 two file descriptors which are end points of a full duplex connection composed
  28 of two streams automatically connected at the master and slave drivers. The
  29 user may then push modules onto either side of the stream pair. The user needs
  30 to push the \fBptem\fR(7M) and \fBldterm\fR(7M) modules onto the slave side of
  31 the pseudo-terminal subsystem to get terminal semantics.

  32 .sp
  33 .LP
  34 The master and slave drivers pass all messages to their adjacent queues. Only
  35 the \fBM_FLUSH\fR needs some processing. Because the read queue of one side is
  36 connected to the write queue of the other, the \fBFLUSHR\fR flag is changed to
  37 the \fBFLUSHW\fR flag and vice versa. When the master device is closed an
  38 \fBM_HANGUP\fR message is sent to the slave device which will render the device
  39 unusable. The process on the slave side gets the errno \fBEIO\fR when
  40 attempting to write on that stream but it will be able to read any data
  41 remaining on the stream head read queue. When all the data has been read, read
  42 returns 0 indicating that the stream can no longer be used. On the last close
  43 of the slave device, a 0-length message is sent to the master device. When the
  44 application on the master side issues a \fBread()\fR or \fBgetmsg()\fR and 0 is
  45 returned, the user of the master device decides whether to issue a
  46 \fBclose()\fR that dismantles the pseudo-terminal subsystem. If the master
  47 device is not closed, the pseudo-tty subsystem will be available to another
  48 user to open the slave device. Since 0-length messages are used to indicate
  49 that the process on the slave side has closed and should be interpreted that
  50 way by the process on the master side, applications on the slave side should
  51 not write 0-length messages. If that occurs, the write returns 0, and the
  52 0-length message is discarded by the  \fBptem\fR module.

  53 .sp
  54 .LP
  55 The standard STREAMS system calls can access the pseudo-tty devices. The slave
  56 devices support the \fBO_NDELAY\fR and \fBO_NONBLOCK\fR flags.














  57 .SH EXAMPLES
  58 .sp
  59 .in +2
  60 .nf
  61 int    fdm fds;
  62 char   *slavename;
  63 extern char *ptsname();
  64 
  65 fdm = open("/dev/ptmx", O_RDWR);  /* open master */
  66 grantpt(fdm);                     /* change permission of       slave */
  67 unlockpt(fdm);                    /* unlock slave */
  68 slavename = ptsname(fdm);         /* get name of slave */
  69 fds = open(slavename, O_RDWR);    /* open slave */
  70 ioctl(fds, I_PUSH, "ptem");       /* push ptem */
  71 ioctl(fds, I_PUSH, "ldterm");     /* push ldterm*/
  72 .fi
  73 .in -2
  74 
  75 .SH FILES
  76 .sp

  78 .na
  79 \fB\fB/dev/ptmx\fR\fR
  80 .ad
  81 .RS 14n
  82 master clone device
  83 .RE
  84 
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fB/dev/pts/M\fR\fR
  89 .ad
  90 .RS 14n
  91 slave devices (M = 0 -> N-1)
  92 .RE
  93 
  94 .SH SEE ALSO
  95 .sp
  96 .LP
  97 \fBgrantpt\fR(3C), \fBptsname\fR(3C), \fBunlockpt\fR(3C), \fBldterm\fR(7M),
  98 \fBptm\fR(7D), \fBptem\fR(7M)
  99 .sp
 100 .LP
 101 \fISTREAMS Programming Guide\fR

   1 '\" te
   2 .\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
   3 .\"  Copyright 1992 Sun Microsystems
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH PTS 7D "Feb 29, 2020"
   8 .SH NAME
   9 pts \- STREAMS pseudo-tty slave driver
  10 .SH DESCRIPTION
  11 .sp
  12 .LP
  13 The pseudo-tty subsystem simulates a terminal connection, where the master side
  14 represents the terminal and the slave represents the user process's special
  15 device end point. In order to use the pseudo-tty subsystem, a node for the
  16 master side driver \fB/dev/ptmx\fR and N nodes for the slave driver (N is
  17 determined at installation time) must be installed. The names of the slave
  18 devices are \fB/dev/pts/M\fR where \fBM\fR has the values 0 through N-1. When
  19 the master device is opened, the corresponding slave device is automatically
  20 locked out. No user may open that slave device until its permissions are
  21 adjusted and the device unlocked by calling functions \fBgrantpt\fR(3C) and
  22 \fBunlockpt\fR(3C). The user can then invoke the open system call with the name
  23 that is returned by the \fBptsname\fR(3C) function. See the example below.
  24 .sp
  25 .LP
  26 Only one open is allowed on a master device. Multiple opens are allowed on the
  27 slave device. After both the master and slave have been opened, the user has
  28 two file descriptors which are end points of a full duplex connection composed
  29 of two streams automatically connected at the master and slave drivers. The
  30 user may then push modules onto either side of the stream pair. Unless
  31 compiled in strict XPG4v2 mode (see below), the consumer needs to push the
  32 \fBptem\fR(7M) and \fBldterm\fR(7M) modules onto the slave side of the
  33 pseudo-terminal subsystem to get terminal semantics.
  34 .sp
  35 .LP
  36 The master and slave drivers pass all messages to their adjacent queues. Only
  37 the \fBM_FLUSH\fR needs some processing. Because the read queue of one side is
  38 connected to the write queue of the other, the \fBFLUSHR\fR flag is changed to
  39 the \fBFLUSHW\fR flag and vice versa. When the master device is closed an
  40 \fBM_HANGUP\fR message is sent to the slave device which will render the device
  41 unusable. The process on the slave side gets the errno \fBEIO\fR when
  42 attempting to write on that stream but it will be able to read any data
  43 remaining on the stream head read queue. When all the data has been read, read
  44 returns 0 indicating that the stream can no longer be used. On the last close
  45 of the slave device, a 0-length message is sent to the master device. When the
  46 application on the master side issues a \fBread()\fR or \fBgetmsg()\fR and 0 is
  47 returned, the user of the master device decides whether to issue a
  48 \fBclose()\fR that dismantles the pseudo-terminal subsystem. If the master
  49 device is not closed, the pseudo-tty subsystem will be available to another
  50 user to open the slave device. Since 0-length messages are used to indicate
  51 that the process on the slave side has closed and should be interpreted that
  52 way by the process on the master side, applications on the slave side should
  53 not write 0-length messages. Unless the application is compiled in strict
  54 XPG4v2 mode (see below) then any 0-length messages written on the slave side
  55 will be discarded by the \fBptem\fR module.
  56 .sp
  57 .LP
  58 The standard STREAMS system calls can access the pseudo-tty devices. The slave
  59 devices support the \fBO_NDELAY\fR and \fBO_NONBLOCK\fR flags.
  60 .SH STRICT XPG4v2 MODE
  61 .sp
  62 XPG4v2 requires that open of a slave pseudo terminal device provides the
  63 process with an interface that is identical to the terminal interface (without
  64 having to explicitly push any modules to achieve this). It also requires that
  65 0-length messages written on the slave side will be propagated to the master.
  66 .sp
  67 Experience has shown, however, that most software does not expect slave pty
  68 devices to operate in this manner and therefore this XPG4v2-compliant
  69 behaviour is disabled in illumos by default.
  70 .sp
  71 To enable it for an application, the \fB_XPG4_2\fR and \fB_STRICT_SYMBOLS\fR
  72 macros must be set during compilation and the application must be linked with
  73 \fBvalues-xpg4.o\fR or \fBvalues-xp6.o\fR.
  74 .SH EXAMPLES
  75 .sp
  76 .in +2
  77 .nf
  78 int    fdm fds;
  79 char   *slavename;
  80 extern char *ptsname();
  81 
  82 fdm = open("/dev/ptmx", O_RDWR);  /* open master */
  83 grantpt(fdm);                     /* change permission of       slave */
  84 unlockpt(fdm);                    /* unlock slave */
  85 slavename = ptsname(fdm);         /* get name of slave */
  86 fds = open(slavename, O_RDWR);    /* open slave */
  87 ioctl(fds, I_PUSH, "ptem");       /* push ptem */
  88 ioctl(fds, I_PUSH, "ldterm");     /* push ldterm*/
  89 .fi
  90 .in -2
  91 
  92 .SH FILES
  93 .sp

  95 .na
  96 \fB\fB/dev/ptmx\fR\fR
  97 .ad
  98 .RS 14n
  99 master clone device
 100 .RE
 101 
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fB/dev/pts/M\fR\fR
 106 .ad
 107 .RS 14n
 108 slave devices (M = 0 -> N-1)
 109 .RE
 110 
 111 .SH SEE ALSO
 112 .sp
 113 .LP
 114 \fBgrantpt\fR(3C), \fBptsname\fR(3C), \fBunlockpt\fR(3C), \fBldterm\fR(7M),
 115 \fBptm\fR(7D), \fBptem\fR(7M), \fBstandards\fR(5)
 116 .sp
 117 .LP
 118 \fISTREAMS Programming Guide\fR